Quick Start Web API with PowerShell and Visual Studio Code
PowerShell is a powerful scripting language that can automate repetitive tasks and streamline workflows, making it an ideal tool for integrating with Dataverse. This quick start focuses on helping you get started using PowerShell with the Dataverse Web API in Visual Studio Code. Visual Studio Code with PowerShell provides an alternative to using API clients like Postman or Insomnia.
In this quick start, learn how to:
- Use Visual Studio Code with PowerShell to interactively authenticate with Dataverse without registering an application.
- Compose requests to the Dataverse Web API using the PowerShell Invoke-RestMethod cmdlet.
Note
This Quick Start article only introduces basic concepts. This should be enough for basic testing. After your complete the steps in this article, go to Use PowerShell and Visual Studio Code with the Dataverse Web API to learn more advanced capabilities that will make you more productive, such as how to:
- Create reusable functions
- Handle exceptions
- Manage Dataverse service protection limits
- Debug using Fiddler
- Download the Dataverse Web API CSDL $metadata document
The instructions in this article should work for Windows, Linux, and macOS, but these steps have only been tested on Windows. If changes are needed, please let us know using the Feedback section at the bottom of this article.
Prerequisites
Don't proceed without confirming each of the following prerequisites are met.
Install or verify that the following are installed
Install Visual Studio Code. See Download Visual Studio Code
Install the PowerShell extension for Visual Studio Code. See PowerShell for Visual Studio Code
Install PowerShell 7.4 or higher. See Install PowerShell on Windows, Linux, and macOS
Install the Az PowerShell module version 11.1.0 or higher. See How to install Azure PowerShell
To update an existing installation to the latest version, use
Update-Module -Name Az -Force
Verify installation
Open Visual Studio Code.
In the Terminal menu, select New Terminal.
In Visual Studio Code navigation pane, select the
icon for the PowerShell extension.
Copy and paste the following script in the Visual Studio Code terminal window:
Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString() Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version
Press Enter. The output should resemble the following:
PowerShell Version: 7.4.0 PowerShell Az version: 11.1.0
If you don't see results like this, install or update the prerequisites.
You'll also need
- A valid user account for a Dataverse environment
- The Url to the Dataverse environment you want to connect to. See View developer resources to learn how to find it. It looks something like this:
https://yourorg.crm.dynamics.com/
, whereyourorg.crm
is different. - Basic understanding of the PowerShell scripting language
Try it
In Visual Studio Code, select File > New Text File, or Ctrl+N to open a new file.
You don't need to save the file.
Copy and paste the following script into the new file.
$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this ## Login if not already logged in if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) { Connect-AzAccount | Out-Null } # Get an access token $token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token # Common headers $baseHeaders = @{ 'Authorization' = 'Bearer ' + $token 'Accept' = 'application/json' 'OData-MaxVersion' = '4.0' 'OData-Version' = '4.0' } # Invoke WhoAmI Function Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders | ConvertTo-Json
Visual Studio Code should automatically detect it's a PowerShell script.
Edit the
$environmentUrl
variable value (https://yourorg.crm.dynamics.com/
) to match your Dataverse environment URL.Press F5, or use the Visual Studio Code Run > Start Debugging menu command.
A browser window opens. In the browser window, enter or select the credentials you want to use to authenticate.
Verify the output in the Visual Studio Code terminal window.
At the bottom of the terminal, find the WhoAmIResponse complex type value expected for the WhoAmI function. It should look something like this:
{ "@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse", "BusinessUnitId": "639dea3c-505c-4c3a-b8b5-d916cb507e1e", "UserId": "d2159662-498a-406b-83cd-f515b7e561d6", "OrganizationId": "83e197ed-ede1-4886-81f2-f41fe9395297" }
In the terminal window, type
cls
to clear the terminal content.Press F5, or use the Visual Studio Code Run > Start Debugging menu command to run the script again.
Because you're already logged in, the browser window doesn't open. You can continue to edit and run your script to try different requests.
How it works
This section describes the details of the PowerShell script included in the Try it section.
Authentication
The script uses the Az PowerShell module Get-AzTenant command to get tenants authorized for the current user. When you aren't logged in, this command returns an error. This script uses the -ErrorAction SilentlyContinue
parameter to ignore the error and nothing is returned.
When the Get-AzTenant
command doesn't return anything, the script uses the Connect-AzAccount
to open an interactive browser window where you can enter or select your credentials to sign in. Learn more about signing into Azure PowerShell interactively or noninteractively with a service principal.
Finally, the script uses the Get-AzAccessToken command with the -ResourceUrl $environmentUrl
to get a
PSAccessToken instance, which contains a string Token property that is an access token you can use to authenticate with Dataverse.
When you want to connect with a different set of credentials, you need to use the Disconnect-AzAccount command.
Authenticate using different shell environments
Azure PowerShell works using Windows PowerShell and PowerShell shell environments, but not Cmd and Bash shell environments. If you want to authenticate with Cmd or Bash shell environments, you can use the Azure CLI.
This script uses Azure CLI commands to authenticate:
$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (az account tenant list --only-show-errors)) {
az login --allow-no-subscriptions | Out-Null
}
# Get token
$token = az account get-access-token --resource=$environmentUrl --query accessToken --output tsv
This table shows the equivalent Az PowerShell and Azure CLI commands:
Az PowerShell | Azure CLI | Description |
---|---|---|
Get-AzTenant | az account tenant list | Try to retrieve a list of tenants to detect if you're already logged in |
Connect-AzAccount | az login | To log in to Azure |
Get-AzAccessToken | az account get-access-token | To get an access token |
Disconnect-AzAccount | az logout | Log out of Azure |
Use Invoke-RestMethod
with the WhoAmI function
Once you have an access token set to the $token
variable, you need to compose the request to Dataverse Web API and send it using the Invoke-RestMethod cmdlet
Set headers
All Dataverse Web API requests must include a set of common HTTP request headers, including a Authorization
header that includes the access token value. Some operations require more headers. Learn more about Dataverse Web API request headers
# Common headers
$baseHeaders = @{
'Authorization' = 'Bearer ' + $token
'Accept' = 'application/json'
'OData-MaxVersion' = '4.0'
'OData-Version' = '4.0'
}
Send the Request
The WhoAmI function is one of the simplest Dataverse operations you can perform. Because it's an OData function rather than an action, it requires the GET
HTTP method. Learn more about Web API functions
Use the Invoke-RestMethod cmdlet Uri
, Method
, and Headers
parameters to send this request.
# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json
For operations that use POST
or PATCH
HTTP methods, set use the Body
parameter to send the JSON payload.
The ConvertTo-Json cmdlet converts the object returned to a JSON-formatted string that is easy to see in the terminal.
If you want to capture only the UserId
property of the response, you can use the following script instead:
# Get UserId
$userId = (
Invoke-RestMethod `
-Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
-Method 'Get' `
-Headers $baseHeaders
).UserId
Write-Host $userId
Troubleshooting
Make sure you verify all the required programs are installed as described in Verify installation.
The following are situations that can cause the instructions in this quick start to fail:
Nothing happens when I press F5
Make sure that your function keys are enabled on your keyboard by pressing the F-Lock, Fn Lock, or Function Lock key on your keyboard.
You can also use the Visual Studio Code Run > Start Debugging menu command instead.
No such host is known
If you see this error after running the script:
Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 | Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| No such host is known.
Check that the $environmentUrl
represents an environment you have access to. Make sure you changed it from the default value (https://yourorg.crm.dynamics.com/
).
The user is not a member of the organization
If you see this error after running the script:
Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 | Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| { "error": { "code": "0x80072560", "message": "The user is not a member of the organization." } }
Make sure that the account you select in the browser window is that account that has access to the Dataverse environment specified by the $environmentUrl
parameter.
If you're using a different set of credentials than you used before, use the Disconnect-AzAccount command in the terminal window.
WARNING: TenantId '<your tenant id>' contains more than one active subscription
When you run the script for the first time and login using the browser, you might get this warning:
WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use.
To select another subscription, use Set-AzContext.
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`.
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.
You can ignore this warning if you see it. These requests don't require a subscription.
Next steps
Learn more advanced capabilities to be more productive using PowerShell and Visual Studio Code with the Dataverse Web API, such as how to:
- Create reusable functions
- Handle exceptions
- Manage Dataverse service protection limits
- Debug using Fiddler
- Download the Dataverse Web API CSDL $metadata document
Now that you have the ability to authenticate and send Dataverse Web API requests using PowerShell, you can try other Web API operations.
Learn more about Dataverse Web API capabilities by understanding the service documents.