Get started using the package deployment module
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).
Perform the following steps to use the PowerShell cmdlets to deploy packages:
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
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
You must install the PowerShell module for the Package Deployer tool before you can use it. To install:
Start PowerShell on your computer with elevated privileges (run as administrator).
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”
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.
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
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
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
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
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 areNorthAmerica
,EMEA
, APACSouthAmerica
,Oceania
,JPN
, andNorthAmerica2
. For theOnlineType
parameter, valid values areOffice365
andLiveID
.
Your supplied credentials are validated when you run the command in step 2.
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
, andPackageName
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 packagesFor 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 DeployerThe
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
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
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.
- For information about best practices and how to troubleshoot package deployer, go to Deploy packages using Package Deployer and Windows PowerShell.
- For the module cmdlet reference, go to Microsoft.Xrm.Tooling.PackageDeployment Module.