Choosing Between the WSDL and Assemblies
[Applies to: Microsoft Dynamics CRM 4.0]
There is a large overlap in the types found in the Web service WSDL, the two main SDK assemblies: Microsoft.Crm.Sdk and Microsoft.Crm.SdkTypeProxy, and the helper code included in the SDK download package. To choose which to use, you must consider what type of project that you want. The following information explains which to use for each type of project.
A plug-in is a compiled class in an assembly that it registered to run before or after Microsoft Dynamics CRM does its processing for an action. For plug-ins, use the following assemblies:
- Microsoft.Crm.Sdk.dll - Use this SDK assembly because contains the IPlguin and IPluginExecutionContext interfaces. It also contains the helper classes that you can use for building queries, instantiating types and enumerations you can use to make your code more readable and maintainable.
- Microsoft.Crm.SdkTypeProxy.dll - Use this SDK type proxy assembly because it contains the message request and response classes. However, do not use the strongly typed entity classes such as account or contact. Instead, use the DynamicEntity class, which provides a property bag to access the attributes of an entity instance (record). This is preferred because the entity classes included in this DLL will not contain any of your customizations. The entity classes are deprecated and will be removed from this assembly in a future version.
For more information, see Plug-ins.
Custom Workflow Activities
Custom workflow activities compile classes in an assembly that can be called from a workflow. For custom workflow activities, use the following assemblies:
- Microsoft.Crm.Sdk.dll - Use this SDK assembly because it contains the Microsoft.Crm.Workflow namespace, which includes all the classes that are needed to create custom workflow activities.
- Microsoft.Crm.SdkTypeProxy.dll – Use the messages (request and response classes) contained in the SDK type proxy assembly in your custom workflow activities. The same warning against the use of the entity classes, mentioned previously in the "Plug-ins" topic, applies here.
For more information, see Workflows.
Client Application Customizations
If you are adding new functionality to the Microsoft Dynamic CRM Web application or to Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access, you should typically use the types provided in the WSDL from the Web services. This includes adding custom ASPX pages or adding ISV menu items that calls your custom code. Remember that if you customize your entities, you must get an updated WSDL and recompile any code that uses those customized entity classes.
For client application customizations, use the following:
- CrmDiscoveryService Web service – Use this service to obtain the URL for your organization or to obtain a CRM ticket. For more information, see Web Services: CrmDiscoveryService.
- CrmService Web service – Use this service to access the data (records or entity instances) stored in Microsoft Dynamics CRM. If you decide to write code that uses only the DynamicEntity class instead of using the strong typed entity classes, you can use the Microsoft.Crm.Sdk assembly instead of the CrmService WSDL in your project. However, do not include Microsoft.Crm.SdkTypeProxy assembly in projects that also include a Web reference to CrmService. The CrmService Web services contain the entity classes and the message classes. Adding this assembly will cause compile type errors because this will duplicate every entity class found in the WSDL. For more information, see Web Services: CrmService.
- MetadataService Web service – Use this service to access the entity definitions for the data in your project. For more information, see Web Services: MetadataService.
- Microsoft.Crm.Outlook.Sdk.dll – Use this assembly for code that can work online (connected to the server) or offline. If you are adding functionality to Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access, use the Outlook SDK assembly because it contains methods that detect whether the client is online or offline, that make the client go online or offline, or that synchronize the data after going online. For more information, see Support for Offline Programs.
- Helper Code – You can also use the helper classes by adding the C# files from CrmHelpers, located in the SDK download. These classes can be used for easier type instantiation and for building queries. They contain enumerations you can use to write more readable and maintainable code. You can also access the identical helper classes by referencing the Microsoft.Crm.Sdk assembly. Adding this DLL requires a bit more care because the SDK assembly contains the classes for the metadata Web service. This may cause compile time errors if you are also using the MetadataService. For more information, see Helper Code.
© 2010 Microsoft Corporation. All rights reserved.