As part of the SP1 SDK update for Microsoft Dynamics CRM 2013, we got the new Package Deployer Tool. I was recently doing some research on this at TSG and thought I would write about what it is and how to use it.
What is the package deployer tool?
Well the package deployer tool allows us to deploy packages we create from a Visual Studio project that comes as part of the CRM SDK Templates (which are part of the CRM 2013 SP1 SDK). The package is based on a number of managed solutions, migrated data that was exported using the data configuration manager tool (which is also part of the CRM 2013 SP1 SDK), and perform a number of custom actions via .NET code (with various Pre/Post/Before/After hooks) say for assigning all users to a specific role, and display HTML information to the user before or after the package is deployed.One of the key benefits of using a Package is that you can run an upgrade migration to upgrade from one version of a solution to another.
How do we create a package for the deployer tool in Visual Studio 2013?
First we need to download the CRM 2013 SP1 SDK, and extract to say C:\CRM-SDK, then we need to run C:\CRM-SDK\SDK\Templates\CRMSDKTemplates.vsix
The following error may appear in the install log with Visual Studio 2013:
Install Error : Microsoft.VisualStudio.ExtensionManager.MissingReferencesException: This extension cannot be installed because the following references are missing:
- NuGet Package Manager
To resolve this we simply install the NuGet Package Manager from Visual Studio Gallery here, and ensure the latest update is applied to Visual Studio, at the time of writing this is Update 3 and available here.
We can also resolve the error by extracting the CRMSDKTemplates.vsix file, and edit the extension.vsixmanifest file and remove the following line:
<Dependency Id="NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5" DisplayName="NuGet Package Manager" Version="[2.8.50126.400,3.0)" />
The we need to zip the extracted files back up, rename to .vsix and re-run the VSIX file.
Now we can create a CRM Package Project, which is under CRM SDK Templates, in Visual Studio.
What does the project consist of?
As part of the Visual Studio project that is created we get a number of things. Within the bin\Debug\tools folder we get the standard CRM SDK files that we would expect when we need to connect to CRM, but we also get the Solution Packager. This isn’t proven, but I suspect this is used for the Holding Solution when migrating a solution from one version to another, update to follow on migrating a solution from one version to another.We also get the PkgFolder which contains, most importantly, the ImportConfig.xml along with the HTML files for the Welcome, and End Pages of the deployment wizard.
Any custom action code that we want to create can be put into the PackageTemplate.cs file.
To add files to the Package, we simply add them to the root of the PkgFolder and we must remember to set the Copy to Output Directory to Copy Always as part of the properties of the files we add. Setting the Copy to Output Directory property means that when we build the class library project we get the files we need to deploy in the relevant debug or release folder.
The great thing about the content folder is that we can create multi-lingual installation files, by simply creating a locale folder say de-DE under the main content folder.
So what is in the ImportConfig.xml file?
An example of the ImportConfig.xml file is below:
<?xmlversion="1.0"encoding="utf-16"?>
<configdatastoragexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"
installsampledata="false"
waitforsampledatatoinstall="true"
agentdesktopzipfile=""
agentdesktopexename=""
crmmigdataimportfile="">
<solutions>
<configsolutionfilesolutionpackagefilename="solutionFile.zip" />
</solutions>
<filestoimport>
<configimportfilefilename="File.csv"filetype="CSV"associatedmap=""importtoentity="FileEntity"datadelimiter=""fielddelimiter="comma"enableduplicatedetection="true"isfirstrowheader="true" isrecordownerateam="false"owneruser=""waitforimporttocomplete="true"/>
<configimportfilefilename="File.zip"filetype="ZIP"associatedmap="ZipFileMap"importtoentity="FileEntity"datadelimiter=""fielddelimiter="comma"enableduplicatedetection="true"isfirstrowheader="true" isrecordownerateam="false"owneruser=""waitforimporttocomplete="true"/>
<zipimportdetails>
<zipimportdetailfilename="subfile1.csv"filetype="csv"importtoentity="account" />
<zipimportdetailfilename="subfile2.txt"filetype="csv"importtoentity="contact" />
</zipimportdetails>
</filestoimport>
<filesmapstoimport>
<configimportmapfilefilename="FileMap.xml" />
<configimportmapfilefilename="ZipFileMap.xml" />
</filesmapstoimport>
</configdatastorage>
We can simply change the Solution Package filename to the correct filename of our solution, and add more elements if we have multiple solutions to import. The key thing for any dependencies is to list the solutions in the order we wish to import them.
If we need to import some configuration settings before we import the solutions then we would have to use a custom action and add a custom setting in the config file.
We can export configuration settings use the Configuration Manager, we manually export settings from CRM, or we can use a custom data manager to export the data (an example can be found here)
With the configuration files we also have a neat option of saying whether we want to wait for an import of a data file to complete before continuing or if we know we have no dependant relationships in the files then we can run asynchronously.
The following table is an extract from MSDN page Create packages for the CRM Package Deployer which can be seen here
Parameter/Node | Description | ||||||||||||||||||||||||
crmmigdataimportfile | File name of the data file (.zip) exported using the Configuration Migration tool.
| ||||||||||||||||||||||||
<solutions> node | Contains an array of <configsolutionfile> nodes that describe the solutions to import. The order of the solutions under this node indicates the order in which the solutions will be imported on the target server. | ||||||||||||||||||||||||
<configsolutionfile> node | Use this node under the <solutions> node to specify the individual solution file name to be imported. You use the solutionpackagefilename attribute under this node to specify the .zip file name of your solution. You can add multiple solution file names in a package by adding as many <configsolutionfile> nodes. For example, if you want three solution files to be imported, add them like this: | ||||||||||||||||||||||||
<filestoimportnode> node | Contains an array of <configimportfile> and <zipimportdetails> nodes that are used to describe individual files and zip files respectively to be imported. | ||||||||||||||||||||||||
<configimportfile> node | Use this node under the <configimportfile> node to describe a file to be imported to CRM. You can add multiple files in a package by adding as many <configimportfile> nodes. This has the following attributes:
| ||||||||||||||||||||||||
<zipimportdetails> node | This node contains an array of <zipimportdetail> nodes that describe the files included in a zip file that is used to import to CRM. | ||||||||||||||||||||||||
<zipimportdetail> node | Use this node under the <zipimportdetails> node to provide information about an individual file in a .zip file that is specified in the <configimportfile> node. This has the following attributes:
| ||||||||||||||||||||||||
<filesmapstoimport> node | This node contains an array of <configmapimportfile> nodes to import. The order of the map files in this node indicates the order in which they are imported. For information about data maps, see Create data maps for import. | ||||||||||||||||||||||||
<configimportmapfile> node | Use this node under the <filesmapstoimport> node to provide information about an individual map file to import in CRM. |
What is available as part of the Import Extension Class?
The following properties are exposed via the Import Extension class:
Name | Description |
Returns a pointer to the CRM instance. | |
Returns the Title Link Text that is show on the completed page. | |
Returns the long name of the import process. | |
Returns the name of the Import package data folder. | |
Gets package description import. | |
Description of the import package. | |
Returns the folder name of the import. | |
Returns the long name of the import process. | |
Parent dispatcher for displaying UI elements. |
The following methods are available for us to write some custom actions:
Name | Description |
Called After all Import steps are complete, allowing for final customizations or tweaking of the CRM instance. | |
Called Before each application record is imported. | |
Called before the Main Import process begins, after solutions and data. | |
Returns the Name of the import project. | |
Returns the Name of the Import project. | |
Called to Initialize any functions in the Custom Extension. | |
Initialize extension functionality. | |
Is called during a solution upgrade when both solutions, old and Holding, are present in the system. |
We can also use the PackageLog logging interface within the Import Extension class to write out any trace log information to the package trace log.
Full details of the Import Extension class along with other helper classes on MSDN can be found here.
How do we deploy a Package after we have created it?
Once we have created a package there are a few steps that we need to follow to deploy the package, these are as follows:
1. We need to create a Deploy folder say in C:\Deploy
2. Then we copy the contents of the C:\CRM-SDK\SDK\Tools\PackageDeployer folder to the C:\Deploy folder.
3. Next we copy the contents of our package from say the projects bin\Debug folder into the C:\Deploy folder, you may be prompted to replace some files, so accept to replace the files.
4. Now we can run PackageDeployer.exe from C:\Deploy.
Note: We could include the files from C:\CRM-SDK\SDK\Tools\PackageDeployer as part of the Visual Studio solution, setting their Copy to Output Directory properties to Copy Always. This would then allow us to simply copy the projects bin\Debug folder, and would also mean that if we were using TFS (Team Foundation Server) we could have an automated build run on check-in of the solution that rebuilds the solution and places the built files in our standard builds folder meaning we have a single place to look for our deployment package and required executable files.
Although not a full step-by-step guide hopefully this has shown how powerful the Package Deployer Tool is and how it can be used as part of the CRM 2013 Application Lifetime Management.
@simonjen1