Deploy packages using Dynamics CRM Package Deployer and Windows PowerShell

Applies to Dynamics 365 (online), version 9.x
Applies to Dynamics 365 (online), version 8.x

Microsoft Dynamics CRM Package Deployer enables administrators to deploy packages on a Dynamics 365 (on-premises) or Dynamics 365 (online) instance. A “package” can consist of any or all of the following:

  • One or more Dynamics 365 solution files.

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

  • Custom code that can run during or after the package is deployed to Dynamics 365.

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

    Developers create packages by using the package deployment template in Visual Studio. More information: Create packages for the Dynamics 365 Package Deployer

    After a package is created, you can deploy it either by running CRM Package Deployer or by using Windows PowerShell cmdlets for the tool.

Important

Before you import and run a package in a production organization, test the package on a non-production mirror image of the production organization.

Always back up the production organization before you deploy a package.


Deploying packages using the Package Deployer tool

You can use the Package Deployer tool (packagedeployer.exe) to deploy packages in the following ways.

Use CRM Package Deployer tool to deploy packages

Use CRM Package Deployer tool at the command line

Use Package Deployer tool to deploy packages

The Package Deployer tool can only process one package at a time. However, it provides users with the ability to select a package to deploy from multiple packages available in the Package Deployer tool directory. Some of the screens and actions in the tool differ based on the package definition. You do not have to install the Package Deployer tool. Just download and run it.

  1. Obtain the package to be deployed. A package is a collection of files and folders that is created in your Visual studio project folder (<Project>\Bin\Debug) when you build your package project in Visual Studio. Copy the following from your project debug folder:

    • <PackageName> folder: This folder contains the solutions, import configuration, and the contents for your package.

    • <PackageName>.dll: The assembly contains the code for your package. By default, the name of the assembly is the same as your Visual Studio project name.

      For detailed information about creating a package by using Visual Studio, see Create a package for the Package Deployer tool.

      For this topic, let us assume that the package folder and assembly from the Visual Studio project debug folder (<Project>\Bin\Debug) are copied to the c:\DeployPackage folder.

  2. Obtain the Package Deployer tool. The Package Deployer tool is available as a NuGet package. To use the Package Deployer, you must download and extract it to your local computer using nuget.exe.

    Download nuget.exe from https://www.nuget.org/downloads, and save it to your computer, say d:\. Then run the following command at the command prompt to extract the package contents to a folder, say PD, on your computer:
    d:\nuget install Microsoft.CrmSdk.XrmTooling.PackageDeployment.Wpf -Version [VERSION] -O d:\PD

    After you have extracted the Package Deployer tool, browse to the [ExtractedLocation]\tools folder to find the PackageDeployer.exe file.

  3. Copy the package folder and assembly from the c:\DeployPackage to the [ExtractedLocation]\tools folder.

  4. After the files are copied, run the tool by double-clicking the PackageDeployer.exe file in the [ExtractedLocation]\tools folder.

  5. Click Continue on the main screen of the tool.

  6. In the Connect to Microsoft Dynamics 365 screen, provide authentication details to connect to your Dynamics 365 server where you want to deploy the package. If you have multiple organizations, and want to select the organization where you want to deploy the package, select the Always display list of available orgs check box. Click Login.

  7. If you have multiple organizations on your Dynamics 365 server, select a Dynamics 365 organization to connect to.

  8. Select the package to be deployed, and click Next.

    Select your package in the Package Deployer Tool

  9. Follow the instructions on the subsequent screens to complete the deployment of your package.

    The screens appear based on the definition of the package that you selected for deployment. For an end-to-end package deployment that uses the Package Deployer tool, see the topic for the deployment of Unified Service Desk packages: Deploy sample Unified Service Desk applications to CRM Server using Package Deployer

Use Package Deployer tool at the command line

System administrators and customizers can pass parameters, such as a regional language code, to packagedeployer.exe from the command line. These parameters may only be configured by running Package Deployer tool at the command line.

Note

This feature was first introduced in Dynamics CRM Online 2016 Update 0.1.

Available parameters are in this table.

Parameter Description Default Value
RuntimePackageSettings Instructs packagedeployer.exe to accept command line parameters such as LCID and SkipChecks. Not applicable
LCID=localeID Specifies the locale ID, such as 1033 for English-United States or 1036 for French-France, from the available locale IDs in the package. If not specified, the default language will be used. Use the default language
SkipChecks=true/false Use this parameter only when the target environment does not contain any other solutions or customizations. When set to true, solution import will bypass some safety checks, which can improve performance of the import. False

The following example instructs CRM Package Deployer to bypass some safety checks and sets the language to import as Polish.

packagedeployer.exe RuntimePackageSettings SkipChecks=true | lcid=1045  

Note

Use the pipe character | to separate parameters when you run packagedeployer.exe at the command line with multiple parameters.

