Class XrmExtensions

Namespace

Hsl.Xrm.Sdk

Assembly

Hsl.Xrm.Sdk.Core.dll

Extensions methods relating to Xrm SDK.

public static class XrmExtensions

Inheritance

object

XrmExtensions

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Methods

AttributeValueEquals(object?, object?, bool)

Compares to attribute values for equality.

public static bool AttributeValueEquals(object? valueA, object? valueB, bool normalizeValues)

Parameters

valueA object

The first value

valueB object

The second value

normalizeValues bool

Whether to normalize string and DateTime values.

Returns

bool

ContainsNonNullValue(Entity, string)

Whether the given attribute has a non-null value.

public static bool ContainsNonNullValue(this Entity target, string attribute)

Parameters

target Entity

attribute string

Returns

bool

Copy(Entity)

Generates a deep copy of the target entity.

public static Entity Copy(this Entity target)

Parameters

target Entity

Returns

Entity

CopyAndUpdateFrom(Entity, Entity)

Create a copy of baseEntity and merges into the copy the attributes from mergedEntity, excluding attributes of type AliasedValue.

This is intended to be used to merge a newer version of an entity on top of an older one:

• preImage.CopyAndUpdateFrom(target)

These usages would likely produce undesired results:

• preImage.CopyAndUpdateFrom(postImage)
• target.CopyAndUpdateFrom(postImage)
• target.CopyAndUpdateFrom(preImage)
• postImage.CopyAndUpdateFrom(target)
• postImage.CopyAndUpdateFrom(preImage)

public static Entity CopyAndUpdateFrom(this Entity baseEntity, Entity mergedEntity)

Parameters

baseEntity Entity

The entity image that is copied. Values from mergedEntity are merged into the copy.

mergedEntity Entity

The entity image whose attributes are merged down onto the copy of baseEntity.

Returns

Entity

CopyAttribute(Entity, string)

Creates a deep copy of the specified attributes on the target entity. Does not support copying AliasedValue attributes.

public static object? CopyAttribute(this Entity target, string attribute)

Parameters

target Entity

attribute string

Returns

object

GetFieldDisplayText(Entity, string)

Returns the formatted value, if present; otherwise, the actual value. Note that this typically only works for records retrieved from retrieve requests.

public static string GetFieldDisplayText(this Entity target, string attribute)

Parameters

target Entity

attribute string

Returns

string

GetFieldValue(Entity, string)

Returns the value of the specified field unwrapping any alias values.

public static object? GetFieldValue(this Entity target, string attribute)

Parameters

target Entity

attribute string

Returns

object

GetFieldValueAsString(Entity, string, bool)

Returns a string version of the field.

public static string GetFieldValueAsString(this Entity target, string attribute, bool useDisplayedValue = false)

Parameters

target Entity

The target entity.

attribute string

The attribute to get the value for.

useDisplayedValue bool

If false, the non-localized value will be returned. If true, a value for displaying to the user will be returned.

Returns

string

GetFieldValue<T>(Entity, string)

Returns the value of the field unwrapping AliasedValue/EntityReference/Money/OptionSetValue/OptionSetValueCollection if necessary.

public static T? GetFieldValue<T>(this Entity target, string attribute)

Parameters

target Entity

The entity to get the value from

attribute string

The field to get the value for

Returns

T

Type Parameters

T

The type to return.

GetFieldValue<T>(Entity, string, T?)

Returns the value of the field unwrapping AliasedValue/EntityReference/Money/OptionSetValue/OptionSetValueCollection if necessary.

public static T? GetFieldValue<T>(this Entity target, string attribute, T? defaultValue)

Parameters

target Entity

The entity to get the value from

attribute string

The field to get the value for

defaultValue T

The default value to use if the entity doesn't contain the given attribute or it is null.

Returns

T

Type Parameters

T

The type to return.

GetItem<T>(ParameterCollection, string, T?)

Gets an item cast to the specified type from the ParameterCollection.

public static T? GetItem<T>(this ParameterCollection pc, string key, T? defaultValue = default)

Parameters

pc ParameterCollection

The ParameterCollection from which the item will be retrieved.

key string

The key to the item in the ParameterCollection.

defaultValue T

The default value to be returned if the item cannot be cast, is null, or cannot be found.

Returns

T

The value retrieved from the ParameterCollection cast as the specified type or the defaultValue if the item cannot be found or is null.

Type Parameters

T

The type as which the item will be returned.

