Get started using the package deployment module

  • Article

The Dataverse package deployment (Microsoft.Xrm.Tooling.PackageDeployment) PowerShell module is used to deploy packages to Dataverse environments and Dynamics 365 Customer Engagement (on-premises) deployments. A package is a compressed (zipped) folder that can consist of one or more solution files, flat files or exported data files from the Configuration Migration tool, custom code that can run during or after the package is deployed, and HTML content specific to the package that can display at the beginning and end of the package deployment process.

This module works with both Dataverse and Dynamics 365 Customer Engagement (on-premises).

Use Windows PowerShell to deploy packages

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

Prerequisites

Install 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

Install the Package Deployer PowerShell module

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

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

  2. At the prompt in the Windows PowerShell window, enter the following command to install the module:

       Install-Module Microsoft.Xrm.Tooling.PackageDeployment.Powershell

You're now ready to use the PowerShell cmdlets. To list the cmdlets that you registered, run the following command at the prompt in the 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 Power Apps environment or Dynamics 365 customer engagement instance

  1. Provide your credentials to connect to your Power Apps environment, Dynamics 365 customer engagement apps instance, or Dynamics 365 Customer Engagement (on-premises) organization. Running the following command will prompt you to type your user name and password to connect, and we will store it in the $Cred variable, and use it later for connecting to your environment.

    $Cred = Get-Credential

  2. Use the following command to get a connection to your environment. We will store the connection information in the $CRMConn variable:

    • If you are connecting to the Dynamics 365 for Customer Engagement apps (on-premises) organization:

      $CRMConn = Get-CrmConnection -ServerUrl https://<your_CRM_Server> -OrganizationName <your_Org_Name> -Credential $Cred

    • If you are connecting to the Dynamics 365 customer engagement 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 connection information stored in the $CRMConn variable to deploy packages. 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 for Customer Engagement apps 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 for Customer Engagement apps PowerShell Reference.

See also