Partager via

Create packages for the CRM Package Deployer

  • Article

 

Applies To: Dynamics CRM 2013

Microsoft Dynamics CRM Package Deployer is a new tool that enables administrators to deploy packages on Microsoft Dynamics CRM Online and Microsoft Dynamics CRM (on-premises) instances. A “package” can consist of any or all of the following:

  • One or more CRM solution files.

  • Flat files or exported data files from the Configuration Migration tool. For more information about the tool, see Manage your configuration data.

  • Custom code that can run while the package is being deployed to the CRM server, or after it’s been deployed.

  • HTML content specific to the package that can display at the beginning and end of the deployment process. This can be useful to provide a description of the solutions and files that are deployed in the package.

Microsoft Dynamics CRM provides you with a Visual Studio template for creating these packages that can be used with the Package Deployer tool to deploy them to a CRM server.

In This Topic

Prerequisites

Create a package

Deploy a package

Best practices for creating and deploying packages

Prerequisites

  • Ensure that you have all the solutions and files ready that you want to include in the package.

  • Microsoft .NET Framework 4

  • Microsoft Visual Studio 2012 or Visual Studio 2013

  • NuGet Package Manager for Visual Studio 2012 or Visual Studio 2013

  • Microsoft Dynamics CRM SDK templates for Visual Studio that contains the package template. You can get it in one of the following ways:

    • Download the CRM SDK template from Visual Studio gallery, and double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

    • Download and extract the CRM SDK package. The templates file, CRMSDKTemplates.vsix, is located in the SDK\Templates folder. Double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

Create a package

Perform the following five steps to create a package:

Step 1: Create a project using the template

Step 2: Add your files to the project

Step 3: Update the HTML files: English and other languages

Step 4: Specify the configuration values for the package

Step 5: Define custom code for your package

Step 1: Create a project using the template

  1. Start Microsoft Visual Studio, and create a new project.

  2. In the New Project dialog box:

    1. From the list of installed templates, expand Visual C#, and select CRM SDK Templates.

    2. Select .NET Framework 4 as the target framework, and then select CRM Package.

    3. Specify the name and location of the project, and click OK.

    New project for creating a custom package

  3. In the Solutions Explorer pane, expand the References section to ensure all the assembly references resolve correctly. If there are any missing references, set the reference path of your project (Project > [Project] Properties > Reference Paths) to the SDK\Tools\PackageDeployer folder.

Step 2: Add your files to the project

  1. In the Solutions Explorer pane, add your solutions and files under the PkgFolder folder.

  2. For each file that you add under the PkgFolder folder, in the Properties pane, set the Copy to Output Directory value to Copy Always. This ensures that your file is available in the generated package.

Step 3: Update the HTML files: English and other languages

  1. In the Solution Explorer pane, expand PkgFolder > Content > en-us. You’ll find two folders called EndHTML and WelcomeHTML. These folders contain the HTML and associated files that enable you to display information at the end and beginning of the package deployment process. Edit the files in the HTML folder of these folders to add information for your package.

  2. You can also add the HTML files in your package in other languages so that the content in the HTML appears in the language based on the locale settings of the user’s computer. To do so:

    1. Create a copy of the en-us folder under PkgFolder > Content.

    2. Rename the copied folder to the appropriate language. For example, for the Spanish language, rename it to es-ES.

    3. Modify the content of the HTML files to add Spanish content.

Step 4: Specify the configuration values for the package

  1. Define the package configuration by adding information about your package in the ImportConfig.xml file available in the PkgFolder. Double-click the file to open it for editing. The following table lists information about each parameter and node in the config file.

Parameter/Node

Description

installsampledata

true or false. If true, installs sample data to CRM instance. This is the same sample data that you can install from Settings > Data Management area.

waitforsampledatatoinstall

true or false. If true, and if installsampledata is also set to true, waits for sample data to install before deploying the package.

agentdesktopzipfile

File name of the zip file to unpack. If you specify a .zip file name here, it adds a screen during the package deployment process that prompts you to select a location where you want to unpack the contents of the file.

