Web API Query schema definitions and detect changes sample (C#)

Note

Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

This sample shows how to retrieve and detect changes in table definitions using the RetrieveMetadataChanges Action.

You can view the sample at PowerApps-Samples/dataverse/webapi/C#-NETCore/Schema/RetrieveMetadataChanges/

See these topics for explaination of functionality:

This sample uses the common helper code in the WebAPIService class library (C#).

Prerequisites

The following is required to build and run this sample:

  • Microsoft Visual Studio 2022.
  • Access to Dataverse with privileges to perform data operations.

How to run this sample

  1. Clone or download the PowerApps-Samples repository.

  2. Locate the /dataverse/webapi/C#-NETx/RetrieveMetadataChanges/ folder.

  3. Open the RetrieveMetadataChanges.sln file using Visual Studio 2022

  4. Edit the appsettings.json file to set the following property values:

    Property Instructions
    Url The Url for your environment. Replace the placeholder https://yourorg.api.crm.dynamics.com value with the value for your environment. See View developer resources to find this.
    UserPrincipalName Replace the placeholder you@yourorg.onmicrosoft.com value with the UPN value you use to access the environment.
    Password Replace the placeholder yourPassword value with the password you use.
  5. Save the appsettings.json file

  6. Press F5 to run the sample.

Code

The code for this sample is here: PowerApps-Samples/dataverse/webapi/C#-NETx/RetrieveMetadataChanges/Program.cs

Demonstrates

This sample shows how to retrieve schema definitions for a specific set of column definitions and save them (in memory) to represent a cache.

Then it creates a new column, retrieves the data for only that new column, which it adds to the cache.

Then it deletes the column, retrieves data about deleted items and uses it to remove the deleted column definition from the cache.

This sample has 6 sections:

Define query

Define a query using EntityQueryExpression that will return all the Picklist choice columns from the contact table.

Initialize cache

  1. Create an instance of RetrieveMetadataChanges with the Query parameter set to the query.
  2. Send the request and get a RetrieveMetadataChangesResponse.
  3. Cache the RetrieveMetadataChangesResponse.EntityMetadata value.
  4. Save the RetrieveMetadataChangesResponse.ServerVersionStamp value for use in the next request.
  5. Write a list of all the current columns in the cache.

Add choice column

Create a new choice column by creating a new PicklistAttributeMetadata instance in the contact table.

Detect added column

  1. Create a new instance of RetrieveMetadataChanges with the Query parameter set to the original query.
  2. Set the RetrieveMetadataChangesRequest.ClientVersionStamp with the value previously returned from the first request.
  3. Send the request and get a RetrieveMetadataChangesResponse.
  4. Verify that only one new column definition was returned to represent the choice column that was created.
  5. Save the RetrieveMetadataChangesResponse.ServerVersionStamp value for use in the next request.
  6. Add that choice column data to the cache.

Delete choice column

Delete the choice column created earlier.

Detect deleted column

  1. Create a new instance of RetrieveMetadataChanges with the Query parameter set to the original query.
  2. Set the RetrieveMetadataChangesRequest.ClientVersionStamp with the value previously returned from the second request.
  3. Set the RetrieveMetadataChangesRequest.DeletedMetadataFilters to DeletedMetadataFilters.Attribute because we are looking for deleted column definitions.
  4. Send the request and get a RetrieveMetadataChangesResponse.
  5. Find the Id of the deleted choice column in the RetrieveMetadataChangesResponse.DeletedMetadata, using DeletedMetadataFilters.Attribute as an index value for the collection.
  6. Remove the column definition from the cache.
  7. Write a list of all the current columns in the cache.

Clean up

No clean up is required because all data created by this sample was deleted.

See also

Query Schema Definitions
Cache Schema data
Use the Dataverse Web API
WebAPIService class library (C#)
Web API Metadata Operations Sample (C#)