Microsoft.Xrm.Data.PowerShell

Overview

Microsoft.Xrm.Data.Powershell contains two modules, the first is Microsoft.Xrm.Tooling.CrmConnector.Powershell which is owned and maintained by Microsoft, the second is Microsoft.Xrm.Data.Powershell which is a wrapper over this connector providing helpful functions.

Installation Options:

• PREFERRED Install via PowerShell - Gallery Link: https://www.powershellgallery.com/packages/Microsoft.Xrm.Data.Powershell/
• Use only if absolutely required Install via a downloaded zip (Primarily used for troubleshooting or cannot install from the gallery)

How the module works
How to get a list of the commands
About the Authors

New releases of this can be found on the Release Page or can be downloaded using OneGet (Install-Module) from the Powershell Gallery.

Microsoft.Xrm.Data.Powershell

This module builds from Microsoft.Xrm.Tooling.CrmConnector.Powershell, on top of this we are providing common functions to create, delete, query, and update data. We have also included many helpful functions for common tasks such as publishing, and manipulating System & CRM User Settings, etc. The module will function for both Dynamics CRM Online and On-Premise environments. Note: while you can import or create data this utility was not specifically designed to do high throughput data imports. For data import please refer to our blog at https://aka.ms/CRMInTheField - you may also review sample code written to add high speed/high throughput data manipulation to .NET projects posted by Austin Jones & Sean McNellis at: https://github.com/seanmcne/XrmCoreLibrary

Microsoft.Xrm.Tooling.CrmConnector.Powershell

This module comes from Dynamics CRM SDK and it exposes two functions, Get-CrmOrganizations and Get-CrmConnection. See the link for more detail. Use PowerShell cmdlets for XRM tooling to connect to CRM - (For reference, click for the Previous Documentation Url)

Preferred: Install the module via PowerShell Gallery

Note this method requires: Powershell Management Framework 5 or higher - details: https://www.powershellgallery.com/

Install-Module Microsoft.Xrm.Data.PowerShell -Scope CurrentUser

To Update to a newer release of the module

Update-Module Microsoft.Xrm.Data.PowerShell -Force

Troubleshooting:

1. Try adding the -verbose flag to your install and update module commands - this should give you more information
2. As this module is not signed, you may need to change Execution Policy to load the module. You can do so by executing the following command then try again

 Set-ExecutionPolicy –ExecutionPolicy RemoteSigned –Scope CurrentUser

3. If powershell is out of date and doesn't support TLS 1.2 by default - enable it to use TLS 1.2 by executing the following command, then try again

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12

Alternative: How to file copy or manually deploy this module - Only if absolutely required

