The Force.com platform tightly integrates with Microsoft .NET technologies via the Force.com SOAP API, which lets you access and manipulate your data and functionality in the Force.com cloud. This functionality can be executed on any Microsoft.NET supported platform including but not limited to web applications running IIS, Windows desktop or server applications, SharePoint services, and SQL Server programmability.
This article provides details on the various options to integrate the Force.com platform with Microsoft .NET. After reading this article, you will have a foundation of methodologies, best practices and code samples to leverage the Force.com SOAP API across any Microsoft .NET platform.
Force.com can be tightly integrated with any Microsoft .NET based application through the Force.com SOAP Application Programming Interface (API). By exposing, consuming and editing an organization's Force.com data through the API, Microsoft .NET developers can leverage existing toolsets and programming language knowledge, enabling them to develop a Force.com integrated application rapidly and efficiently.
While Visual Basic .NET and C# are the most widely used .NET programming languages, an application that uses the Force.com SOAP API can be written in any .NET compatible programming language. Microsoft's and salesforce.com's adherence to industry-accepted web service standards allows developers to use familiar coding methodologies and techniques with little additional training. Developers can also save time in developing their application by leveraging the existing business logic and security model provided out of the box through the use of the API.
There are of course many forms of integration. For example, you may choose to build and run your Microsoft apps on an intranet, and then bridge to a Force.com application using some kind of single sign on (SSO) methodology, such as SAML. This can easily be done, and you can find the details in Single Sign-On with SAML on Force.com. This article focuses primarily on an integration based around the data within a Force.com application - something that will allow you to react to changes to that data, or insert or remove on Force.com from your local Microsoft application.
As with other code bases written in .NET, an integrated Force.com application can be tailored to run on any .NET support platform. The Microsoft .NET Framework is included with all major Microsoft operating systems, desktop and server, as well as Microsoft's 3 major application platforms: SQL Server, Internet Information Services, and SharePoint Services. Thus, the Force.com API can be accessed and consumed across any of the aforementioned platforms with little to no additional development effort.
In order for a .NET application to integrate with Force.com, a reference to the SOAP API must be added to the application within Visual Studio. This reference is established through the use of a WSDL file generated from the Force.com platform. A WSDL file is an XML file that describes how a SOAP-based web service functions, how an application can communicate with the web service, and the operations allowed to be conducted within the SOAP API.
In other words, the WSDL provides a description of the bridge between your Microsoft application, and a Force.com application running in a Force.com environment (or organization).
Force.com offers several types of WSDLs to consume, depending on the requirements of the application being developed and the audience for whom the application is developed. Regardless of the WSDL used, the Force.com API enforces several concepts across all WSDL types consistent with the World Wide Web Consortium's (W3C) accepted standards including, but not limited to: how to communicate with the web service, how to authenticate with the web service, and what operations are allowed with the web service.
The Force.com platform offers many WSDL types for API access, with the primary WSDLs being the Enterprise, Partner and Apex Class WSDLs. Choosing the correct WSDL will depend on the type of application being developed.
The important point here is if you want to create an application that can run against any customer application running on Force.com, then you probably want to use the Partner WSDL. For example, a generic data tool may have this requirement. However, if you have more control over the application you want to integrate with, and understand how often its data model changes, then the Enterprise WSDL may be more beneficial - the strongly typed representation is very useful during coding.
All of these WSDLs are automatically generated and maintained by the platform. For example, if you create a new object it will be automatically be made available within the partner WSDL. Likewise, if you create a new Apex class that functions as a web service, its WSDL will be automatically made available.
WSDL files are retrieved via the standard user interface in an organization by logging in and navigating to Setup > App Setup > Develop > API. Choose the appropriate WSDL and download the file to a location accessible to your development environment.
The steps to add a web reference will vary, depending on the edition of Visual Studio used as well as the .NET Framework for which the application is developed. Visual Studio 2008 and newer now reference 'Add Service Reference' to projects and have deprecated the 'Add Web Reference' term. Regardless of terminology or versions, the steps to add a reference to your WSDL file are in essence the same across all versions of Visual Studio:
1. Open the add reference dialog box via the 'Add Service Reference' or 'Add Web Reference' command from the Project menu.
2. Provide location of WSDL file in order to create the reference. Locations can take multiple forms including HTTP address. In this case, the location will point to a location on your local hard drive or network share.
3. Establish name of reference to be used in your application. This is referred to as either the Web reference name or Namespace. Regardless of terminology, this name will become the established namespace for all references to objects, properties and methods enclosed in the WSDL file.
4. Confirm the reference has been added by viewing the reference in the Solution Explorer in Visual Studio.
That's it! You're now ready to start using the reference and interacting with apps on Force.com.
Now that you have your reference, you need to authenticate with the Force.com servers. This determines which organization you get access to, and which data. After that, you'll be in a position to add or query data. The following sections look at this process in a lot more detail.
Before using any functionality or accessing any data through the Force.com platform, a valid username and password must be passed to the API in order to authenticate and establish a secure session with the API. Only then will the .NET application be allowed to interact with the Force.com API. Consideration should be given during the design of your application as to how the application authenticates against the API.
All security and subsequent operations can be conducted under the context of a single service account, established solely for the purpose of API access for you application. Alternatively, individual users of the .NET application can conduct operations under the context of their individual Force.com user account. Either option will have significant impacts on the architecture of your application and is beyond the scope of this document.
Regardless of the authentication method used, there are security considerations to keep in mind when developing an application:
Let's walk through the code of a basic app to make this more concrete.
Integrating .NET with Force.com can be accomplished following a few simple steps. All samples are written in C#.
1. Capture a user name and password: These values can be hardcoded as part of your application's .config files, stored in a database for retrieval, or passed to the API via values collected from the application user. In this example, the username and password are simply hard coded as string variables within the application.
2. Login to the Force.com API: Once the username and password values are established, they are passed to the API to determine if they are valid. As part of this validation, a binding to the API is established by instantiating an SforceService object. Once the binding is established, the result of the login attempt is returned in the form of a LoginResult object. Best practices also dictate this login attempt be wrapped in a try catch block to allow for graceful handling of any exceptions that may be thrown as part of the login process.
3. Establish the Session: Once a successful login has been executed, it is necessary to establish a valid Force.com API session by setting the endpoint URL for your binding object to communicate with as well as set any required values to create a valid session header.
That's it! You have just successfully logged in to the Force.com API and created a valid session to conduct further operations on the Force.com platform. The SfdcBinding variable now contains the end point URL where further web service interactions will take place, as well as the session. The following code will use this to retrieve and create data on Force.com from .NET.
Now that a valid session has been established, Force.com data can be queried from the platform and consumed in your .NET application. Queries are executed against the Force.com API using SOQL (Salesforce.com Object Query Language).
SOQL is similar to SQL and can be used in a similar manner to specify precisely the data your .NET application requires to consume. Results from the SOQL sent to the API are stored in a QueryResult object, which in essence is simply an array of records returned from the API that can be handled similarly to a dataset or data reader.
1. Instantiate a QueryResult to hold the results: There are numerous options that can be set via the QueryOptions object. These options are beyond the scope of this document but can be found in the Force.com Web Services API Developer's Guide.
2. Construct the Query: Queries can be built on the fly based on other interactions within your .NET application or they can be predefined if the query is executing in a more controlled, predictable piece of code. If the developer has any level of familiarity with SQL, one will be able to construct SOQL queries with ease. In this example, the Force.com API will be queried for a lead record with an email address of email@example.com. Our application requires the lead record's first name, last name and phone number.
3. Execute the Query: Once the QueryResult object and SOQL query string have been established, it's time to execute the query against the API.
4. Consume the Results: Now that the query has been executed, we must check to see if any results were returned. If results were returned from the API, our application can now consume the records, otherwise the lack of records returned can be handled gracefully to provide meaningful feedback to the calling application. In this case, we are going to assume that a single record was returned by our query.
You've just consumed your first piece of Force.com data in your .NET application! Note how the the result is typecast to a Lead object - a result of this example using the Enterprise WSDL which is strongly typed. If it used the Partner WSDL, the code will be considerably more verbose. In particular, it would use SObjectResult type that can be used to represent any concrete type, and you have to use generic field methods (passing in as a parameter the name of the field on which you want to operate) to access or manipulate field data.
The Force.com API supports all CRUD operations. We've just covered a walkthrough for ‘R', reading data from the API. This walkthrough covers the basics or creating data on the Force.com platform using the create() call as well as introduces the SaveResult object.
1. Instantiate the Object Being Created: Before we can execute a create() against the API, we must establish the type of object being created. In this case, we will create a new lead.
2. Establish Field Values and Object Properties: Like any .NET variable, there are numerous ways to establish the values to pass to the create() call. In this case, the values are simply hard coded as variable values. However, a more practical use would include capturing the values from a user via a web form or desktop application. Once the values have been established, the object properties must be set before the object is created. Your application should have its own layer of validation and business logic to ensure the values being set are validated.
3. Execute Create Call and Capture Save Results: Now that the object has been instantiated and properties have been set, we can now execute the create() call against the API. The results of the create call are stored in a SaveResult object to allow your application to gracefully handle the results, regardless of success or failure. Note that both the SaveResult and subject objects are arrays and are thus built to handle multiple records simultaneously. In this case, we are operating on a single record only.
4. Working with the Results: The create call will obviously result in success or failure. Successful create calls will return the ID value of the resultant record created. Fortunately, the API is built to allow us to handle both scenarios within our application.
Congratulations! You have just successfully created a new record on the Force.com platform from a .NET application.
Now that we have an existing record, subsequent updates can be made to that record through your application. In order for the Force.com platform to execute a successful update call, the ID value of the object must be provided.
1. Create the Object to Update: Like a create call, an update call can operate on a single record or multiple records. In this case, we will operate on a single record.
2. Establish Values: Once the object to update has been created, the values to be updated must be established. The ID of the object must be set in order to execute the update so the API know which record to update. Failure to provide the ID or providing an invalid ID will result in an error.
3. Execute the Update: Once the values we wish to change have been established, the update is executed and results are captured in a SaveResult object.
4. Working with the Results: Like the results of a create call, the results of an update will contain an array of results equal to the array size of records in the update call. The results can be utilized in the same manner as a create call results in order to allow your application to handle both a successful and failed update.
As is evident in the update and create calls, the Force.com API establishes a very consistent method of interacting with your application, allowing for rapid development and reuse of code.
Deleting data on the Force.com API is very simple. The delete operation of your SforceService binding accepts an array of ID values as a parameter. Instead of populating a SaveResult object, the Force.com API populates the results of a delete call in a DeleteResult object.
1. Establish the IDs: A string array must be established containing the IDs of the records to be deleted.
2. Execute Delete Call: Once the array of IDs has been established, the array is passed as a parameter to the delete call of the SforceService object established.
3. Capture Delete Results: Similar to a create and update call, the results of the operation are stored in an array object, in this case a DeleteResult. In this example, the array will have a single value as we are only passing a single ID value to delete.
Like other applications, calls to the Force.com API will result in either success or failure. Application exceptions when using the Force.com API are handled in the same manner as a typical exception in any other .NET application and are managed through try/catch/finally blocks.
Successful calls and calls resulting in an error response from the API typically populate an array-based object. Basic responses from the API are captured in the following array objects:
All of the above result objects are handled in the same manner as an Array object in .NET. The results objects can be looped through using any standard .NET programming technique. These techniques are beyond the scope of this document.
There are several other integration methodologies possible with the Force.com API. For completeness, those API's are highlighted here to further show what is possible with the Force.com platform and Microsoft .NET.
As indicated in the introduction, you could also integrate in terms of a single sign on solution.
Establishing an integration between a .NET application and an application running on Force.com is not challenging. It requires a little planning around what type of integration is going to be made, and as a result which web service endpoint and WSDL will be invoked. After that, the actual coding of an integration is trivial - it's a matter of importing the WSDL, authenticating against the servers, and then simply writing against the API to add, remove, update or delete data.
Steve Baines has over 15 years of industry experience and currently manages his own consulting practice, specializing in Marketing Operations and Technology, application development and systems integration.