Custom Code Best Practices

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

The following is a list of best practices to follow.

Best Practices for Consuming the Microsoft Dynamics CRM Web Services

You should put the Microsoft Dynamics CRM Web service URL into a configuration file so that your code is isolated from changes to the URL in future versions.

Where Should You Put Custom Code?

For Plug-ins and Custom Workflow Activities

For on-disk plug-ins or custom workflow activities, place the assemblies in the <installdir>\Server\bin\assembly folder.

For Custom Web Applications

Some of these recommendations require Microsoft Dynamics CRM 4.0 Update Rollup 2, which can be found at\&displaylang=en\&.

Use a custom entity for any settings or configuration data you require. For more information, see "ISV Utilities for Comparing Customizations and Transferring Configuration Data" located at

Create a subfolder in the <crmwebroot>\ISV folder, such as <crmwebroot>\ISV\<myapp>, using the following guidelines:

  • Place your .aspx files in the <crmwebroot>\ISV\<myapp> folder.
  • Place your assemblies in one of the locations listed in the following table.
Condition Location for assemblies
If you will be sharing the assemblies with other applications In the GAC
If you have installed Update Rollup 2 Under your own bin folder <crmwebroot>\ISV\<myapp>\bin. Make sure you add the @Assembly directive to each of your ASPX pages specifying the name of the assembly. The name should not include the path. For more information about this directive, see @Assembly, located at
If you have not installed Update Rollup 2 Use the \bin folder directly under the <crmwebroot> folder However, this is not recommended after you have installed Update Rollup 2.

Where Should You Put Your Web Pages?

Whether you use the ISV folder to deploy your application or a new Web site or application depends on several factors. The following guidelines can be used to guide your choice.

When to use the <crmwebroot>\ISV\<myapp> folder?

Use the ISV folder when:

  • Your application needs to take advantage of the context of the Microsoft Dynamics CRM application. For example, you have a page that will be displayed as an IFrame inside Microsoft Dynamics CRM and you want to take advantage of Microsoft Dynamics CRM authentication (including IFD) and avoid cross-domain issues. If your page needs to communicate with the CRM form client-side object model (crmForm), your page needs to be part of the same domain.
  • Your application will be used both online and offline and you want to keep a consistent deployment structure.
  • Your application is an extension of the Microsoft Dynamics CRM application.

When to create a new Web site?

Create a new Web site for your code when:

  • Your application needs to be bound to a domain, protocol, or port different from the Microsoft Dynamics CRM application or needs to run in a different application pool.
  • Your application can exist and be accessed on its own. For example, a portal than interacts with Microsoft Dynamics CRM as the backend (using Web services) should be hosted as a new Web site.
  • Your application always uses Active Directory or Windows authentication (not IFD) and cross domain scripting is not an issue. For example, your application interacts with a back-end using Web services and interacts with Microsoft Dynamics CRM forms. A page hosted in an IFrame within the Microsoft Dynamics CRM application that does not interact with the CRM form (crmForm) falls into this category.

What type of workflow is better?

  • From a performance perspective, is it better to create a single long workflow or is it better to have multiple child workflows and call them in one parent workflow? The child workflow approach results in lower throughput, but it is more manageable if you need to change the workflow definition frequently. Compilation overhead is not a major concern because the workflow is compiled only during publishing. However, there is overhead for starting each workflow instance. This requires retrieving all entities used in the workflow as well as starting a child workflow in a 2-step process that includes a 'Workflow Expansion Task' and the actual workflow instance. For maximum throughput, use a single long workflow.

How should you mark your custom workflow activity as completed?

  • The return value from the Execute method is used by Workflow runtime to mark the activity as "completed." You should use "return base.Execute(executionContext)" unless the activity bypasses base class functionality. Avoid returning ActivityExecutionStatus.Closed. For more information, see this topic in the MSDN Library: ActivityExecutionStatus Enumeration.

How should you report exceptions in custom workflow activities?

  • You should throw an InvalidPlugInExecutionException. This error will be shown in the workflow instance form.

© 2010 Microsoft Corporation. All rights reserved.