Nothing But .Net

Editors Note: This is the first in our new blog series we are entitling 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.

Force.com offers several API’s for accessing data on their servers, but one of the oldest and most commonly used is the SOAP API. The first step in using the SOAP API is to download a WSDL file and then create a reference within the application.  For .NET users, the reference can either be a web reference or a service reference. As with most things, there are pros and cons to using each method. I will tell you what those pros and cons are so that you can make a decision about which method is best for your particular application.

Creating a Service Reference

Creating a service reference makes use of the newer Windows Communication Foundation (WCF) framework. This method uses configuration files to define both the binding and the configuration and therefore is loosely coupled from the service implementation. Microsoft recommends that all XML Web service clients are created using this technology.

To create the service reference, download the WSDL file from Salesforce and in Visual Studio 2013 go to Project and Add Service Reference (see Figure 1). From here, you need to enter the path to the WSDL file and click GO. You should also specify a name to use as the namespace. This will be referenced from within your code.

Figure 1: Dialog to add a WCF service reference to a .NET project

Once the service reference is added, you can add code to login to the server and query, create, update or delete Salesforce objects. For specific instructions on how to do this, refer to this article on Consuming Force.com SOAP and REST services from .Net applications.

Creating a Web Reference

Creating a web reference utilizes the .NET 2.0 Web Services technology and is considered much simpler and outdated. To do this, you will still need to download a WSDL, but to add a web reference using Visual Studio 2013, you will have to perform a few additional steps. You should go to Projects and Add Service Reference and then from here click the Advanced button at the bottom of the dialog (see Figure 2).

Figure 2: Click Advanced from Add Service Reference to add a Web Reference

This will bring up the Service Reference Settings dialog and from there you can click Add Web Reference (see Figure 3).

Figure 3: Service Reference Settings Dialog is used to add a Web Reference.

Finally, you can add a web reference by entering a path to the WSDL file and clicking the arrow next to URL (see Figure 4). You will then specify a web reference name and click Add Reference to add it to your Visual Studio 2013 project.

Figure 4: Add Web Reference dialog in Visual Studio 2013.

For more information about the specific code you should use to access the SOAP API using this method, refer to this tutorial on Integrating Force.com with Microsoft .NET.

Which Method Should I Use?

I originally was going to write this article about how you should always use a service reference, since it is the method that Microsoft recommends when working with SOAP API’s. It also exposes more functionality in terms of the additional headers it makes available. I assumed it would be a faster way to access Salesforce data and so I was surprised when a benchmark test I created revealed a different result.

I created a console application using Visual Studio 2013 that created both a service and a web reference to the same WSDL file. Each reference was used to login to the Salesforce server and create a simple case. Using the web reference method, the process takes an average of less than 2 seconds. Using the service reference, that same process took an average of more than 18 seconds.

That was not what I was expecting, but as you can see from this Stackoverflow post, I am not the only person to observe this result. According to the accepted answer in the post, the reason for the delay is due to a call to the Channel Factory Class.  This object should be cached and reused on subsequent calls, thus making them faster.

I confirmed this behavior as well. And the slow result does only apply to the first call. Subsequent calls are much faster, but this applies both to the web reference and the service reference method (see results of multiple calls in Figure 5).

Figure 5: Multiple calls to benchmark application reveal that second calls for both methods are much faster.

As to the question of which method you should use, I think it depends on the needs and architecture of your application. If you have an application that is already using the web reference method and you have no need to utilize one of the additional headers easily exposed with the WCF method, then I would not change a thing. If you are creating a brand new application that access the SOAP API and you know there is no chance you will ever need to modify one of the headers, then I would go with the web reference method.

If however, your application does need to access the headers, then I would consider using the service reference method. It does make accessing the headers a little easier. Just make sure that your application takes into account the slow start time of loading the WCF reference. I would also suggest that you take a look at this MSDN article which shows how to use the XmlSerializer to improve the startup time of WCF client applications.