IOrganizationService.Update(Entity) Method

Reference

Definition

Namespace:: Microsoft.Xrm.Sdk

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.

Updates an existing record.

public:
 void Update(Microsoft::Xrm::Sdk::Entity ^ entity);

[System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))]
[System.ServiceModel.OperationContract]
public void Update (Microsoft.Xrm.Sdk.Entity entity);

[<System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))>]
[<System.ServiceModel.OperationContract>]
abstract member Update : Microsoft.Xrm.Sdk.Entity -> unit

Public Sub Update (entity As Entity)

Parameters

entity: Entity

An entity instance that has one or more properties set to be updated in the record.

Attributes: FaultContractAttribute OperationContractAttribute

Examples

For both of these samples to work correctly, you must be connected to the server to instantiate an IOrganizationService interface instance.

The following example shows how to use the Update(Entity) method to update an Account record (early bound).

/// <summary>
/// Demonstrates update of Account record
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void AccountUpdateExample(IOrganizationService service)
{
      Account retrievedAccount = (Account)service.Retrieve(
         entityName: Account.EntityLogicalName,
         id: new Guid("78914942-34cb-ed11-b596-0022481d68cd"),
         columnSet: new ColumnSet("accountid", "name", "numberofemployees"));

      // Create a new instance
      Account updateAccount = new()
      {
         // Set the ID
         Id = retrievedAccount.Id,

         // Only set values that are being changed!

         // Boolean (Two option)
         CreditOnHold = true,
         // DateTime
         LastOnHoldTime = DateTime.Now,
         // Double
         Address1_Latitude = 47.642311,
         Address1_Longitude = -122.136841,
         // Int
         NumberOfEmployees = 400,
         // Money
         Revenue = new Money(new decimal(2000000.00)),
         // Picklist (Option set)
         AccountCategoryCode = account_accountcategorycode.Standard
      };

      // Udate the record
      service.Update(updateAccount);
}

The following example shows how to use the Update(Entity) method to update an account Entity record (late bound).

/// <summary>
/// Demonstrates update of account Entity record
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void EntityUpdateExample(IOrganizationService service)
{
      Entity retrievedAccount = service.Retrieve(
         entityName: "account",
         id: new Guid("78914942-34cb-ed11-b596-0022481d68cd"),
         columnSet: new ColumnSet("accountid", "name", "numberofemployees"));

      // Create a new instance
      Entity updateAccount = new("account")
      {
         // Set the ID
         Id = retrievedAccount.Id,
      };
      // Only set values that are being changed!

      // Boolean (Two option)
      updateAccount["creditonhold"] = true;
      // DateTime
      updateAccount["lastonholdtime"] = DateTime.Now;
      // Double
      updateAccount["address1_latitude"] = 47.642311;
      updateAccount["address1_longitude"] = -122.136841;
      // Int
      updateAccount["numberofemployees"] = 400;
      // Money
      updateAccount["revenue"] = new Money(new decimal(2000000.00));
      // Picklist (Option set)
      updateAccount["accountcategorycode"] = new OptionSetValue(2); //Standard customer

      // Udate the record
      service.Update(updateAccount);
}

You can find more samples on GitHub:

Remarks

Learn how to update table rows using the SDK for .NET.

Privileges and Access Rights

To perform this action, the caller must have Read and Write privileges on the table and the same access rights on the record specified in the entity parameter.

If you update the ownerid column for a user or team owned record, you will need Assign privileges for the table and access rights for the record.

If you update a lookup column for a record to associate records, you will need Append and AppendTo privileges for the related tables and access rights for the records.

Learn more about how to verify access with code.

Notes for Callers

It is important that you only set column values that are changed. Don't retrieve a record with column values, change the values and then use that retrieved Entity instance with the Update(Entity) method.

Setting unchanged column values will cause the retrieved column values to be set as changed which can trigger unwanted additional business logic or cause auditing data to misrepresent actual changes. Instead, you should instantiate a new instance and only set values that have actually changed.

If the entity instance includes data for columns where AttributeMetadata.IsValidForUpdate is false, the values are ignored.

For more information about the exceptions that can be thrown when this method is called, see Handle exceptions in your code.

Supported tables

You can use this method to create any record of a table that supports the Update message. Learn more about Table support for messages and Message support for tables.

Applies to

Share via