Edit

Web API Basic Operations Sample (PowerShell)

  • Article

This PowerShell version 7.4.0 sample demonstrates how to perform common data operations using the Dataverse Web API and Visual Studio Code. This sample implements the Dataverse operations and console output detailed in Web API Basic Operations Sample.

This sample uses the Dataverse Web API PowerShell Helper functions to manage authentication and provide reusable functions to perform common operations. These scripts are referenced using dot sourcing with the following lines:

. $PSScriptRoot\..\Core.ps1
. $PSScriptRoot\..\TableOperations.ps1
. $PSScriptRoot\..\CommonFunctions.ps1

Note

This sample should work with Windows, Linux, and macOS, but has only been tested on Windows.

Prerequisites

Before running this sample, you should read these articles that explain concepts and patterns used by these samples:

These articles have the same prerequisites.

Install or verify that the following are installed

Verify installation

  1. Open Visual Studio Code.

  2. In the Terminal menu, select New Terminal.

  3. In Visual Studio Code navigation pane, select the icon for the PowerShell extension.

  4. 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

  5. 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/, where yourorg.crm is different.
  • Basic understanding of the PowerShell scripting language

How to run this sample

  1. Clone or download the PowerApps-Samples repository.

  2. Open the BasicOperations.ps1 file using Visual Studio Code

  3. Edit this line to use the URL of the environment you want to connect to:

    Connect 'https://yourorg.crm.dynamics.com/' # change this

  4. (Optional) Set the $deleteCreatedRecords variable to $false if you don't want to delete the records this sample creates.

  5. Press F5 to run the sample.

  6. The first time you run the sample a browser window opens. In the browser window, enter or select the credentials you want to use to authenticate.

To connect as a different user, run the Disconnect-AzAccount command and try again.

Code

The code for this sample is at: PowerApps-Samples/dataverse/webapi/PS/BasicOperations/BasicOperations.ps1

Demonstrates

This sample has five regions:

Section 1: Basic Create and Update operations

Operations:

  • Create a contact record.
  • Update the contact record.
  • Retrieve the contact record.
  • Update a single property of the contact record.
  • Retrieve a single property of the contact record.

Section 2: Create record associated to another

Operations: Associate a new record to an existing one.

Operations: Create the following entries in one operation: an account, its associated primary contact, and open tasks for that contact. These entity types have the following relationships:

Accounts
    |---[Primary] Contact (N-to-1)
        |---Tasks (1-to-N)

Section 4: Associate and Disassociate records

Operations:

  • Add a contact to the account contact_customer_accounts collection.
  • Remove a contact from the account contact_customer_accounts collection.
  • Associate a security role to a user using the systemuserroles_association collection.
  • Remove a security role for a user using the systemuserroles_association collection.

Section 5: Delete sample records

Operations: A reference to each record created in this sample was added to a list as it was created. This section loops through that list and deletes each record.

Clean up

By default this sample deletes all the records created in it. If you want to view created records after the sample is completed, change the deleteCreatedRecords variable to false and you'll be prompted to decide if you want to delete the records.

See also

Use the Dataverse Web API
Quick Start Web API with PowerShell and Visual Studio Code
Use PowerShell and Visual Studio Code with the Dataverse Web API
Create a table row using the Web API
Update and delete table rows using the Web API
Retrieve an table row using the Web API
Web API Samples
Web API Basic Operations Sample