Share via

Deploy packages using Dynamics CRM Package Deployer and Windows PowerShell

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Note

The information provided here is for versions of Dynamics 365 prior to Dynamics 365 (online), version 9.0. For the latest documentation, see Deploy packages using Dynamics CRM Package Deployer and Windows PowerShell.

Microsoft Dynamics CRM Package Deployer enables administrators to deploy packages on a Dynamics 365 (on-premises) or Microsoft 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 configuration data.

  • Custom code that can run during or after the package is deployed to Microsoft 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 Microsoft Visual Studio. More information: MSDN: Create packages for the CRM 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.

In this topic

Deploying packages using the Package Deployer tool

Use Windows PowerShell to deploy packages

Troubleshoot package deployment issues by using log files

Best practices for deploying packages

Deploying packages using the Package Deployer tool

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

Use Package Deployer tool to deploy packages

Use 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 MSDN: 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. Download the Microsoft Dynamics CRM SDK. Then run the downloaded executable file to extract the contents of the package.

  3. Browse to the SDK\Tools\PackageDeployer folder, and copy the package folder and assembly from the c:\DeployPackage to the SDK\Tools\PackageDeployer folder.

  4. After the files are copied, run the tool by double-clicking the PackageDeployer.exe file in the SDK\Tools\PackageDeployer 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 Microsoft 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 /Settings:"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 MSDN: 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

Register the cmdlets

Use the cmdlet to retrieve packages

Use the cmdlet to connect to your Dynamics 365 instance

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

Register the cmdlets

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

  1. If you haven’t already done so, download the Dynamics 365 SDK package from the Microsoft Download Center, and run the package file to extract the contents of the package. Let’s assume that you extracted the package to the c:\CRM folder on your computer. The Package Deployer tool and the other required files become available at the following location: c:\CRM\SDK\Tools\PackageDeployer.

  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 Windows PowerShell folder under the PackageDeployer folder. In this case:

    cd c:\CRM\SDK\Tools\PackageDeployer\PowerShell

  4. Run the RegisterXRMTooling.ps1 script to register the Package Deployer Windows PowerShell assembly (dll), and install the Windows PowerShell snap-in for the Package Deployer tool. To do so, type the following command, and press ENTER:

    .\RegisterXRMTooling.ps1

  5. Add the Windows PowerShell snap-in for XRM tooling. This will register the following cmdlets: Get-CrmConnection and Get-CrmOrganizations.

    Add-PSSnapin Microsoft.Xrm.Tooling.Connector

  6. Add the Windows PowerShell snap-in for Package Deployer. This will register the following cmdlets: Get-CrmPackages and Import-CrmPackage.

    Add-PSSnapin Microsoft.Xrm.Tooling.PackageDeployment

You are now ready to use these 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, c:\CRM\SDK\Tools\PackageDeployer). 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 MSDN: 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 c:\CRM\SDK\Tools\PackageDeployer

  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 c:\CRM\SDK\Tools\PackageDeployer –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 c:\CRM\SDK\Tools\PackageDeployer

    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

    Note

    The PackageAssemblyLocation parameter and the ability to display the folder location and name of a package were first introduced with December 2016 update for Dynamics 365 (online and on-premises). More information:  Dynamics 365 SDK 

Use the cmdlet to connect to your Dynamics 365 instance

  1. Provide your credentials to connect to your Microsoft 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 Microsoft 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 Microsoft 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: MSDN: 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 December 2016 update for Dynamics 365 (online and on-premises). More information:  Dynamics 365 SDK

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

MSDN: Create packages for the CRM Package Deployer
Administering Dynamics 365

© 2017 Microsoft. All rights reserved. Copyright