Upgrade plug-ins and custom workflow activities


Applies To: Dynamics CRM 2013

Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online do not provide legacy support for running Microsoft Dynamics CRM 4.0 plug-ins and custom workflow activities. If you have 4.0 based plug-ins or custom workflow activities running on a Microsoft Dynamics CRM 2011 on-premises or IFD server, you will need to upgrade your code for them to run on Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online servers.

A recommended approach is to update your 4.0-based plug-in or custom workflow activity code to the latest Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online design standards prior to upgrading your on-premises or IFD organization to Microsoft Dynamics CRM 2013. This topic identifies the code changes that are required.

One of the first steps in upgrading your code is to simply compile the code. You will need to remove references in your Microsoft Visual Studio project to old SDK assemblies and add references to the Microsoft.Crm.Sdk.Proxy.dll and Microsoft.Xrm.Sdk.dll assemblies. If your code uses early-bound types instead of DynamicEntity, you also need to generate an early-bound types file using the CrmSvcUtil program and add that generated types file to your project. A non-customized early-bound types file named MyOrganizationCrmSdkTypes is included in the SampleCode\CS\HelperCode and SampleCode\VB\HelperCode folders of the SDK download to get you started a little quicker. However, if your organization has custom or customized entities, you should generate a new early-bound types file.

After attempting to compile your code, you will see where the SDK API has changed. The following sub-topics describe some of these changes.

The IPlugin interface has changed. The Execute method has a new signature, and you get references to the execution context and organization service using different code. For more information, see Write a plug-in.

There are some changes to the IPluginExecutionContext class. Specifically, the CallerOrigin property has been removed and replaced by the IsExecutingOffline and IsOfflinePlayback properties. Also, you can now directly determine if your plug-in is executing in the database transaction by examining the IsInTransaction property.

If you are using early-bound types like account, contact, and so on in your plug-in code you need to change those class names slightly. The new names are Account, Contact, and so on. These types are defined in the early-bound types file that is generated by the CrmSvcUtil program.

Your plug-in should check for a fault exception FaultException<OrganizationServiceFault> that can be returned from the Windows Communication Foundation (WCF) channel. For more information, see the SDK sample plug-in code for other exceptions that can occur.

Some messages have been deleted and new messages added. For example, the AssociateRequest message replaces the AssociateEntitiesRequest message. For more information, see the table in the Message-entity support for plug-ins.xlsx file in the Tools folder of the SDK download for a list of message and entity combinations that support plug-ins.

Finally, consider enhancing your code by making use of new features in this release of Microsoft Dynamics CRM. For example, add support for running your plug-in or custom workflow activity in the sandbox (isolation mode) so you can deploy it to Microsoft Dynamics CRM Online! For more information about the sandbox, see Plug-in isolation, trusts, and statistics.

The following restrictions now apply to plug-in assemblies.

  • All assemblies must be signed or delay signed.

  • The PluginAssembly records must be unique on Name+Culture+Major+Minor+PublicKeyToken.

  • The PluginType records must be unique on TypeName+PluginAssemblyId.

  • Registration of 32-bit assemblies is only supported on 32-bit clients. Trying to register a 32-bit assembly on a 64-bit server results in a registration error.

The following are known plug-in registration configuration issues.

  1. Specifying an invalid attribute in an image or step. For example, the attribute name is not spelled correctly or the attribute does not exist in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online.

  2. Registering a pre-image for a CreateRequest or a post-image for a DeleteRequest.

  3. Specifying an incorrect deployment type. For example, by registering a plug-in to execute on an assign of an account for deployment on Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access when that message and entity combination is supported only on the server.

The following sub-topics list the changes for the custom workflow activities in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online. For an example of a custom workflow activity before and after upgrade, see Upgrading a CRM 4.0 Custom Workflow Activity to CRM 2011.

Processes in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online execute with the Microsoft .NET Framework 4 run-time. As a result, to create custom workflow activities you must:

  • Create a class that inherits from the CodeActivity workflow base class. The CodeActivity base class is available in the System.Activities namespace

  • The Execute method in your custom activities must take a parameter of CodeActivityContext type instead of the ActivityExecutionContext type.

  • Define input, output, and default parameters using the new Microsoft Dynamics CRM process classes. Moreover, you no longer have to define dependency properties while defining the input and output parameters to indicate that the process is dependent on the value.

For more information about these points, see Create a custom workflow activity.

The name and group name of a custom workflow activity is now specified while registering the custom workflow activity assembly instead of at the compilation time. These are the values that will appear in the Process designer in the Microsoft Dynamics CRM Web application to identify your custom activity. For more information, see Specify the name and group name for a custom workflow activity.

Use the Microsoft.Xrm.Sdk.Workflow namespace instead of the Microsoft.Crm.Workflow namespace to create custom activities. You can use the Microsoft.Xrm.Sdk.Worklow namespace by adding a reference to the Microsoft.Xrm.Sdk.Workflow.dll file in your project. For example, to specify the input parameters in your custom activity, you now have to use the InputAttribute class instead of the CrmInputAttribute class.

Use the Microsoft.Xrm.Sdk.Workflow.Activities namespace instead of the Microsoft.Crm.Workflow.Activities namespace to create custom activities. You can use the Microsoft.Xrm.Sdk.Workflow.Activities namespace by adding a reference to the Microsoft.Xrm.Sdk.Workflow.dll file in your project.

Same as mentioned earlier for plug-ins in this topic.

Same as mentioned earlier in the Messages section for plug-ins.

Same as mentioned earlier in the Plug-in assembly restrictions and registration issues section. Additionally, custom workflow activities must be unique on Name+WorkflowActivityGroupName.