Entity class operations using the SDK for .NET
When you work with Microsoft Dataverse data using the SDK for .NET 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.
Entity.LogicalName
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.
Entity.Id
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 logicalname + id. For an account it is accountid and for contact it is contactid.
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.
For example:
//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.
| Type | Description |
|---|---|
| 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 entityimage. A URL to download the image can be retrieved in a companion attribute named entityimage_url. More information: Image attributes |
| 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 EntityName columns, which store a string value representing the logical name of a table. |
Note
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
Entityclass - Use the indexer on the
Attributescollection - Use the
Entitymethods provided
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.
| Method | Description |
|---|---|
| GetAttributeValue<T>(String) | Use this to return a typed attribute value |
| SetAttributeValue(String, Object) | Use this to set a typed attribute value |
For example:
account.SetAttributeValue("name", "Account Name");
var accountName = account.GetAttributeValue<string>("name");
Entity.FormattedValues
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
Note
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
Entity.RelatedEntities
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>();
Note
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.
Next Steps
These topics will explain more about working with Dataverse entities (table rows).
Quick Start: SDK for .NET sample (C#)
Query data
Create table rows
Retrieve a table row
Update and delete a table row
Associate and disassociate table rows
Generate classes for early-bound programming