For more information about the parameters and values that can be passed to packagedeployer.exe, see Create packages for the CRM Package Deployer.

Use Windows PowerShell to deploy packages

The Package Deployer tool also provides Windows PowerShell support to deploy packages.

Perform the following steps to use the PowerShell cmdlets to deploy packages:

Prerequisites

Import the Package Deployer PowerShell module

Use the cmdlet to retrieve packages

Use the cmdlet to connect to your Dynamics 365 server

Use the cmdlet to deploy packages

Get detailed help on cmdlets

Prerequisites

Here are the prerequisites for using the PowerShell cmdlets:

  • PowerShell 3.0 or later is required to deploy a package by using PowerShell. To check your PowerShell version, run a PowerShell window, and then run the following command: $Host

  • Set the execution policy to run the signed PowerShell scripts. To do so, run a PowerShell window as an administrator, and then run the following command: Set-ExecutionPolicy -ExecutionPolicy AllSigned

Import the Package Deployer PowerShell module

You must import the Windows PowerShell module for the Package Deployer tool before you can use it. To import:

  1. Obtain the PowerShell files for the Package Deployer. The PowerShell files for the Package Deployer tool are available as a NuGet package. To use them, you must download and extract it to your local computer using nuget.exe.

    Download nuget.exe from https://www.nuget.org/downloads, and save it to your computer, say d:\. Then run the following command at the command prompt to extract the package contents to a folder, say PD-PowerShell, on your computer:
    d:\nuget install Microsoft.CrmSdk.XrmTooling.PackageDeployment.PowerShell -Version [VERSION] -O d:\PD-PowerShell

    After you have extracted the PowerShell files for the Package Deployer tool, browse to the [ExtractedLocation]\tools folder to find the required files.

  2. Start Windows PowerShell on your computer with elevated privileges (run as administrator).

  3. At the prompt in the Windows PowerShell window, change your directory to the folder where you extracted the files. In this case:

    cd [ExtractedLocation]\tools\  
    
  4. Run the RegisterXRMPackageDeployment.ps1 script available at the [ExtractedLocation]\tools folder by running the following command:

    .\RegisterXRMPackageDeployment.ps1  
    

    You are now ready to use the Windows PowerShell cmdlets. To list the cmdlets that you registered, run the following command at the prompt in the Windows PowerShell window:

Get-Help “Crm”  

Use the cmdlet to retrieve packages

Before you can use the cmdlet, ensure that you have copied your package to the PackageDeployer folder (in this case, [ExtractedLocation]\tools). A package is a collection of files and folders that is created in your Visual Studio project folder (<Project>\Bin\Debug) when you build your project in Visual Studio. Copy the entire contents of your project debug folder to the PackageDeployer folder. For detailed information about building a package using Visual Studio, see Create packages for the CRM Package Deployer.

  1. In the PowerShell window, use the following cmdlet to return a list of packages available for import in the specified folder (in this case, c:\CRM\SDK\Tools\PackageDeployer):

    Get-CrmPackages –PackageDirectory [ExtractedLocation]\tools  
    
  2. If you want information about a package in a folder, you can use the Get-CrmPackages cmdlet along with the –PackageName parameter to specify the name of the assembly in the folder that contains the package definition.

    Get-CrmPackages –PackageDirectory [ExtractedLocation]\tools –PackageName SampleCRMPackage.dll  
    
  3. The package assembly location can be stored in a variable by using the Get-CrmPackages cmdlet. Then it may be reused in the Import-CrmPackage cmdlet to specify a value for the PackageDirectory parameter. For example, you can store the information of one or more packages returned from the Get-CrmPackages cmdlet in a variable called $MyPackages.

    $MyPackages = Get-CrmPackages –PackageDirectory [ExtractedLocation]\tools   
    

    To display all the packages.

    $MyPackages  
    

    To display only the third package.

    $MyPackages[2].PackageAssemblyLocation  
    

    Then, you can reference each package in the array from 0 through n. For example, this cmdlet imports the first package found in $MyPackages.

    Import-CrmPackage -CrmConnection $CRMConn -PackageDirectory $MyPackages[0].PackageAssemblyLocation  
    

Use the cmdlet to connect to your Dynamics 365 instance

  1. Provide your credentials to connect to your Dynamics 365 (online) or Dynamics 365 (on-premises) instance. Running the following command will prompt you to type your user name and password to connect to the Dynamics 365 instance, and we will store it in the $Cred variable, and use it later for connecting to your Dynamics 365 server.

    $Cred = Get-Credential  
    
  2. Use the following command to get a connection to your Dynamics 365 (online) or Dynamics 365 (on-premises) instance. We will store the connection information in the $CRMConn variable:

    • If you are connecting to the Dynamics 365 (on-premises) instance:

      $CRMConn = Get-CrmConnection -ServerUrl http://<your_CRM_Server> -OrganizationName <your_Org_Name> -Credential $Cred  
      
    • If you are connecting to the Dynamics 365 (online) server:

      $CRMConn = Get-CrmConnection -DeploymentRegion NorthAmerica –OnlineType Office365 –OrganizationName <your_Org_Name> -Credential $Cred  
      

      Note

      For the DeploymentRegion parameter, valid values are NorthAmerica, EMEA, APACSouthAmerica, Oceania, JPN, and NorthAmerica2. For the OnlineType parameter, valid values are Office365 and LiveID.

  3. Your supplied credentials are validated when you run the command in step 2.

