Introducing the Dynamics CRM Deployment Wizard

Over the course of my career, I have seen too many Dynamics CRM solution deployments fail because of poorly executed deployment processes. To make deployments easier, I have built a new tool called the Dynamics CRM Deployment Wizard. The CRM Deployment Wizard executes deployment (solution or reference data import) steps listed in a JSON manifest file, so all you have to do is organize your files, create the manifest and run the deployment job.

Specifically, the CRM Deployment Wizard supports three different types of operations:

  1. Importing CRM solutions
  2. Executing Alexander Development Dynamics CRM Configuration Data Mover jobs
  3. Executing arbitrary commands using the .Net System.Diagnostics.Process.Start method

(If this sounds similar to the Dynamics CRM Package Deployer, you're right. When I first started looking at deployment automation, the Package Deployer was my first choice, but it requires someone to build a deployment package using Visual Studio, and that seems like overkill for most deployments I've ever overseen.)

The rest of this post will show how to stage and execute a deployment package. Download links for the source code and a compiled version of the Deployment Wizard are at the bottom if you want to skip ahead.

Setting up a deployment package

In order to use the tool, you need to do the following:

  1. Create a directory to hold the deployment manifest and all supporting CRM solution and configuration data files.
  2. Create the following subdirectories in the main deployment package directory:
    a. solutions
    b. data
    c. logs
  3. Place solutions to be imported in "solutions" directory.
  4. Place Configuration Data Mover job XML files and any JSON data import files in "data" directory.
  5. Create a manifest file in root of package directory. This file is a JSON array of steps for the tool to execute. Here is the content of a sample Deployment Wizard manifest:
{
  "steps": [
    {
      "type": "solutionimport",
      "solutionpath": "dog_0_0_0_1.zip",
      "options": {
        "publishworkflows": true,
        "publishcomponents": true
      }
    },
    {
      "type": "dataimport",
      "configpath": "team-import.xml",
      "datasource": "teams.json"
    },
    {
      "type": "command",
      "path": "C:\\git-repos\\AlexanderDevelopment.CrmDeploymentWizard\\sln-work\\test.bat",
      "arguments": ""
    }
  ]
}

Each of the configuration parameters is described in more detail below. I've also included a sample deployment package in the samples directory in my GitHub repository.

CRM solution import step parameters

  • type: solutionimport
  • solutionpath: Path to the solution relative to the "solutions" directory.
  • options
    • publishworkflows: Boolean value for whether publish SDK messages when the solution is imported.
    • publishcomponents: Boolean value for whether to publish the entities, dashboards, application ribbon modifications, sitemap, global optionsets and web resources included in the solution after it is imported. Unlike a lot of other solution import utilities, this does not execute a publish all command.

Configuration Data Mover step parameters

  • type: dataimport
  • configpath: Path to the job XML file relative to the "data" directory.
  • datasource: Source for the data import. If the source is a Configuration Data Mover JSON data export file, the path is relative to the "data" directory. Unlike when running the Configuration Data Mover as a standalone tool, this utility will not read the source connection from the job XML file.

The target for the data import is not specified in the step parameters. The data import target is always set to the target for the overall Deployment Wizard job, even if a target is specified in the Configuration Data Mover job XML file.

Command step parameters

  • type: command
  • path: Absolute path to the command to run (EXE, BAT, etc.). Any backslashes in the path must be escaped.
  • arguments: Arguments to be passed to the command at runtime.

When a command step is executed, as soon as the process starts, the Deployment Wizard will immediately move to the next step in the manifest or finalize the job if no next step is specified. You should not create jobs that require a command to complete prior to executing a subsequent step.

Deploying the package

Once you have completed the preparation steps above, you can open a command prompt and run the tool. You just need to supply the path to the manifest file and connection details for the target CRM system as a simplified connection string. Here's an example of how to do that:

AlexanderDevelopment.CrmDeploymentWizard.exe -m "C:\git-repos\AlexanderDevelopment.CrmDeploymentWizard\samples\package01\package-manifest.json" -t "url=http://192.168.65.101/LucasTest01;username=administrator;domain=companyx;password=XXXXXXXX"  

This is the output on my system:
Dynamics CRM Deployment Wizard output

Logging

The CRM Deployment Wizard uses the Apache log4net library for logging. The standard configuration generates two log files in the directory where the Deployment Wizard executable runs:

  • CrmDeploymentWizard.log - This is a verbose log of each step in the process.
  • CrmDeploymentWizard-Error.log - This records every error encountered in the process. It is particularly useful for troubleshooting jobs that include a Configuration Data Import step because it includes the GUID and details for each record that could not be imported.

You can modify the format of the logs by updating the log4net configuration in the app.config files. An overview of logging configuration options can be found here.

Results of CRM solution import steps are saved to the "logs" subdirectory in the main deployment package directory as yyyy-MM-dd_hhmmss_solution-[SOLUTION NAME].xml

Getting the Dynamics CRM Deployment Wizard

The source code is available in my GitHub repository here.

A compiled version can be downloaded here.

This is currently a pre-release version. I don't think it will eat your data or trash your CRM system, but it's definitely rough around the edges and could use some better error handling and more thorough testing. If you're interesting in helping me out with either of those, please let me know.

comments powered by Disqus