IsAttributeEqual(Entity, Entity, string, bool)

Checks whether the specified attribute is the same in both entities. NOTE: only normalization possible without metadata is done.

public static bool IsAttributeEqual(this Entity target, Entity other, string attribute, bool normalizeValues = true)

Parameters

target Entity

Target entity for checking

other Entity

Entity to compare to

attribute string

The attribute to compare

normalizeValues bool

Whether to normalize string and DateTime values.

Returns

bool

ToEntitiesList<T>(EntityCollection)

Converts the EntityCollection to a list of entities with the given early bound type.

public static List<T> ToEntitiesList<T>(this EntityCollection collection) where T : Entity

Parameters

collection EntityCollection

Returns

List<T>

Type Parameters

T

The early bound entity type to use.

ToEntity(EntityReference)

Creates an entity referring to the given target intended to be passed to a Update or Upsert request.

public static Entity? ToEntity(this EntityReference target)

Parameters

target EntityReference

Returns

Entity

ToEntityReference(Guid, string)

Transforms a Guid into an EntityReference.

public static EntityReference? ToEntityReference(this Guid target, string logicalName)

Parameters

target Guid

The target Guid to transform into an EntityReference.

logicalName string

The logical name of the entity for which the Guid is a reference.

Returns

EntityReference

An EntityReference with the specified Guid as the Id and logical entity name as the referenced entity, or a null value if the Guid is an empty Guid.

ToEntityReference(Guid?, string)

Transforms a Guid into an EntityReference.

public static EntityReference? ToEntityReference(this Guid? target, string logicalName)

Parameters

target Guid?

The target Guid to transform into an EntityReference.

logicalName string

The logical name of the entity for which the Guid is a reference.

Returns

EntityReference

An EntityReference with the specified Guid as the Id and logical entity name as the referenced entity, or a null value if the Guid is null.

ToMoney(decimal)

Transforms the decimal value into a Money object.

public static Money ToMoney(this decimal target)

Parameters

target decimal

The target decimal value to be transformed into a Money object.

Returns

Money

A Money object whose value will be set to the value of the target decimal.

ToMoney(decimal?)

Transforms the decimal value into a Money object.

public static Money? ToMoney(this decimal? target)

Parameters

target decimal?

The target decimal value to be transformed into a Money object.

Returns

Money

A Money object whose value will be set to the value of the target decimal, or null if the decimal value is null.

ToOptionSetValue(int)

Transforms the int value into a OptionSetValue object.

public static OptionSetValue ToOptionSetValue(this int target)

Parameters

target int

The target int value to be transformed into an OptionSetValue object.

Returns

OptionSetValue

An OptionSetValue object whose value will be set to the value of the target int.

ToOptionSetValue(int?)

Transforms the int value into an OptionSetValue object.

public static OptionSetValue? ToOptionSetValue(this int? target)

Parameters

target int?

The target int value to be transformed into an OptionSetValue object.

Returns

OptionSetValue

A OptionSetValue object whose value will be set to the value of the target int, or null if the int value is null.

ToOptionSetValue<T>(T?)

Creates an option set value for the given enum value.

public static OptionSetValue? ToOptionSetValue<T>(this T? enumValue) where T : struct, Enum

Parameters

enumValue T?

Returns

OptionSetValue

Type Parameters

T

ToOptionSetValue<T>(T)

Creates an option set value for the given enum value.

public static OptionSetValue ToOptionSetValue<T>(this T enumValue) where T : struct, Enum

Parameters

enumValue T

Returns

OptionSetValue

Type Parameters

T

TryRemoveUnchangedFields(Entity, Entity)

Removes unchanged fields where it is possible to identify the values are the same without querying metadata. Doesn't deal with the items below (because it would require metadata or an additional query to CDS):

• In order to be eligible to be removed, DateTime.Kind in updateEntity should match what CRM returns from retrieves (Unspecified for Time Zone Independent and Date Only and Utc for user local)
• Zeroing hours/minutes/seconds for a date only field. Does handle zeroing milliseconds and below since CDS only handles second-level resolution.
• Number/Money precision
• Alt Key References vs regular EntityReference on currentEntity

Despite not handling the above, this does remove a decent chunk of fields in many cases which should improve performance.

public static void TryRemoveUnchangedFields(this Entity updateEntity, Entity currentEntity)

Parameters

updateEntity Entity

The entity to remove unchanged fields from.

currentEntity Entity

The entity to use as a baseline.