Customizations refer to changes made to the Microsoft Dynamics CRM data schema, such as adding entities, attributes, relationships, and views.

The options for deploying customizations from one environment to another include:

Importing Customizations

Importing customizations is relatively straightforward. You can manually use the Microsoft Dynamics CRM user interface to both export and import customizations. However, if developing an automated installation program, you should use the ImportCompressedXml message. Always use the compressed (zip) versions of the customization files to avoid exceeding the 4-megabyte (MB) default file size limit.

We recommend using the import process for the following pieces of metadata:

• New entities

• New templates

• New security roles

• New workflows

The following code shows how to import a zip file:

static void ImportZip(CrmService service)
{
    //Get the Byte[] for the Customization File
    //Assume it is in the same directory as this application
    Byte[] bytes = System.IO.File.ReadAllBytes("customizations.zip");

    //Import the Customizations
    ImportCompressedAllXmlRequest request = new ImportCompressedAllXmlRequest();
    request.CompressedCustomizationXml = bytes;
    service.Execute(request);
}

Tip

The Import Customizations feature of Microsoft Dynamics CRM is designed to allow exporting from one organization and importing into another even if neither organization shares a common language. If your import file is missing language strings for a language provisioned on the system, it will simply leave them null. Certain strings, however, may never be null in the base language (for example, entity display names). The value from the base language of the exporting system will be substituted in this case and loaded into the base language on the importing system.

Do not use the Import Customization messages (ImportAllXml, ImportXml, ImportCompressedAllXml, ImportCompressedXml) to update schema metadata. Use the MetadataService instead, as described next.

Using the MetadataService

The MetadataService Web service provides excellent resources for configuring solutions. Chapter 8, has extensive details on how to use this API. For deployment applications, use the MetadataService to:

• Add new attributes.

• Add new relationships.

• Modify existing entities.

• Modify existing attributes.

• Modify existing relationships.

Warning

The MetadataService is language-sensitive. If the Locale ID (LCID) is hard-coded into your MetadataService code, it will fail if that language is not installed on the system. Keep in mind the multilingual capabilities of Microsoft CRM. Chapter 8 has more details regarding the MetadataService and multiple languages.

You can create new entities using the MetadataService as well. However, when a new entity is created, Microsoft Dynamics CRM creates unique GUIDs for some of the underlying metadata. Microsoft Dynamics CRM will synchronize some of these GUIDs when using the export/import process to ensure that duplicate schema entries are not processed. However, if you were to use the MetadataService to create the entities with an installer on two separate environments, each of those environments would contain unique GUIDs and Microsoft Dynamics CRM would interpret those entities as unique. Therefore, you would no longer be able to export and import customizations changes between those environments.

Publish Customizations

It’s extremely easy to publish your customizations using the CrmService Web service. You should ensure that your customizations are published before you begin registering any plug-ins and workflow activities.

To publish all customizations on the server, use the PublishAllXml message (as shown in the following code). If you want to limit the scope of your publishing, you can use the more precise PublishXml message, which is documented in the Microsoft Dynamics CRM SDK.

static void PublishAll(CrmService service)
{
    PublishAllXmlRequest request = new PublishAllXmlRequest();
    service.Execute(request);
}

Note

The publish messages are located with the CrmService API, not the MetadataService API.

Assigning permissions should be the last step in your configuration. This helps to prevent (but may not eliminate) the chances of a user using your solution while configuration is taking place. You can use import customizations to easily add new security roles to the organization. You may also want to assign these roles to users during configuration. You can use the AssignUserRolesRole message to add roles to a particular user.

Warning

Do not modify existing security roles. Doing so may compromise the operational security of the organization. Don’t assume that any of the default security roles (except System Administrator) will be present on the system. Many customers delete all unused roles when they set up their systems for additional security.

You should use caution when your solution needs to modify the user interface, such as updating existing forms or adding additional application menu items or left navigation links. You should expect that the destination Microsoft Dynamics CRM system has already been modified, and you need to inject your updates safely into the application.

As you already know, you can first export the item, modify its XML, and then re-import it. This is critical for preventing one developer from overwriting the customizations made by another developer. Schemas for each of these user interface constructs are available in the SDK and can be manipulated with normal XML programming techniques.

The following example shows how to append XML to any part of the customizations XML file:

static void ModifyUserInterface(CrmService service, string exportParameters,
 string path, string fragmentXml)
{
    //Export the current Customizations
    //Use the export parameters specified
    ExportXmlRequest exportRequest = new ExportXmlRequest();
    exportRequest.ParameterXml = exportParameters;
    ExportXmlResponse exportResponse =
      (ExportXmlResponse)service.Execute(exportRequest);

    //Add the XML fragment at the specified XPath location
    XmlDocument doc = new XmlDocument();
    doc.LoadXml(exportResponse.ExportXml);
    XmlDocumentFragment fragment = doc.CreateDocumentFragment();
    fragment.InnerXml = fragmentXml;
    XmlNodeList nodes = doc.SelectNodes(path);
    nodes[0].AppendChild(fragment);

    //Import the Customizations back into CRM
    ImportAllXmlRequest import = new ImportAllXmlRequest();
    import.CustomizationXml = doc.OuterXml;
    service.Execute(import);
}

For example, you could use this code to add a menu item to the settings area of the site map. To achieve this we would call the preceding method as follows:

static void ModifySiteMap(CrmService service)
{
    string exportParameters = "
        <importexportxml>
            <entities/>
            <nodes>
                <node>sitemap</node>
            </nodes>
            <securityroles/>
            <workflows/>
            <settings/>
        </importexportxml>";

    string path =
      "ImportExportXml/SiteMap/SiteMap/Area[@Id='Settings']/Group[@Id='Settings']";

    string fragmentXml =
      @"<SubArea Id='example_menu_item' Entity='example_entityname' />";

    ModifyUserInterface(service, exportParameters, path, fragmentXml);
}