This is commonly used for creating packages for Unified Service Desk for Microsoft Dynamics CRM. For information about Unified Service Desk, see the Unified Service Desk Administration Guide.

agentdesktopexename

Name of the .exe or .msi file in the zip file or a URL to be invoked at the end of the deployment process.

This is commonly used for creating packages for Unified Service Desk.

crmmigdataimportfile

File name of the data file (.zip) exported using the Configuration Migration tool.

Important

If your data file contains user information, the user information won’t be imported. To import user information from the source CRM instance to the target instance, you must use the Configuration Migration tool. For more information, see Manage your configuration data in the CRM Implementation Guide.

<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:

<solutions>
<configsolutionfile solutionpackagefilename="SampleSolutionOne_1_0_managed.zip" />
<configsolutionfile solutionpackagefilename="SampleSolutionTwo_2_0_managed.zip" />
<configsolutionfile solutionpackagefilename="SampleSolutionThree_3_0_managed.zip" />
</solutions>

<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.

<filestoimport>
<configimportfile
filename="File.csv"
filetype="CSV"
associatedmap="FileMap"
importtoentity="FileEntity"
datadelimiter="" fielddelimiter="comma"
enableduplicatedetection="true"
isfirstrowheader="true"  isrecordownerateam="false"
owneruser=""
waitforimporttocomplete="true"/>
<configimportfile
filename="File.zip"
filetype="ZIP"
associatedmap="FileMapName"
importtoentity="FileEntity"
datadelimiter=""
fielddelimiter="comma"
enableduplicatedetection="true"
isfirstrowheader="true"
isrecordownerateam="false"
owneruser=""
waitforimporttocomplete="true"/>
...
...
</filestoimport>

This has the following attributes:

Attribute

Description

filename

Name of the file that contains the import data. If the file is a .zip file, a <zipimportdetails> node must be present with a <zipimportdetail> node for each file in the .zip file.

filetype

This can be csv, xml, or zip.

associatedmap

Name of the CRM import data map to use with this file. If blank, attempts to use the system determined import data map name for this file.

importtoentity

Can be the name of the exe in the zip file, a URL, or an .msi file to provide a link to invoke at the end of the process.

datadelimiter

Name of the data delimiter used in the import file. Valid values are singlequote or doublequotes.

fielddelimiter

Name of the field delimiter used in the import file. Valid values are comma or colon, or singlequote.

enableduplicatedetection

Indicates whether to enable duplicate detections rules on data import. Valid values are true or false.

isfirstrowheader

Used to denote that the first row of the import file contains the field names. Valid values are true or false.

isrecordownerateam

Indicates whether the owner of the record on import should be a team. Valid values are true or false.

owneruser

Indicates the user ID that should own the records. The default value is the currently logged in user.

waitforimporttocomplete

If true, the system waits for the import to complete before proceeding. If false, it queues the jobs and moves on.

<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.

<filestoimport>
...
...
<zipimportdetails>
<zipimportdetail filename="subfile1.csv" filetype="csv" importtoentity="account" />
<zipimportdetail filename="subfile2.txt" filetype="csv" importtoentity="contact" />
</zipimportdetails>
</filestoimport>

This has the following attributes:

Attribute

Description

filename

Name of the file that contains the import data.

filetype

This can be csv or xml.

importtoentity

Can be the name of the exe in the zip file, a url, or an .msi file to provide a link to invoke at the end of the process.

<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.

<filesmapstoimport>
<configimportmapfile filename="FileMap.xml" />
</filesmapstoimport>
  1. Click Save All.

