Web Services & DLLs or What’s up with all the duplicate classes?

You may have noticed that the Microsoft Dynamics CRM 4.0 SDK contains Web services, assemblies and helper code that have LOTS of the same classes. Which should you use, when and why? It depends on what you are creating:

Plug-ins

A plug-in is an assembly that it registered to run before or after CRM does it’s processing for an action.

Use:

Microsoft.Crm.Sdk.dll
Microsoft.Crm.SdkTypeProxy.dll

Use the SDK assembly because contains the IPlguin and IPluginExecutionContext. It also contains the helper classes you can use for building queries, instantiating types and enumerations you can use to make your code more readable and maintainable.

Use the SDK type proxy assembly because it contains the messages (request and response classes). This assembly also includes all the entity classes but do not use them! In other words, do not use the account or contact classes; instead use the DynamicEntity class, which provides a property bag to access the attributes of an entity instance (record). This is better for you anyway, since 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.

Custom Workflow Assemblies

Custom workflow activities are assemblies that can be called from a workflow.

Use:

Microsoft.Crm.Sdk.dll
Microsoft.Crm.SdkTypeProxy.dll

Use the SDK assembly because it contains the Workflow namespace which includes all the classes you need to create custom workflow activities.

You can use the messages (request and response classes) contained in the SDK type proxy in your custom workflow activities. The same warning against using the entity classes applies here.

Add-ins for the Web app or for the Outlook client

If you are adding new functionality to the CRM Web application or to the Outlook client, you should use 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 need to recompile any code that uses those customized entity classes.

Use:

CrmDiscoveryService – Use this to get the URL for your organization or to get a CRM ticket
CrmService – Use this to access the data (records or entity instances) stored in CRM
MetadataService – Use this to access the definitions for the data (entities)
Microsoft.Crm.Outlook.dll – Use this for code that can work online (connected to the server) or offline
Helper Code – Optional helper code to make your coding easier

There is another Web service covered in the CRM Deployment SDK but this is not used in this sort of custom code.

If you are adding functionally to the CRM Outlook client, use the Outlook SDK assembly because it contains methods to detect whether the client is online or offline, to make the client go online or offline or to synchronize the data after going online.

You can also use the helper classes by adding the C# files from CrmHelpers. These classes can be used for easier type instantiation, for building queries and contains enumerations you can use to write more readable and maintainable code.

You can also get the identical helper classes by adding the Microsoft.Crm.Sdk.dll assembly. Adding this DLL requires a bit more care because the SDK assembly contains the classes for the metadata Web service so this may be confusing if you are also using the MetadataService.

Do not include Microsoft.Crm.SdkTypeProxy.dll to these types of projects. The Web services contain the entity classes and the message classes so this assembly is not needed.