UpsertRequest Class

Definition

Namespace:

Microsoft.Xrm.Sdk.Messages

Assembly:

Microsoft.Xrm.Sdk.dll

Package:

Microsoft.PowerPlatform.Dataverse.Client v1.1.32

Contains data that is needed to update or insert a record in Dataverse.

public ref class UpsertRequest sealed : Microsoft::Xrm::Sdk::OrganizationRequest

[System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")]
public sealed class UpsertRequest : Microsoft.Xrm.Sdk.OrganizationRequest

[<System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")>]
type UpsertRequest = class
    inherit OrganizationRequest

Public NotInheritable Class UpsertRequest
Inherits OrganizationRequest

Inheritance

Object

OrganizationRequest

UpsertRequest

Attributes

DataContractAttribute

Examples

The following example shows how to use this message. For this sample to work correctly, you must be connected to the server to get an IOrganizationService interface instance.

This example demonstrates using alternate keys while using Upsert. In this case, the sample_bankaccount table has the sample_accountname column configured as an alternate key, so the value for that column is used to uniquely identify the record instead of the primary key value. The sample_description is the only value in the Entity.Attributes collection.

/// <summary>
/// Demonstrates an upsert operation using alternate keys
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance</param>
static void UpsertExample(IOrganizationService service)
{
      string tableLogicalName = "sample_bankaccount";
      string keyName = "sample_accountname";

      UpsertRequest request = new()
      {

         Target = new Entity(
                  entityName: tableLogicalName,
                  keyName: keyName,
                  keyValue: "Sample One")
         {
            Attributes =
            {
                  {
                     "sample_description",
                     "A description for the record."
                  }
               }
         }
      };

      var response = (UpsertResponse)service.Execute(request);

      Console.WriteLine($"RecordCreated? {response.RecordCreated}");
      Console.WriteLine($"Record ID: {response.Target.Id}");

      // Retrieve the record alternate key value
      Entity record = service.Retrieve(
         entityName: response.Target.LogicalName,
         id:response.Target.Id,
         columnSet: new Microsoft.Xrm.Sdk.Query.ColumnSet(keyName));

      Console.WriteLine($"Key name: {record[keyName]}");
}

When no record already exists with the key value of Sample One, the first time you use this method the output will look like the following becaues a record is created:

RecordCreated? True
Record ID: 8e7695e0-347c-ee11-8179-000d3a9933c9
Key name: Sample One

Notice that the sample_accountname value "Sample One"> was set even though it is not in the Entity.Attributes collection. You shouldn't include key values in the Attributes collection. They will be included when a record is created.

Run the method again, and the output look like the following becaues the record is Updated:

RecordCreated? False
Record ID: 8e7695e0-347c-ee11-8179-000d3a9933c9
Key name: Sample One

Sample code on GitHub

Insert or update a record using Upsert

Remarks

Usage

Pass an instance of this class to the Execute(OrganizationRequest) method, which returns an instance of the UpsertResponse class.

Privileges and Access Rights

To perform this action, the caller must have privileges on the table for the Entity set to the Target property. Generally, callers must have Read and Write privileges for the table. Learn more about how to verify access in code

Notes for Callers

Learn more about how to use Upsert to Create or Update a record

Constructors

UpsertRequest()

Initializes a new instance of the UpsertRequest class.

Properties

ExtensionData	Gets or sets the structure that contains extra data. Optional. (Inherited from OrganizationRequest)
Item[String]	Gets or sets the indexer for the Parameters collection. (Inherited from OrganizationRequest)
Parameters	Gets or sets the collection of parameters for the request. Required, but is supplied by derived classes. (Inherited from OrganizationRequest)
RequestId	Gets or sets the ID of the request. Optional. (Inherited from OrganizationRequest)
RequestName	Gets or sets the name of the request. Required, but is supplied by derived classes. (Inherited from OrganizationRequest)
Target	Gets or sets the target entity.