Using the 365 entity class in a late bound fashion

In this article I’ll address usage of the entity class. The entity class is critical element when interacting with 365 data via the IOrganizationService, it is especially important when working in a late bound fashion. You will pass entity objects to and from 365 to create, retrieve, and update data.

This article is part of a series

The complete code sample is on GitHub, see Woodsworkblog.ConsoleApp, for this example see the LateBound class.

Late bound and early bound

There are two ways to work when using the IOrganizationService, late bound or early bound. Early bound entails using a tool to generate a set of classes that represent your 365 metadata model. Early bound means you effectively get compile time checking of your code against the metadata of 365. In early bound you don’t normally need to use the entity class. Late bound requires you to manually reference the metadata model in your code, most often as static strings, incorrect values will result in a run time error.

I prefer late bound, I have explained my reasoning in a previous article. Fundamentally I find early bound requires a bit more legwork which outweighs the benefits. That said it’s in no way a bad option and I mention it here so you are aware of the option.

Entity class

The entity class is the base class type for all 365 entities (including the early bound generated ones). You can use it within both the late and early bound models. Typically, a single entity object represents a single record in CRM. You create instances of this class to send into 365 for creates and updates, you will receive instances of it when doing a retrieve.

Entity entity = new Entity();

The key elements of the class are; id, logical name, and attributes.

The id represents the Guid of a record in 365. You can access id from the entity class Id property.

Guid id = entity.Id;
entity.Id = Guid.Parse("00000000-0000-0000-0000-000000000000");

The logical name is the schema name an entity in 365, e.g. contact, account, incident.

String logicalName = entity.LogicalName;
entity.LogicalName = "entity schema name";

You can also set the id and logical name via the entity constructors.

entity = new Entity("entity schema name", Guid.Parse("00000000-0000-0000-0000-000000000000"));

The attributes represent the set of fields for a given record. Each attribute is represented as a key value pair of; attribute schema name, and attribute value, i.e. a dictionary. When you want to set a value you simply provide the attribute schema name and value.

entity.Attributes["attribute schema name"] = "some value";

Entity provides an indexer to the attributes collection so the ‘Attributes’ can be omitted.

entity["attribute schema name"] = "some value";

If you want to retrieve a value from the attributes collection you can extract values by providing the attribute schema name as a key.

object someObjectValue = entity["attribute schema name"];

This has a couple of flaws, 1) if the attributes collection does not contain your key a Generic.KeyNotFoundException will be thrown, 2) your value is returned as an object so an additional cast is required.

To avoid these issues, use the GetAttributeValue function. This will return your value properly typed (or an exception if it cannot be properly cast). If the attributes collection does not contain your key (instead of an exception being thrown), if you are trying to cast to a class null will be returned, or for a struct the default value will be returned.

string someValue = entity.GetAttributeValue<string>("attribute schema name");

You can also access the record id in the attribute collection (as opposed to using the id property). You will need to specify the entity primary key schema name as the attribute name. Typically, this is the entity schema name appended with ‘id’, e.g. for contact use contactid.

Guid contactId = entity.GetAttributeValue<Guid>("contactid");

A complete example using the contact class would look like this:

Entity contact = new Entity("contact", Guid.Parse("00000000-0000-0000-0000-000000000000"));
contact["firstname"] = "James";
contact["lastname"] = "Wood";

string firstname = contact.GetAttributeValue<string>("firstname"); 

Attribute Types

In the attribute examples above we have only looked at the string and Guid type. In reality, you will need to use a few more types to work with all 365 data types.

String

Use this for all types of text fields, e.g. single line and multi-line.

entity["someString"] = "Hello World";
string someString = entity.GetAttributeValue<string>("someString");

Int

Use this for whole number fields.

entity["someInt"] = 12;
int someInt = entity.GetAttributeValue<int>("someInt");

OptionSetValue

This class is provided in the 365 SDK. Use this for option set fields. You need to specify the option set numeric value in the constructor.

entity["someOptionSetValue"] = new OptionSetValue(100000000);
OptionSetValue someOptionSetValue = entity.GetAttributeValue<OptionSetValue>("someOptionSetValue");

DateTime

Use this for all types of date and time values, e.g. user local, date only, time zone independent. The type of date time value is important and results in differing behaviours, check the MSDN for details.

entity["someDateTime"] = DateTime.Now;
DateTime someDateTime = entity.GetAttributeValue<DateTime>("someDateTime");

EntityReference

This class is provided in the 365 SDK. It is used for lookup fields in 365 – e.g. to link records via a 1 to many relationship. The lookup field is shown on the ‘child’. You need to specify the ‘parent’ entity type and record id.

entity["someEntityReference"] = new EntityReference("someEntity", Guid.Parse("00000000-0000-0000-0000-000000000000"));
EntityReference someEntityReference = entity.GetAttributeValue<EntityReference>("someEntityReference");

Bool

Use this for simple two option fields, 0 is false, 1 is true. Note; some two option fields might actually be option sets represented as option set values.

entity["someBool"] = false;
bool someBool = entity.GetAttributeValue<bool>("someBool");

Guid

Pretty much only used record ids, which you can access via the entity id property anyway.

entity["someGuid"] = Guid.Empty;
Guid someGuid = entity.GetAttributeValue<Guid>("someGuid");

Decimal

Use this for decimal numbers.

entity["someDecimal"] = 12m;
decimal someDecimal = entity.GetAttributeValue<decimal>("someDecimal");

Double

Use this for floating point numbers.

entity["someDouble"] = 12d;
double someDouble = entity.GetAttributeValue<double>("someDouble");

Money

This class is provided in the 365 SDK. Use this for currency fields, provide the constructor with a decimal.

entity["someMoney"] = new Money(12m);
Money someMoney = entity.GetAttributeValue<Money>("someMoney");

Original Post https://woodsworkblog.wordpress.com/2017/06/25/using-the-365-entity-class-in-a-late-bound-fashion/