Use the cmdlet to deploy packages

Next, use the Dynamics 365 connection information stored in the $CRMConn variable to deploy packages to the Dynamics 365 instance. The following command deploys a package, disassembles the package in the c:\UnpackedFiles folder, and records information to a log file in the c:\MyLogFiles folder.

Import-CrmPackage –CrmConnection $CRMConn –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer –PackageName SampleCRMPackage.dll –UnpackFilesDirectory c:\UnpackedFiles -LogWriteDirectory C:\MyLogFiles -Verbose  

Note

  • CrmConnection, PackageDirectory, and PackageName parameters are mandatory.
  • Instead of manually specifying the package folder, you can use a variable with the PackageDirectory parameter. More information: Use the cmdlet to retrieve packages
  • For the PackageName parameter, you have to specify the name of the assembly that contains the package definition.
  • You do not need to specify the UnpackFilesDirectory parameter if your package does not unpack files during package deployment. While defining a package in Visual Studio, you specify whether to unpack files using the agentdesktopzipfile parameter in the ImportConfig.xml file. More information: Create packages for the CRM Package Deployer
  • The Verbose parameter is optional, and is used to display a detailed log of the activities performed during the package deployment process.
  • The optional RuntimePackageSettings parameter can be used together with the following parameters:

    • The LCID=localeID parameter specifies the locale ID, such as 1033 for English-United States or 1036 for French-France, from the available locale IDs in the package. If not specified, the default language will be used.
    • The SkipChecks=true/false parameter should only be used when the target environment does not contain any other solutions or customizations. When set to true, solution import will bypass some safety checks, which can improve import performance.
  • The folder that you specify when you use the LogWriteDirectory parameter must already exist, and the user who is running the Import-CrmPackage cmdlet must have write permission to the folder. Additionally, the -Verbose parameter is required when you use the LogWriteDirectory parameter.

    The LogWriteDirectory parameter was first introduced with Dynamics 365 (online), version 9.0. More information: Dynamics 365 Customer Engagement Developer Guide

The following example command imports a package named SampleCRMPackage and specifies English-United States (1033) as the language to import the package.

Import-CrmPackage –CrmConnection $CRMConn –PackageDirectory c:\CRM\SDK\Tools\PackageDeployer –PackageName SampleCRMPackage.dll –UnpackFilesDirectory c:\UnpackedFiles –RuntimePackageSettings LCID=1033  

Get detailed help on cmdlets

In the PowerShell window, use the Get-Help cmdlet with a cmdlet name to view a detailed help for the cmdlet. For example, to get detailed help for the Import-CrmPackage cmdlet:

Get-Help Import-CrmPackage -full  

To view the online help for the cmdlets, see Dynamics 365 PowerShell Reference.

Troubleshoot package deployment issues by using log files

The Package Deployer tool provides logging support to get detailed information about errors that can occur when someone signs in to the Microsoft Dynamics 365 instance using the tool and deploying packages. By default, the tool generates three log files that are available at the following location on the computer where you run the tool: c:\Users\<UserName>\AppData\Roaming\Microsoft\Microsoft Dynamics CRM Package Deployer\<Version>. To specify a different folder, use the -LogWriteDirectory PowerShell cmdlet parameter. More information: Use the cmdlet to retrieve packages

  • Login_ErrorLog.log: Provides information about the issues that occurred when you use the tool to sign in to the Dynamics 365 instance. If there are any issues during sign in, a message appears on the tool’s login screen with a link to this log file. The message states that an error occurred while processing the login request and the user can view the error log. You can click the link in the message to view this log file. The log file is created the first time you encounter any sign-in issues in the tool. Thereafter, the log file is used to log information about a sign-in issue, whenever it occurs.

  • PackageDeployer.log: Provides detailed information about each task performed in the tool during the deployment of the packages. You can view the log file from the tool by clicking the View Log File link at the bottom of the screen.

  • ComplexImportDetail.log: Provides detailed information about the data imported in the last deployment by using the tool. Each time you deploy a package using this tool, the existing details from the log file are moved to a file called ComplexImportDetail._old.log in the same directory, and the ComplexImportDetail.log file displays information about the latest import done using the tool.

Best practices for deploying packages

While deploying packages, Dynamics 365 administrators must:

  • Insist on a signed package assembly so that they 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 server.

  • Back up the production instance before deploying a package.

See also

Create packages for the CRM Package Deployer