IOrganizationService.Create(Entity) Method

  • Reference

Definition

Namespace:
Microsoft.Xrm.Sdk
Assembly:
Microsoft.Xrm.Sdk.dll
Package:
Microsoft.PowerPlatform.Dataverse.Client v1.1.17

Creates a record. 

public:
 Guid Create(Microsoft::Xrm::Sdk::Entity ^ entity);
[System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))]
[System.ServiceModel.OperationContract]
public Guid Create (Microsoft.Xrm.Sdk.Entity entity);
[<System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))>]
[<System.ServiceModel.OperationContract>]
abstract member Create : Microsoft.Xrm.Sdk.Entity -> Guid
Public Function Create (entity As Entity) As Guid

Parameters

entity
Entity

An entity instance that contains the properties to set in the newly created record.

Returns

Guid

The ID of the newly created record.

Attributes
FaultContractAttribute OperationContractAttribute

Examples

The following example shows how to use the Create(Entity) method to create two account records using two different ways to instantiate the Entity. Learn more about generating early-bound classes for the SDK for .NET

For this sample to work correctly, you must be connected to the server to instantiate an IOrganizationService instance. 

/// <summary>
/// Creates two account records using different styles
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
/// <returns>The ID of the record created</returns>
static void CreateAccountsExample(IOrganizationService service)
{
// Early bound example
     Account earlyBoundAccount = new()
      {
         // string primary name
         Name = "Contoso (Early Bound)",
         // Boolean (Two option)
         CreditOnHold = false,
         // DateTime
         LastOnHoldTime = new DateTime(2023, 1, 1),
         // Double
         Address1_Latitude = 47.642311,
         Address1_Longitude = -122.136841,
         // Int
         NumberOfEmployees = 500,
         // Money
         Revenue = new Money(new decimal(5000000.00)),
         // Choice (Option set)
         AccountCategoryCode = account_accountcategorycode.PreferredCustomer
      };

      //Create the account
      Guid earlyBoundAccountId = service.Create(earlyBoundAccount);


//  Late bound example
      Entity lateBoundAccount = new("account");
      // string primary name
      lateBoundAccount["name"] = "Contoso (Late Bound)";
      // Boolean (Two option)
      lateBoundAccount["creditonhold"] = false;
      // DateTime
      lateBoundAccount["lastonholdtime"] = new DateTime(2023, 1, 1);
      // Double
      lateBoundAccount["address1_latitude"] = 47.642311;
      lateBoundAccount["address1_longitude"] = -122.136841;
      // Int
      lateBoundAccount["numberofemployees"] = 500;
      // Money
      lateBoundAccount["revenue"] = new Money(new decimal(5000000.00));
      // Choice (Option set)
      lateBoundAccount["accountcategorycode"] = new OptionSetValue(1);

      //Create the account
      Guid lateBoundAccountId = service.Create(lateBoundAccount);

      //Delete the accounts
      service.Delete(Account.EntityLogicalName, earlyBoundAccountId);
      service.Delete("account", lateBoundAccountId);
}

You can find more samples on GitHub:

Remarks

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

Privileges and Access Rights

To perform this action, the caller must have Read and Create privileges on the table that is specified in the entity parameter. Learn more about how to verify access with code

Notes for Callers

This method creates one record in a transaction. To create a record that has related records in a transaction, use CreateRequest. Learn more about creating related entities in one operation.

By default the caller becomes the owner for the new record. For the caller to own the new record, they must have both Create and Read privileges for the entity. Alternatively, you can set the ownerid property to the ID of another user.

The entity instance that is specified as a parameter must contain values for all the columns where the AttributeMetadata.RequiredLevel property is set to SystemRequired and the column is AttributeMetadata.IsValidForCreate" property is true. A column set to SystemRequired is not typical for tables containing business data, but can be found for tables used to define solution components, such as CustomAPI .

For common Dataverse tables you can find RequiredLevel and IsValidForCreate values in the Dataverse table/entity reference. For custom tables or tables added by other solutions, you can use a table definition browser like the one described in Browse table definitions in your environment.

If the entity instance includes data for columns where AttributeMetadata.IsValidForCreate 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 Create message. Learn more about Table support for messages and Message support for tables.

Applies to

See also