Web API Conditional Operations Sample (PowerShell)

This PowerShell version 7.4.0 sample demonstrates how to perform operations that are conditionally based upon the version of the table row contained on the Microsoft Dataverse server and/or currently maintained by the client. This sample implements the Dataverse operations and console output detailed in Web API Conditional Operations Sample.

View this sample on Github

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:

• Quick Start Web API with PowerShell and Visual Studio Code
• Use PowerShell and Visual Studio Code with the Dataverse Web API

These articles have the same prerequisites.

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

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 ConditionalOperations.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/ConditionalOperations/ConditionalOperations.ps1

Demonstrates

This sample has four regions:

Section 0: Create sample records

Operations: Create an account record and retrieve it to capture the initial ETag value.

Section 1: Conditional GET

Operations:

• Attempt to retrieve the account using If-None-Match header with the initial ETag value, demonstrating that a 304 NotModified response is returned when the record hasn't changed.
• Update the account's telephone number.
• Attempt to retrieve the account again using If-None-Match header with the initial ETag value, demonstrating that the full record is returned because it has been modified.

Section 2: Optimistic concurrency on delete and update

Operations:

• Attempt to delete the account using If-Match header with the initial ETag value, demonstrating that a 412 PreconditionFailed error is returned when the ETag doesn't match.
• Attempt to update the account using If-Match header with the initial ETag value, demonstrating that a 412 PreconditionFailed error is returned when the ETag doesn't match.
• Update the account using If-Match header with the current ETag value, demonstrating that the update succeeds when the ETag matches.
• Retrieve the account to confirm the update.

Section 3: 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
Perform conditional operations using the Web API
Quick Start Web API with PowerShell and Visual Studio Code
Use PowerShell and Visual Studio Code with the Dataverse Web API
Web API Samples
Web API Conditional Operations Sample
Web API Conditional Operations Sample (C#)
Web API Conditional Operations Sample (Client-side JavaScript)