UpdateRequest Class

Reference

Definition

Namespace:: Microsoft.Xrm.Sdk.Messages

Assembly:: Microsoft.Xrm.Sdk.dll

Package:: Microsoft.PowerPlatform.Dataverse.Client v1.1.32

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Contains the data that is needed to update an existing record.

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

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

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

Public NotInheritable Class UpdateRequest
Inherits OrganizationRequest

Inheritance: Object

OrganizationRequest
UpdateRequest

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. For the complete sample, see the link later in this topic.

The UpdateRequestExample method below demonstrates:

Applying duplicate detection rules in case the change to the record makes it match an existing record.
Optimistic concurrency checks to ensure that the record hasn't been changed since it was retrieved.
Optional parameters to pass values to a plug-in and prevent custom logic from being triggered.

/// <summary>
/// Demonstrates using UpdateRequest with optional parameters
/// and Concurrency behavior
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance</param>
static void UpdateRequestExample(IOrganizationService service)
{
      string accountid = "560bb46c-2d71-ee11-9ae7-000d3a9933c9";
      ColumnSet columns = new(
         "name",
         "creditonhold",
         "lastonholdtime",
         "address1_latitude",
         "address1_longitude",
         "numberofemployees",
         "revenue",
         "accountcategorycode");

   Entity retrievedAccount =  service.Retrieve("account", new Guid(accountid), columns);

      // Instantiate a new Entity instance with the ID that matches the record.
      // Set only the values you are changing.
      // DO NOT use a retrieved record with attribute values set which you are not changing.
      Entity account = new("account", retrievedAccount.Id);
      account["name"] = "Contoso";

      // Set the row version for concurrency behavior
      // Error -2147088253 will occur if this is not set
      account.RowVersion = retrievedAccount.RowVersion;


      //Compose the  request
      UpdateRequest request = new()
      {
         Target = account,
         // The operation will fail if the record is 
         // updated in the period since it was retrieved.
         ConcurrencyBehavior = ConcurrencyBehavior.IfRowVersionMatches
      };

      //Set optional parameters:

      // Expect error if duplicate record found
      request["SuppressDuplicateDetection"] = false;
      // Set a shared variable that a plug-in can access
      request["tag"] = "RecordUpdatedBySampleCode";
      // Bypass plug-in logic if caller has prvBypassCustomPlugins privilege
      request["BypassCustomPluginExecution"] = true;
      // Don't trigger any flows for this operation
      request["SuppressCallbackRegistrationExpanderJob"] = true;

      try
      {
         service.Execute(request);
      }
      catch (FaultException<OrganizationServiceFault> ex)
      {
         switch (ex.Detail.ErrorCode)
         {
            case -2147220685: // Duplicate record error
                  Console.WriteLine(ex.Detail.Message);
                  // A record was not created or updated because a duplicate of the current record already exists.
                  break;
            case -2147088254: // ConcurrencyVersionMismatch  
                  Console.WriteLine(ex.Detail.Message);
                  // The version of the existing record doesn't match the RowVersion property provided.
                  break;
            case -2147088253: // ConcurrencyVersionNotProvided
                  Console.WriteLine(ex.Detail.Message);
                  // The RowVersion property must be provided when the value of ConcurrencyBehavior is IfVersionMatches.
                  break;
            case -2147088243: // OptimisticConcurrencyNotEnabled 
                  Console.WriteLine(ex.Detail.Message);
                  // Optimistic concurrency isn't enabled for entity type account.
                  // The IfVersionMatches value of ConcurrencyBehavior can only be used if optimistic concurrency is enabled.
                  break;
            default:
                  Console.WriteLine(ex.Detail.Message);
                  break;
         }
      }
}

Sample code on GitHub

Use duplicate detection when creating and updating records

Remarks

Usage

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

This message supports one or more optional parameters. For more information, see Use messages (request and response classes) with the Execute method.

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

This message updates a record and its related records in one transaction. For a less complex method that updates a single record, use the Update(Entity) method.

This class enables some operations not possible when using the Update(Entity) method. Some things you can do with this class:

Apply duplicate detection rules. Learn how to detect duplicate data using the SDK for .NET
Apply optimistic concurrency checks by setting the ConcurrencyBehavior property.
Apply optional parameters. Learn how to use optional parameters.

Supported Tables

See Message support for tables for an example query you can use to get the list of tables you can use with the Update message.

Constructors

UpdateRequest()

Initializes a new instance of the UpdateRequest class.

Properties

ConcurrencyBehavior	Specifies the type of optimistic concurrency behavior that should be performed by Dataverse when processing this request.
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 an instance of an entity that is used to update a record. Required.

Applies to

Jaa