1. Go to Releases(https://github.com/seanmcne/Microsoft.Xrm.Data.PowerShell/releases) and Download Microsoft.Xrm.Data.Powershell.zip.
2. Right click the downloaded zip file and click "Properties".
3. Check "Unblock" checkbox and click "OK", or simply click "Unblock" button depending on OS versions.

4. Extract the zip file and copy "Microsoft.Xrm.Data.PowerShell" folder to either one of the following folders - one is for a user only scope, the second is for a system-wide scope (for all users):

• %USERPROFILE%\Documents\WindowsPowerShell\Modules
• %WINDIR%\System32\WindowsPowerShell\v1.0\Modules

5. As this module is not signed, you may need to change Execution Policy to load the module. You can do so by executing following command.

 Set-ExecutionPolicy –ExecutionPolicy RemoteSigned –Scope CurrentUser

      Refer to Set-ExecutionPolicy for more information.

6. Open PowerShell and run following command to load the module.

#Import Micrsoft.Xrm.Data.Powershell module 
Import-Module Microsoft.Xrm.Data.Powershell

• The module is not compatible yet with PowerShell Core and must use v4 or v5 - this is due to the dependency on XrmTooling. If there is an update for XrmTooling we will explore porting this to work with that new module depending on the amount of effort required.

How Microsoft.Xrm.Data.Powershell works

Microsoft.Xrm.Data.Powershell module exposes many functions, but you can use Connect-CrmOnlineDiscovery, Connect-CrmOnPremDiscovery to connect to any CRM organization by using Discovery Service. Use Connect-CrmOnline function for Azure Automation. By executing these function, it creates $conn global variable. Any other functions which needs to connect to the CRM Organization takes connection parameter. You can explicitly specify the connection by using -conn parameter, but if you omit the connection, functions retrieve connection from global variable.

Alternatively, you can create multiple connection objects and pass them into each function under the –conn parameter.

Example

This example shows how to create connection and do CRUD operation as well as manipulate System Settings.

1. Run following command to connect to Dynamics CRM Organization via the Xrm Tooling GUI.

# Online - use oAuth and XrmTooling Ui by providing your UPN and the enviroment url
connect-crmonline -Username "[email protected]" -ServerUrl <orgurl>.crm.dynamics.com

# OnPrem sample using discovery
Connect-CrmOnPremDiscovery -InteractiveMode

# Azure Automation example
# this uses an application user - see here for more details: https://docs.microsoft.com/en-us/power-platform/admin/create-users-assign-online-security-roles#create-an-application-user
$oAuthClientId = "00000000-0000-0000-0000-000000000000"
$encryptedClientSecret = Get-AutomationVariable -Name ClientSecret
Connect-CrmOnline -ClientSecret $encryptedClientSecret -OAuthClientId $oAuthClientId -ServerUrl "https://<org>.crm.dynamics.com"

For Azure Automation, write all scripts inside inlinescript block as Runbook or use PowerShell type. When using Azure automation or any non-end-user connection (headless) an ApplicationUser should be used - for details on how to create an application user see here: https://docs.microsoft.com/en-us/power-platform/admin/create-users-assign-online-security-roles#create-an-application-user

2. Run following command to test CRUD.

# Create an account and store record Guid to a variable 
$accountId = New-CrmRecord -conn $conn -EntityLogicalName account -Fields @{"name"="Sample Account";"telephone1"="555-5555"} 
 
# Display the Guid 
$accountid 
 
# Retrieve a record and store record to a variable 
$account = Get-CrmRecord -conn $conn -EntityLogicalName account -Id $accountId -Fields name,telephone1 
 
# Display the record 
$account 
 
# Set new name value for the record 
$account.name = "Sample Account Updated" 
 
# Update the record 
Set-CrmRecord -conn $conn -CrmRecord $account 
 
# Retrieve the record again and display the result 
Get-CrmRecord -conn $conn -EntityLogicalName account -Id $accountId -Fields name 
 
# Delete the record 
Remove-CrmRecord -conn $conn -CrmRecord $account

3. Run following command to manipulate SystemSettings.

# Display the current setting 
Get-CrmSystemSettings -conn $conn -ShowDisplayName 
 
# Change the PricingDecimalPrecision system setting from 0 to 1 
Set-CrmSystemSettings -conn $conn -PricingDecimalPrecision 1 
 
# Display the current setting 
Get-CrmSystemSettings -conn $conn -ShowDisplayName

How to get command details

Each command has detail explanation.

1. Run following command to get all commands.

Get-Command *crm*

2. Run following command to get help.

Get-Help New-CrmRecord -Detailed

About Authors

This module is implemented by Sean McNellis and Kenichiro Nakamura, these helper functions make use of the Microsoft provided powershell module hosted (standalone) here: https://www.powershellgallery.com/packages/Microsoft.Xrm.Tooling.CrmConnector.PowerShell/.

Sean McNellis, Principal Cloud Solution Architect based out of North America and working with Business Applications on Dynamics & PowerPlatform. Kenichiro Nakamura, Sr. Software Engineer based out of Japan.

Blog (English): http://aka.ms/CrmInTheField Blog (Japanese): http://blogs.msdn.com/CrmJapan Twitter: @pfedynamics

Current Powershell Gallery location is here: https://www.powershellgallery.com/packages/Microsoft.Xrm.Data.Powershell