Class XrmExtensions

Extensions methods relating to Xrm SDK.

Inheritance

System.Object

XrmExtensions

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Hsl.Xrm.Sdk

Assembly: Hsl.Xrm.Sdk.Core.dll

Syntax

public static class XrmExtensions

Methods

AttributeValueEquals(Object, Object, Boolean)

Declaration

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

Parameters

Type	Name	Description
System.Object	valueA
System.Object	valueB
System.Boolean	normalizeValues

Returns

Type	Description
System.Boolean

ContainsNonNullValue(Entity, String)

Whether the given attribute has a non-null value.

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target
System.String	attribute

Returns

Type	Description
System.Boolean

Copy(Entity)

Generates a deep copy of the target entity.

Declaration

public static Entity Copy(this Entity target)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target

Returns

Type	Description
Microsoft.Xrm.Sdk.Entity

CopyAndUpdateFrom(Entity, Entity)

Create a 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)

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	baseEntity	The entity image that is copied. Values from mergedEntity are merged into the copy.
Microsoft.Xrm.Sdk.Entity	mergedEntity	The entity image whose attributes are merged down onto the copy of baseEntity.

Returns

Type	Description
Microsoft.Xrm.Sdk.Entity

CopyAttribute(Entity, String)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target
System.String	attribute

Returns

Type	Description
System.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.

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target
System.String	attribute

Returns

Type	Description
System.String

GetFieldValue(Entity, String)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target
System.String	attribute

Returns

Type	Description
System.Object

GetFieldValue<T>(Entity, String)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target	The entity to get the value from
System.String	attribute	The field to get the value for

Returns

Type	Description
T

Type Parameters

Name	Description
T	The type to return.

GetFieldValue<T>(Entity, String, T)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target	The entity to get the value from
System.String	attribute	The field to get the value for
T	defaultValue	The default value to use if the entity doesn't contain the given attribute or it is null.

Returns

Type	Description
T

Type Parameters

Name	Description
T	The type to return.

GetFieldValueAsString(Entity, String, Boolean)

Returns a string version of the field.

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target	The target entity.
System.String	attribute	The attribute to get the value for.
System.Boolean	useDisplayedValue	If false, the non-localized value will be returned. If true, a value for displaying to the user will be returned.

Returns

Type	Description
System.String

GetItem<T>(ParameterCollection, String, T)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.ParameterCollection	pc	The ParameterCollection from which the item will be retrieved.
System.String	key	The key to the item in the ParameterCollection.
T	defaultValue	The default value to be returned if the item cannot be cast, is null, or cannot be found.

Returns

Type	Description
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

Name	Description
T	The type as which the item will be returned.

IsAttributeEqual(Entity, Entity, String, Boolean)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	target	Target entity for checking
Microsoft.Xrm.Sdk.Entity	other	Entity to compare to
System.String	attribute	The attribute to compare
System.Boolean	normalizeValues	Whether to normalize string and DateTime values.

Returns

Type	Description
System.Boolean

ToEntitiesList<T>(EntityCollection)

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

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.EntityCollection	collection

Returns

Type	Description
System.Collections.Generic.List<T>

Type Parameters

Name	Description
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.

Declaration

public static Entity ToEntity(this EntityReference target)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.EntityReference	target

Returns

Type	Description
Microsoft.Xrm.Sdk.Entity

ToEntityReference(Guid, String)

Transforms a Guid into an EntityReference.

Declaration

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

Parameters

Type	Name	Description
System.Guid	target	The target Guid to transform into an EntityReference.
System.String	logicalName	The logical name of the entity for which the Guid is a reference.

Returns

Type	Description
Microsoft.Xrm.Sdk.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(Nullable<Guid>, String)

Transforms a Guid into an EntityReference.

Declaration

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

Parameters

Type	Name	Description
System.Nullable<System.Guid>	target	The target Guid to transform into an EntityReference.
System.String	logicalName	The logical name of the entity for which the Guid is a reference.

Returns

Type	Description
Microsoft.Xrm.Sdk.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.

Declaration

public static Money ToMoney(this decimal target)

Parameters

Type	Name	Description
System.Decimal	target	The target decimal value to be transformed into a Money object.

Returns

Type	Description
Microsoft.Xrm.Sdk.Money	A Money object whose value will be set to the value of the target decimal.

ToMoney(Nullable<Decimal>)

Transforms the decimal value into a Money object.

Declaration

public static Money ToMoney(this decimal? target)

Parameters

Type	Name	Description
System.Nullable<System.Decimal>	target	The target decimal value to be transformed into a Money object.

Returns

Type	Description
Microsoft.Xrm.Sdk.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(Int32)

Transforms the int value into a OptionSetValue object.

Declaration

public static OptionSetValue ToOptionSetValue(this int target)

Parameters

Type	Name	Description
System.Int32	target	The target int value to be transformed into an OptionSetValue object.

Returns

Type	Description
Microsoft.Xrm.Sdk.OptionSetValue	An OptionSetValue object whose value will be set to the value of the target int.

ToOptionSetValue(Nullable<Int32>)

Transforms the int value into an OptionSetValue object.

Declaration

public static OptionSetValue ToOptionSetValue(this int? target)

Parameters

Type	Name	Description
System.Nullable<System.Int32>	target	The target int value to be transformed into an OptionSetValue object.

Returns

Type	Description
Microsoft.Xrm.Sdk.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.

Declaration

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

Parameters

Type	Name	Description
T	enumValue

Returns

Type	Description
Microsoft.Xrm.Sdk.OptionSetValue

Type Parameters

Name	Description
T

ToOptionSetValue<T>(Nullable<T>)

Creates an option set value for the given enum value.

Declaration

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

Parameters

Type	Name	Description
System.Nullable<T>	enumValue

Returns

Type	Description
Microsoft.Xrm.Sdk.OptionSetValue

Type Parameters

Name	Description
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.

Declaration

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

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.Entity	updateEntity	The entity to remove unchanged fields from.
Microsoft.Xrm.Sdk.Entity	currentEntity	The entity to use as a baseline.