Editors Note: This is the second post in our blog series Nothing But .Net. Sara Morgan, our resident expert, is an independent Software Developer and long-time .NET programmer who has recently been wooed into the world of Force.com development. She recently filmed her first introductory course covering Visualforce for Lynda.com.
In January 2014, Salesforce announced the release of two new Open Source Salesforce Toolkits for .NET. One accessed the Force.com REST API and the other the Chatter REST API. The new toolkits are just a starting point and they are still a work in progress. However, Salesforce made the very wise decision to make them available as open source and therefore encourage the community to contribute toward their maturation. This article will cover why you would want to use the new toolkits, as well as go over some issues that have been uncovered since their release. It will end with a discussion of what you can do to help expand and enhance the toolkits.
Why Use the New Force.com Toolkit for .Net?
Both toolkits were built using the .NET Framework Portable Class Library project, which means the toolkits can be used to build Windows 7/8/8.1 applications, along with Windows Phone 8, Silverlight 5, and iOS/Android applications using Xamarin and Mono.NET. They also make use of the Aync and Await patterns for asynchronous programming and can be installed as NuGet packages. This means they are super fast and easy to install.
There are plenty of reasons to use the new toolkit when accessing the REST API using oAuth 2.0, but my favorite is the fact that you have to write less code. The REST API returns and accepts data in XML or JSON format. This data must be serialized and de-serialized and even though this process is easier using the new HttpClient library that was made available in .NET 4.5, it is even simpler using the new Toolkits.
If you have not yet seen the toolkits, I suggest you check out the GitHub repository, which includes documentation as well as four sample applications. The sample applications include a simple console application which uses the username-password flow, as well as Windows 8 and Windows Phone 8 applications. There is also an MVC 5 application that demonstrates how to authenticate using the web-server authentication flow.
Supported Visual Studio Versions
The new toolkits take advantage of libraries introduced in .NET 4.5 and therefore cannot be used in Visual Studio projects prior to Visual Studio 2012. If you need to work with the Salesforce REST API and you are using an earlier version of Visual Studio (such as Visual Studio 2010), you will need to use an alternative method and deal with all the exhaustive JSON serialization and de-serialization yourself.
If you find yourself in this unfortunate position, I suggest you check out the last part of this article on the DeveloperForce website. It offers step by step instructions for how to setup your .NET Developer environment and goes over what you need to do to work with the REST API. However, if you are using Visual Studio 2012 or higher and need to connect to the REST API, I suggest you either use the new Force.com Toolkit or utilize the HttpClient class, as described in this Salesforce Developers article.
Installing the NuGet Packages
The Force.com toolkits come packaged as three NuGet packages available online through Visual Studio’s NuGet Package Manager. There are additional packages that include code templates to give you a jump start to create your application (as seen in Figure 1) however the main toolkit packages are:
- DeveloperForce.Chatter – Allows you to interact with the Chatter REST APIs.
- DeveloperForce.Force – Allows you to interact with the Force.com REST APIs.
- DeveloperForce.Common – Central library that provides authentication and other common functionality.
If you happen to be working with an Express version of Visual Studio 2012 or 2013, you may encounter a problem when trying to install the NuGet Packages. The NuGet packages for the Force.com toolkit require that you use NuGet Package Manager 2.8 or higher. As of the printing of this article, Visual Studio Express versions come installed with NuGet 2.7 and thus must be upgraded before you can install the Force.com packages. This can be done by going to the Updates tab in Manage NuGet packages.
Authenticating to a Sandbox
The Force.com toolkit provides two overloaded versions of the UsernamePasswordAsync method used to authenticate a user. These versions allow you to specify the optional userAgent and tokenRequestEndpointURL parameters. If you are logging into a production or developer instance of Salesforce, then you do not need to include these additional parameters. In that case, you can authenticate using the following code:
If you are authenticating from a Sandbox, then you will need to make sure that your username includes the .sandbox_name at the end (just like you would specify if you were logging into a Sandbox normally). You will also need to include the two additional parameters and make sure the url you specify begins with “test” and not “login”. For example:
If you are authenticating to a sandbox using the Web-Server authentication flow, you will use first login with a formatted url that must include the “test” prefix for the authorization endpoint URL. For example:
Known Issues and Enhancements on the Way
Since the toolkits introduction back in January, several issues have been reported on the GitHub Repository. Most of these issues have been resolved, but there are still a few outstanding issues. They involve creating a Windows store app package and executing SOQL queries with special characters.
If you encounter any errors using the new toolkit, I suggest that you report them here on the GitHub website. The website also lists upcoming enhancements, which at this time include a new WebServerAsync overload and a QueryAll method.
What you can do to help
One of the biggest drawbacks to using the new toolkits is that they are new and do not support all the API’s that Salesforce offers. This is where the community really needs to step in. There is a big need for more people to get involved by downloading the kit, using it and reporting any issues found. There is also a need for more sample applications and support for additional API’s and oAuth authentications flows. Currently, the new toolkit only supports two of the six available authentication flows: Username-Password and Web-Server.
I have been a .NET developer for many years now and I know how passionate that community of developers can be. If you work with .NET and Salesforce, this is your big chance. Consider downloading and contributing to the open source code. Get involved and help to build a really great set of .NET toolkits for Force.com.