Adding Adoxio.Dynamics.DevOps Scripts to a Project
This blog post is going to be an introductory description of how to add and customize the sample scripts from the Adoxio.Dynamics.DevOps project into your own source controlled project so that you can start to perform scripted exports and imports of solutions and data in Dynamics 365.
The first thing to do if not done already is to install the Adoxio.Dynamics.DevOps PowerShell module on your computer. This is documented at the beginning of the README file on GitHub. The instructions are very similar for Dynamics 365 v8 and v9, with the important difference being the installation of the appropriate version of the Dynamics 365 SDK. Read the instructions and follow the steps as documented and this part should be done quite quickly.
Once the PowerShell module is installed, you could directly invoke the functions that are included in the module, however there is a more streamlined and repeatable manner in which it is intended to be used, through a set of sample scripts that serve as a template for setting up your project. Before doing that, it will be helpful to get a sense of what functionality is included in the PowerShell module so that the sample scripts makes sense once we start to look at them.
To see what functions are included in the module, open a PowerShell window and type in the following command:
Get-Command -Module Adoxio.Dynamics.DevOps
The output of this command is the full list of public functions included in the module. Some of these are the ones that you’ll see being referenced inside the sample scripts we will be using later.
One more useful thing to do before we continue is to see how to access the help documentation for individual functions. To do this, type the following command in PowerShell using the following format, where <command> is the name of one of the commands seen in the previous output:
Get-Help -Name <command> -Full
You will see a description of the function, a list of parameter names and their descriptions, and examples showing the execution of the command. If you have any doubt as to what a function inside one of the scripts does, use this command to get a more detailed explanation. For example, this is the output of Compress-CrmSolution:
Now let’s get your project setup to start using these PowerShell functions by copying and modifying the sample scripts. Go to the Adoxio.Dynamics.DevOps GitHub project and download the project.
Once downloaded to your local computer as a zip file, extract the zip file and navigate to the samples folder. Inside the sample folder you will see two folders: Advanced, and Simple. The advanced folder contains the scripts that give you full control over all the configuration settings that are used.
The simple folder contains a more simplified version of the scripts with less configuration required, but for now we will ignore it because it still needs some development work before I consider it stable and ready for use.
Copy the advanced folder to the root of your project and rename the folder from Advanced to scripts.
Let’s take a closer look at the files and folders inside the scripts folder.
Files in this folder represent connections to Dynamics 365 instances that import and export operations will be performed against. The contents of an individual file are the credentials and URL for an instance. Notice that there are several examples files provided, for on-premise, IFD, and online instances. The configuration parameters to use for each of these environments is slightly different so you should choose the appropriate file as a starting point for the environments that you will be using.
Files in this folder represent the settings for schema and data oriented operations performed during an export. There is a list of solutions to export and where to store their unpacked contents so that the individual components in a CRM solution are stored as individual files, and settings for manipulating configuration migration tool schema files and unpacking a configuration migration tool generated data zip file so that each data record is stored as an individual XML file.
Files in this folder represent the settings for schema and data oriented operations performed during an export. The settings are the inverse of what is seen in the export setting files, to pack the individual components from a CRM solution into a zip file so that it is importable into CRM once again, and to pack the individual data records into a zip file so that it is also importable into CRM once again using package deployer.
For now, please comment out or delete the CrmOrganizationProvisionDefinition section in this file. This section contains settings for provisioning local Dynamics 365 organization instances. These instances are intended to be running on a local virtual machine on your computer. This is a more complicated topic which I am going to skip over for now and will address in a future blog post.
This file orchestrates the export process. It has parameters for selecting the connection parameters to use to specify which organization the export is targeting, and the export settings file to use to know which solutions should be exported and data operations to perform.
This file orchestrates the import process. It has parameters for selecting the connection parameters file to use to specify which organization the import is targeting, and the import settings file to use so that the appropriate solutions and data are imported, and whether the imported solutions should be packed as managed or unmanaged solutions.
Now that we have a high-level understanding of the various files and folders, here is how to modify them to suit your needs.
- Edit or create new files in the CrmConnectionParameters folder that describe your environments. Make sure the file name accurately describes the purpose and name of the environment because its name will be referenced as a parameter during exports and imports when invoking Export.ps1 and Import.ps1.
- Edit the Export.ps1 and Import.ps1 files and update the validation set values in the CrmConnectionParameter parameter at the top of the file to match the filenames in the CrmConnectionParameters folder but without the .ps1 filename extension. The validation set provides IntelliSense and validation when executing the scripts from the command line so that only valid values can be chosen.
- Edit or create new files in the ExportSettings folder, with names that describe the feature or functionality of your project. Inside the export settings file, update the list of solutions to match the names of the solutions to export. The solutions when exported will reside in folders under crm/solutions beneath the root of your project. You can also update the name of the data zip file if performing a data export. The data must be exported manually in advance using the configuration migration tool. The data when exported will reside in a folder located under crm/data beneath the root of your project.
- Edit or create new files in the ImportSettings folder. Perform similar changes as made to the export settings file, referring to the solution names and data names that were used previously in the corresponding export settings files.
When editing all of these files, it is very important to pay close attention to the exact names of connections, solutions, and the data packages throughout the various settings files. They are referenced multiple times because each section is technically a separate set of parameters that are passed to the different functions in the Adoxio.Dynamics.DevOps module.
This is what the command to perform an export looks like:
./Export.ps1 -CrmConnectionName Online -ExportSettings <SettingFileName>
This is what the command to perform a managed solution import looks like:
./Import.ps1 -CrmConnectionName Online -ImportSettings <SettingFileName> –PackageType Managed
As each script is executed there will be fairly detailed output shown at each step during their execution. Temporarily generated files are saved in a temp folder beneath the root of the project. The temp folder should not be committed to source control.
This concludes this introductory overview of setting up a project to use the Adoxio.Dynamics.DevOps project. There is certainly a lot more detail to cover in the future regarding the configuration of the import and export settings files and how to properly manage your solution and data components during a project.