Before you can programmatically use the methods and logic available in Microsoft Dynamics CRM, you must first add the API references to your project. You can add any of the APIs by using one of the following methods:
Access the Web reference URL directly in Visual Studio 2008.
Download the WSDL definition to the file system and add the Web reference locally.
Reference the Microsoft.Crm.Sdk and Microsoft.Crm.SdkTypeProxy assemblies.
With the Web service APIs, you have a choice of referencing the service endpoint directly or connecting to an exported WSDL file. We discuss both approaches shortly. Table 3-1 lists the three Web service–based APIs available, the recommended namespace names, and where you can download the WSDL file. Even though we recommend that you use the same naming convention described in Table 3-1, you can choose whatever naming convention you prefer.
Table 3-1. Available Microsoft Dynamics CRM Web Service APIs
API Name | Namespace Name | WSDL Location |
|---|---|---|
CrmService | CrmSdk | Download from Microsoft Dynamics CRM user interface for each organization |
MetadataService | MetadataSdk | Download from Microsoft Dynamics CRM user interface for each organization |
CrmDiscoveryService | CrmSdk.Discovery | Included in the WSDL folder of the Microsoft Dynamics CRM SDK |
Table 3-2 lists the Microsoft Dynamics CRM Web service API URL locations for on-premise deployments.
Note
Microsoft Dynamics CRM Online uses a unique address for the DiscoveryService Web service: https://dev.crm.dynamics.com/mscrmservices/2007/passport/crmdiscoveryservice.asmx.
Microsoft also offers three assemblies that you can use to programmatically interact with Microsoft Dynamics CRM instead (with some benefits and constraints):
Microsoft.Crm.Sdk.dll
Microsoft.Crm.SdkTypeProxy.dll
Microsoft.Crm.Outlook.Sdk.dll
The Web service APIs can provide a dynamic, strongly typed development reference for custom entities and attributes. This provides a more robust development experience. However, you must keep the Web references up to date to utilize your new customizations with strongly typed code at compile time.
On the other hand, the assembly references wrap the Web service functionality and provide most of the core functionality (and default entity access). Further, these assemblies provide additional helper functionality. However, your code will not be able to use the strongly typed references for any schema customizations made to the system. Also, when using the assembly references, you take advantage of the Microsoft Dynamics CRM’s DynamicEntity concept (which we discuss in detail later in the chapter). By using this approach, you will have an easier time deploying common solutions across multiple and changing environments.
Tip
Are your custom entities or new attributes not appearing in Microsoft IntelliSense in Visual Studio? Make sure that you have published your changes and updated your Web reference in Visual Studio 2008. Updating the reference depends on the technique you used to reference the WSDL. If you used the URL, you can update the reference directly from Visual Studio 2008. If you referenced the file, you need to first export a new WSDL and replace the existing one before you see the change.
When developing assembly-based solutions such as plug-ins and workflow assemblies, we recommend that you reference the API assemblies instead of using the Web references. For Web development applications, you can use either the WSDL or assembly reference approach.
Microsoft built Microsoft Dynamics CRM 4.0 against the Microsoft .NET Framework 3.0. Consequently, most developers will build their solutions with Visual Studio 2008 targeted at the .NET Framework 3.0. Technically, you could also build against the .NET Framework 3.5, but then you will need to make sure that the .NET 3.5 Framework is installed on the destination server. Note that the ASP.NET version configured in Internet Information Services (IIS) will probably be 2.0.50727, but this is the run-time version of .NET. The run-time versions of the .NET Framework 3.0 and 3.5 are identical to those of the .NET Framework 2.0, so any code developed with those versions of the .NET framework will run properly on the 2.0.50727 run-time engine.
More Info
Please review the latest SDK for the most up-to-date information on support for .NET Framework versions.
The following example demonstrates how to add references for the CrmService and Microsoft.Crm.Sdk using each of the preceding techniques. You would use a similar technique for the other API references.
Adding the CrmService Web reference URL directly in your project
Create a new Console application project in Visual Studio 2008 and select the .NET 3.0 Framework.
Right-click the project, and then click Add Service Reference.
Click the Advanced button in the Add Service Reference box.
In the Service Reference Settings box, click Add Web Reference.
In the Add Web Reference dialog box, add the CrmService reference:
In the URL box, type http://<crmserver>/mscrmservices/2007/crmservice.asmx, and then click Go.
In the Web reference name box, type CrmSdk. (Note that if you are using C#, this is case sensitive.)
Click Add Reference.
Adding an on-premise CrmService service WSDL reference to your project
Open Microsoft Dynamics CRM in a Web browser, click Settings, click Customization, and then select Download Web Service Description Files.
Click the icon of the CrmService.asmx file to download. The file will open in a Web browser window.
In the Web browser, save the page to your file system as an XML file. (In Internet Explorer 7, click Page, and then click Save As.) Be sure to change the file name to end with the .xml or .wsdl extension (for example, CrmServiceWsdl.xml).
Create a new Console application project in Visual Studio 2008 and target the .NET 3.0 Framework.
Right-click the project, and then click Add Service Reference.
Click the Advanced button in the Add Service Reference box.
In the Service Reference Settings box, click Add Web Reference.
In the Add Web Reference dialog box, add the CrmService reference:
In the URL box, type the location of your downloaded WSDL file (for example, c:CrmServiceWsdl.xml), and then click Go.
In the Web reference name box, type CrmSdk. (Note that if you are using C#, this is case sensitive.)
Click Add Reference.
Note
The Visual Studio 2005 Add Web Reference command automatically appears in Visual Studio 2008 when you target the .NET 2.0 Framework.
Adding the SDK assemblies references to your project
Create a new Console application project in Visual Studio 2008.
Right-click the project, and then click Add Reference.
In the Add Reference dialog box, click the Browse tab.
Navigate the file system and find the Microsoft.Crm.Sdk.dll assembly. The SDK assemblies reside in the SDK’s bin folder or the GAC folder of the Microsoft Dynamics CRM server installation CD. Click OK to add.
Repeat steps 2-4, but now add the Microsoft.Crm.Sdk.TypeProxy.
After you add the references to your project, you are ready to begin development.
Caution
Do not add both the WSDL-based reference and the Microsoft.Crm.* assemblies to your project. The references share the same namespace and many of the same properties and methods, which will force to you fully qualify all of your commands. We recommend you use one approach per project file.
Before we begin to code, let’s review the key functionality contained in each of Web service APIs.