Entity class operations using the Organization service
Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.
When you work with Microsoft Dataverse data using the organization service you will use the Entity class with the late-bound style or with generated entity classes using the early-bound style. The generated entity classes inherit from the Entity class, so understanding the Entity class is important for either style.
This topic will describe some of the most frequently used properties and methods of the Entity class.
When you instantiate a new Entity class instance using the late-bound style you must provide a valid string value to specify what entity type it is. The
LogicalName is defined in the entity metadata (table definition).
When using the early-bound style, this value is set by the constructor of the generated class. For example:
var account = new Entity("account");
In your code, if you later want to retrieve the string value that describes the entity type, you can use the LogicalName property. This is useful for the many APIs that require an entity logical name as a parameter.
When you instantiate the
Entity class, whether using the late-bound or early-bound style, it doesn't have a unique id set. If you are creating an entity, you shouldn't set it, but allow it to be set by the system when you create (save) it.
If you are retrieving an entity, it will include the primary key attribute value whether you request it or not. The primary key attribute name is different for each type of entity. Generally, the name of the primary key attribute is the entity
id. For an account it is
accountid and for contact it is
While you can get or set the primary key value using the primary key attribute, you can also use the Id property to access the value without having to remember the name of the primary key attribute.
Early bound access to table columns
If you are using the early-bound style with generated classes, you will find typed properties for each attribute in the class. The properties for the attributes use the AttributeMetadata.SchemaName and they can be accessed directly on the
Entity class instance.
//Using the early-bound Account entity class var account = new Account(); // set attribute values // string primary name account.Name = "Contoso"; // Boolean (Two option) account.CreditOnHold = false; // DateTime account.LastOnHoldTime = new DateTime(2017, 1, 1); // Double account.Address1_Latitude = 47.642311; account.Address1_Longitude = -122.136841; // Int account.NumberOfEmployees = 500; // Money account.Revenue = new Money(new decimal(5000000.00)); // Picklist (Option set) account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer
Late bound access to table columns
The data contained within an entity is in the Entity.Attributes property. This property is an AttributeCollection that provides a whole set of methods to add new attributes, check whether an attribute exists, or remove attributes.
Discover column names and data types
In the late-bound style, you need to know the AttributeMetadata.LogicalName for the attribute and the data type. The
LogicalName is the lowercase version of the
SchemaName. You can discover the
LogicalName and type for attributes in several ways:
- View the definition of the column (attribute) in the web application customization tools
- For system tables, you can review the Table/entity Reference
- Use a tool to browse the table definitions, such as the Metadata Browser described in Browse the metadata for your environment
- View the list of derived classes on the AttributeMetadata reference page
Attribute types can be any of the following. This is a partial list.
|EntityReference||A Lookup attribute. A link to another entity record.|
|BooleanManagedProperty||Used only for entities that can be solution components, such as WebResource. More information: Use managed properties|
|Money||A Currency attribute.|
|OptionSetValue||An Option Set attribute. State and Status attributes also use this type.|
|Boolean||A Two Option attribute.|
|Byte||An Image attribute. Each entity can have one image and the attribute is named
|DateTime||A Date and Time attribute usually uses a UTC value. More information: Behavior and format of the date and time attribute|
|Decimal||A Decimal Number attribute.|
|Double||A Floating Point Number attribute.|
|Guid||Usually used as the unique identifier for the entity.|
|Int32||A Whole Number attribute.|
|String||Multiple Lines of Text and Single Line of Text attributes use this type. Another less common type that uses string are
File columns are not available directly from the entity. You need to use a series of requests to upload or download data from file columns. More information: Use file column data.
There are three different ways to interact with entity attributes using the late-bound style:
- Use the indexer on the
- Use the indexer on the
- Use the
Use the indexer on Entity class
In most cases using the late-bound style, you can interact with collection by using the indexer to get or set the value of an attribute using the
LogicalName for the attribute. For example, to set the name attribute of an account:
//Use Entity class with entity logical name var account = new Entity("account"); // set attribute values // string primary name account["name"] = "Contoso"; // Boolean (Two option) account["creditonhold"] = false; // DateTime account["lastonholdtime"] = new DateTime(2017, 1, 1); // Double account["address1_latitude"] = 47.642311; account["address1_longitude"] = -122.136841; // Int account["numberofemployees"] = 500; // Money account["revenue"] = new Money(new decimal(5000000.00)); // Picklist (Option set) account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer
Use the indexer on the Attributes collection
Just like you would on the entity, you can also access a value using the indexer on the Attributes collection.
string accountName = account.Attributes["name"];
Use the Entity methods
You can also use Entity methods to get or set attribute values.
|GetAttributeValue<T>(String)||Use this to return a typed attribute value|
|SetAttributeValue(String, Object)||Use this to set a typed attribute value|
account.SetAttributeValue("name", "Account Name"); var accountName = account.GetAttributeValue<string>("name");
Any entity attribute value that can be displayed in the UI and is not a string will have a string formatted value that can be used to display the value in the UI. For example:
- Money values will have a string value with the appropriate currency and precision formatting.
- Date values will have the formatting set depending on how the system is configured
- OptionSet (choices) values will display the localized label that represents the integer value
Formatted values only apply to entities that have been retrieved. Once you set the value, a new formatted value is not calculated until you save the entity and retrieve the entity again. The formatted value is generated on the server.
You can access the formatted values using the FormattedValues collection using an indexer or with the entity GetFormattedAttributeValue(String) method.
For example, both of these retrieve the same formatted value:
var formattedRevenueString1 = account.FormattedValues["revenue"]; var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");
More information: Access formatted values
When you create an entity record (table row) you can also define a set of related entity records to create in the same operation. More information: Create related table rows in one operation
When you retrieve an entity record using RetrieveRequest you can set RelatedEntitiesQuery with a query to include related entity records in the results. More information: Retrieve with related rows
If you include related entity records in the results, you can also update values on those related records and include them when you update the entity record. More information: Update related table rows in one operation
Convert to an EntityReference
Many message properties require only an EntityReference. Use the Entity.ToEntityReference() method to convert an entity record to an entity reference.
Convert to an Entity class
If you are using the early-bound style, you will need to convert the Entity instance to the type of generated entity class you are using. This can usually be done with a cast, but you can also use the Entity.ToEntity<T>() method.
Account account1 = (Account)retrievedEntity; Account account2 = retrievedEntity.ToEntity<Account>();
This method cannot be used to convert a generated
Entity class instance to another generated class or to Entity . It can only be used to convert an Entity instance to one of the generated classes that inherit from it. If the Entity instance isn't actually an instance of the generated class this message will throw an error.
These topics will explain more about working with Dataverse entities (table rows).
Quick Start: Organization service sample (C#)
Create table rows
Retrieve a table row
Update and delete a table row
Associate and disassociate table rows
Generate classes for early-bound programming
Submit and view feedback for