When installing your ASP.NET Web application on the Microsoft Dynamics CRM server, you have a limited set of choices for where to place files and what configuration options to use. You should place the compiled assemblies for your Web site in the bin folder of the Microsoft Dynamics CRM Web site. You should place all other files (ASPXs, ASMXs, resources, and so on) inside the ISV folder. Microsoft recommends that you use your company’s name (or customization namespace) and then the name of your solution as your folder structure in the ISV folder, as shown in Figure 9-4. Consequently, you will deploy your custom Web files to two locations:

Figure 9-4. ISV folder in the Microsoft Dynamics CRM Web site

Warning

If you find the restrictions for an integrated ASP.NET Web application too severe, you may want to consider creating your own virtual directory. However, if you choose this method, you will not be able to take advantage of the CrmImpersonator class, which is critical to authentication using IFD.

Under no circumstances should you modify any file in Microsoft Dynamics CRM’s Web folder, including the Web.config. Modifying the files in the Microsoft Dynamics CRM Web folder will lead to unexpected system behavior and potential loss of your data.

Tip

Never assume that the Microsoft Dynamics CRM Web site will always be located at C:inetpubwwwroot. Many Web server administrators like to store the Inetpub folder on different drives than the operating system. You can find the file system location of the Microsoft Dynamics CRM Web site in the registry. Look for the value called WebSitePath in the registry key HKEY_LOCAL_MACHINESOFTWAREMicrosoftMSCRM

Microsoft Dynamics CRM offers three different storage locations for deploying plug-ins and workflow activities:

When deploying to production, developers should not use the disk deployment option—that option is intended for debugging purposes only.

The GAC deployment option is the most complex because you must not only place your assemblies in the GAC (usually achieved with an MSI), but you must also register the plug-ins and activities with each organization (in the configuration step). The advantage of GAC deployment is that you can easily replace the DLLs in the GAC for all organizations on the deployment. Developers will need to balance the desire for a central location for their assemblies (database) with the ability to share assemblies across organizations (GAC).

You should not handle database deployment during installation. Register the plug-ins and activities during the configuration step. Unless you have a need for regularly servicing the assemblies by updating the GAC and restarting IIS, it is recommended that you opt for the database route.

During the configuration step you should register any plug-ins and workflow activities. Use the API messages outlined in Chapter 5, to achieve this. Remember that a user who registers plug-ins and workflow activities must be a Deployment Administrator, as shown in Figure 9-5.

Figure 9-5. Microsoft Dynamics CRM 4.0 Deployment Manager

We also recommend that you use the plug-in’s custom configuration and secure configuration capabilities during deployment. These special properties of a plug-in enable the storage of organization-specific configuration information conveniently with the plug-in registration. For instance, if you wanted to store a custom database connection string that your plug-in requires for integration purposes, you can store this information securely during the registration of the plug-in. Please refer to Chapter 5 for additional information.

Tip

The source code for Microsoft’s Plug-in registration tool is freely available and licensed with the Microsoft Permissive License (Ms-PL). You can use all or some of this code in your own solutions. More information can be found here: http://code.msdn.microsoft.com/crmplugin.

Developers can also customize Microsoft Dynamics CRM’s online Help files. The Online Help is the same for all organizations on the deployment. Because online Help is deployment-wide, you should modify it during the installation step.

You can find the help content in the Help folder of the Microsoft Dynamics CRM Web site. Each installed language has its own separate help content found in a folder corresponding to its Locale ID (LCID).

It’s important to remember that the indexing catalog doesn’t update immediately. You don’t need to write code to force the refresh because it will happen automatically. However, when debugging your help content, you may want an immediate refresh. To do this, you need to stop and restart the Help catalog located by navigating to Computer Management > Services and Applications > Indexing Service, as shown in Figure 9-6.

Figure 9-6. Stopping the Microsoft CRM Help index catalog

Please refer to the Microsoft Dynamics CRM SDK for more information regarding the online Help customization.

Deploying custom reports to an environment can be done manually through the Microsoft Dynamics CRM user interface. However, Microsoft Dynamics CRM 4.0 now treats reports as a first-class entity. As such, you can create and update reports directly through the CrmService Web service. The code below shows an example of how to create a new report in Microsoft Dynamics CRM:

private Guid CreateReport(string reportFileName)
{
    FileInfo reportInfo = new FileInfo(reportFileName);

    report newReport = new report();
    newReport.name = Path.GetFileNameWithoutExtension(reportFileName);
    newReport.filename = reportFileName;
    newReport.filesize = new CrmNumber(reportInfo.Length);
    newReport.bodytext = File.ReadAllText(reportFileName);
    newReport.languagecode = new CrmNumber(1033);
    newReport.reporttypecode = new Picklist(1);

    CrmService crmService = CreateCrmService();
    crmService.Create(newReport);
}

You can use this approach within a custom installer or simple application to easily deploy a list of custom reports between environments.

Your application may require certain settings to be stored and configured in order to function properly. Systemwide settings that may apply to any organization in the deployment should be stored in the registry or custom database and completed during the installation step.

Caution

Remember that in Web farm scenarios, you will need to change any systemwide settings stored in the registry on each Web server in the deployment.

Configuration settings unique to each deployment can be stored in a custom entity located within each organization. As such, you should use the configure step to populate these values. When using a configuration program, simply use the Create message from the CrmService Web service to insert the data.