Step 5: Define custom code for your package

  1. In the Solution Explorer pane, double-click the PackageTemplate.cs file at the root to edit it.

  2. In the PackageTemplate.cs file, you can:

    1. Enter custom code to execute when the package is initialized in the override method definition of InitializeCustomExtension().

    2. Enter custom code to execute before the import starts in the BeforeImportStage() function.

    3. Use the RunSolutionUpgradeMigrationStep() function to perform data transformation or upgrade between two versions of a solution while a solution update is occurring.

      public override void RunSolutionUpgradeMigrationStep(string solutionName, string oldVersion, string newVersion, Guid oldSolutionId, Guid newSolutionId)
{
    base.RunSolutionUpgradeMigrationStep(solutionName, oldVersion, newVersion, oldSolutionId, newSolutionId);
}

      This function expects the following parameters:

      Parameter

      Description

      solutionName

      Name of the solution

      oldVersion

      Version number of the old solution

      newVersion

      Version number of the new solution

      oldSolutionId

      GUID of the old solution.

      newSolutionId

      GUID of the new solution.

    4. Enter custom code to execute after the import completes in the AfterPrimaryImport() function.

    5. Change the default name of the package folder from PkgFolder to something else. To do so, rename the PkgFolder in the Solution Explorer pane, and then edit the return value under the GetImportPackageDataFolderName property.

      public override string GetImportPackageDataFolderName
{
    get
    {
        // WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located. 
        // Changing this name requires that you also change the correlating name in the Solution Explorer 
        return "PkgFolder";
    }
}

    6. Change the package name by editing the return value under the GetNameOfImport property.

      public override string GetNameOfImport(bool plural)
{
     return "Package Short Name";
}

      This is the name of your package that will appear on the package selection page in the CRM Package Deployer wizard.

    7. Change the package description by editing the return value under the GetImportPackageDescriptionText property.

      public override string GetImportPackageDescriptionText
{
       get { return "Package Description"; }
}

      This is the package description that will appear alongside the package name on the on the package selection page in the Package Deployer wizard.

    8. Change the package long name by editing the return value under the GetLongNameOfImport property.

      public override string GetLongNameOfImport
{
     get { return "Package Long Name"; }
}

      The package long name appears on the next page after you have selected the package to install.

  3. Additionally, the following function and variables are available to the package:

    Name

    Type

    Description

    CreateProgressItem

    Function

    Used to create a new progress item in the UI.

    RaiseUpdateEvent

    Function

    Used to update the progress created by the call to CreateProgressItem.

    ProgressPanelItemStatus is an enum:

    public enum ProgressPanelItemStatus
{
    Working = 0,
    Complete = 1,
    Failed = 2,
    Warning = 3,
    Unknown = 4
}

    RaiseFailEvent

    Function

    Used to fail the current status import with an exception message.

    IsRoleAssoicatedWithTeam

    Function

    Used to determine if a role is associated with a specified team.

    IsWorkflowActive

    Function

    Used to determine if a specified workflow is active.

    PackageLog

    Class Pointer

    This is a pointer to the initialized logging interface for the package. This interface is utilized by a package to log messages and exceptions to the package log file.

    RootControlDispatcher

    Variable

    This is a dispatcher interface utilized to allow your control to render its own UI during package deployment. You would utilize this interface to wrap any UI elements or commands. It is important to check this variable for null values before using it as it may or may not be set to a value.

    CrmSvc

    Variable

    This is a pointer to Microsoft.Xrm.Tooling.Connector that allows for a package to address CRM from within the package. This class would be utilized to execute actions in the overridden methods.

    You can use any of these functions or variables using the this keyword:

    Keyword used to include functions or variables

  4. Save your project, and then build it (Build > Build Solution) to create the package. The entire contents in the <Project>\Bin\Debug folder is your package. Note that an assembly file (.dll) is created with the same name as yourVisual Studio project name; this file contains the custom code that that you created in this section.

Deploy a package

After you create a package, you can deploy it on the CRM instance by using either the Package Deployer tool or Windows PowerShell. For detailed information, see Deploy packages using CRM Package Deployer or Windows PowerShell.

Best practices for creating and deploying packages

While creating packages, developers must ensure that the package assemblies are signed.

While deploying the packages, CRM administrators must:

  • Insist on a signed package assembly so that you can track an assembly back to its source.

  • Test the package on a pre-production instance (preferably a mirror image of the production instance) before running it on a production instance.

  • Back up the production instance before deploying the package.

See Also

What's new for developers