Class OrganizationServiceExtensions

Extension methods for IOrganizationService

Inheritance

System.Object

OrganizationServiceExtensions

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 OrganizationServiceExtensions

Methods

AssociateManySafe(IOrganizationService, String, EntityReference, String, IEnumerable<Guid>, Boolean)

Associates the given records unless they're already associated.

Declaration

[Obsolete("Use native Associate method for a one-to-many relationship, or AssociateManyToManySafe for a many-to-many relationship")]
public static void AssociateManySafe(this IOrganizationService service, string relationshipName, EntityReference record1Ref, string associateEntityName, IEnumerable<Guid> idsToAssociate, bool skipExistingCheck)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	relationshipName
Microsoft.Xrm.Sdk.EntityReference	record1Ref
System.String	associateEntityName
System.Collections.Generic.IEnumerable<System.Guid>	idsToAssociate
System.Boolean	skipExistingCheck

AssociateManyToManySafe(IOrganizationService, EntityReference, Relationship, EntityReferenceCollection, String, String, String)

Associates the records via the specified many-to-many relationship. The native Associate method will throw an exception if the provided records are already associated. This method avoids that by querying to determine which records are already associated, if any, and skips those.

If you know that the records are already not associated, it would be preferable to use the native Associate method which would avoid the unnecessary query.

Declaration

public static void AssociateManyToManySafe(this IOrganizationService service, EntityReference record, Relationship relationship, EntityReferenceCollection relatedRecords, string intersectEntityName = null, string intersectEntityAttributeToRecord = null, string intersectEntityAttributeToRelated = null)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The org service.
Microsoft.Xrm.Sdk.EntityReference	record	The record to which relatedRecords will be associated.
Microsoft.Xrm.Sdk.Relationship	relationship	The many-to-many relationship. If the relationship is reflexive (same entity on both sides), then the PrimaryEntityRole property must be specified.
Microsoft.Xrm.Sdk.EntityReferenceCollection	relatedRecords	The records to associate.
System.String	intersectEntityName	Optional, defaults to the logical name of the relationship. If the name of the intersect entity for the many-to-many relationship differs from the relationship's logical name, specify it with this parameter.
System.String	intersectEntityAttributeToRecord	Optional, defaults to record's logical name + "id" (or + "idone" or + "idtwo" if the relationship is relfexive). If the intersect entity's attribute to record differs from this pattern, specify it with this parameter.
System.String	intersectEntityAttributeToRelated	Optional, defaults to relatedRecords's logical name + "id" (or + "idone" or + "idtwo" if the relationship is relfexive). If the intersect entity's attribute to relatedRecords differs from this pattern, specify it with this parameter.

Exceptions

Type	Condition
System.ArgumentException	This exception is thrown if the relationship is reflexive (same entity on both sides) and relationship does not specify PrimaryEntityRole.

AssociateManyToManySafe(IOrganizationService, EntityReference, String, EntityReference, String, String, String)

Associates the records via the specified many-to-many relationship. The native Associate method will throw an exception if the provided records are already associated. This method avoids that by querying to determine if the records are already associated.

If you know that the records are already not associated, it would be preferable to use the native Associate method which would avoid the unnecessary query.

Declaration

public static void AssociateManyToManySafe(this IOrganizationService service, EntityReference record, string relationship, EntityReference relatedRecord, string intersectEntityName = null, string intersectEntityAttributeToRecord = null, string intersectEntityAttributeToRelated = null)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The org service.
Microsoft.Xrm.Sdk.EntityReference	record	The record to which relatedRecord will be associated.
System.String	relationship	The name of the many-to-many relationship. If the relationship is reflexive (same entity on both sides), then you must specify the PrimaryEntityRole property which means that you must use the overload of this method.
Microsoft.Xrm.Sdk.EntityReference	relatedRecord	The record to associate.
System.String	intersectEntityName	Optional, defaults to the logical name of the relationship. If the name of the intersect entity for the many-to-many relationship differs from the relationship's logical name, specify it with this parameter.
System.String	intersectEntityAttributeToRecord	Optional, defaults to record's logical name + "id" (or + "idone" or + "idtwo" if the relationship is relfexive). If the intersect entity's attribute to record differs from this pattern, specify it with this parameter.
System.String	intersectEntityAttributeToRelated	Optional, defaults to relatedRecord's logical name + "id" (or + "idone" or + "idtwo" if the relationship is relfexive). If the intersect entity's attribute to relatedRecord differs from this pattern, specify it with this parameter.

Exceptions

Type	Condition
System.ArgumentException	This exception is thrown if the relationship is reflexive (same entity on both sides) and relationship does not specify PrimaryEntityRole.

AssociateSafe(IOrganizationService, String, EntityReference, EntityReference, Boolean)

Associates the given records unless they're already associated.

Declaration

[Obsolete("Use native Associate method for a one-to-many relationship, or AssociateManyToManySafe for a many-to-many relationship")]
public static void AssociateSafe(this IOrganizationService service, string relationshipName, EntityReference record1Ref, EntityReference record2Ref, bool skipExistingCheck)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	relationshipName
Microsoft.Xrm.Sdk.EntityReference	record1Ref
Microsoft.Xrm.Sdk.EntityReference	record2Ref
System.Boolean	skipExistingCheck

BulkRetrieveByIds(IOrganizationService, String, IEnumerable<Guid>, ColumnSet, BulkRetrieveByIdsOptions)

Retrieves a set of records by primary id. This batches the ids into several requests if needed.

Declaration

public static IEnumerable<Entity> BulkRetrieveByIds(this IOrganizationService svc, string entityName, IEnumerable<Guid> ids, ColumnSet columns, BulkRetrieveByIdsOptions options = null)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc
System.String	entityName
System.Collections.Generic.IEnumerable<System.Guid>	ids
Microsoft.Xrm.Sdk.Query.ColumnSet	columns
BulkRetrieveByIdsOptions	options

Returns

Type	Description
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>

CreateMultiple(IOrganizationService, IEnumerable<Entity>)

Creates multiple records for a single dataverse table.

Declaration

public static Guid[] CreateMultiple(this IOrganizationService svc, IEnumerable<Entity> entities)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc	Dataverse client
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>	entities	List of records to create

Returns

Type	Description
System.Guid[]	Ids of the created records

DeleteFile(IOrganizationService, EntityReference, String)

Deletes the file from the given record / column

Declaration

public static void DeleteFile(this IOrganizationService service, EntityReference targetEntityReference, string targetColumnName)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The instance of the organization service
Microsoft.Xrm.Sdk.EntityReference	targetEntityReference	An Entity Reference to the desired record
System.String	targetColumnName	The column name from which the file should be downloaded

DeleteFile(IOrganizationService, Guid)

Deletes the file identified via the GUID

Declaration

public static void DeleteFile(this IOrganizationService service, Guid fileId)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The instance of the organization service
System.Guid	fileId	The GUID of the file to be deleted

DisassociateSafe(IOrganizationService, String, EntityReference, EntityReference, Boolean)

Disassociates the given records unless they're already not associated.

Declaration

[Obsolete("Use standard Disassociate method")]
public static void DisassociateSafe(this IOrganizationService service, string relationshipName, EntityReference record1Ref, EntityReference record2Ref, bool skipExistingCheck)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	relationshipName
Microsoft.Xrm.Sdk.EntityReference	record1Ref
Microsoft.Xrm.Sdk.EntityReference	record2Ref
System.Boolean	skipExistingCheck

DownloadFile(IOrganizationService, EntityReference, String, Int32)

Downloads a file from the given record / column

Declaration

public static byte[] DownloadFile(this IOrganizationService service, EntityReference targetEntityReference, string targetColumnName, int maxDownloadBlockSizeInBytes = 4194304)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The instance of the organization service
Microsoft.Xrm.Sdk.EntityReference	targetEntityReference	An Entity Reference to the desired record
System.String	targetColumnName	The column name from which the file should be downloaded
System.Int32	maxDownloadBlockSizeInBytes	An optional parameter that can be used to control how large the individual blocks of data are when downloading large files. At the time of writing, this value cannot be larger than 4 MB (i.e. 4,194,304 Bytes)

Returns

Type	Description
System.Byte[]	A byte[] representation of the file

ExecuteMultiple(IOrganizationService, Boolean, Boolean, OrganizationRequest[])

Executes the specified set of requests.

Declaration

public static ExecuteMultipleResponse ExecuteMultiple(this IOrganizationService service, bool continueOnError, bool returnResponses, params OrganizationRequest[] requests)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.Boolean	continueOnError
System.Boolean	returnResponses
Microsoft.Xrm.Sdk.OrganizationRequest[]	requests

Returns

Type	Description
Microsoft.Xrm.Sdk.Messages.ExecuteMultipleResponse

Fetch(IOrganizationService, String)

Fetches records based on the given fetchxml.

Declaration

public static EntityCollection Fetch(this IOrganizationService service, string fetchXml)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	fetchXml

Returns

Type	Description
Microsoft.Xrm.Sdk.EntityCollection

Fetch<T>(IOrganizationService, String)

Fetches records based on the given fetchxml.

Declaration

public static List<T> Fetch<T>(this IOrganizationService service, string fetchXml)
    where T : Entity

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	fetchXml

Returns

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

Type Parameters

Name	Description
T

Retrieve(IOrganizationService, EntityReference, String[])

Retrieves the given record by alternate key or primary id.

Declaration

public static Entity Retrieve(this IOrganizationService service, EntityReference entity, params string[] columns)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
Microsoft.Xrm.Sdk.EntityReference	entity	Either a primary id or alternate key reference to the record to retrieve
System.String[]	columns

Returns

Type	Description
Microsoft.Xrm.Sdk.Entity

Retrieve<T>(IOrganizationService, Guid, String[])

Retrieves the record with the given id.

Declaration

public static T Retrieve<T>(this IOrganizationService service, Guid id, params string[] columns)
    where T : Entity

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The instance of the organization service
System.Guid	id	Primary id of the record to retrieve
System.String[]	columns	The set of attributes to retrieve

Returns

Type	Description
T	Retrieved record

Type Parameters

Name	Description
T	Early bound type to use.

RetrieveAllLazy(IOrganizationService, QueryExpression, RetrieveAllOptions)

Pages through records until options.MaxResults is reached.

Declaration

public static IEnumerable<Entity> RetrieveAllLazy(this IOrganizationService svc, QueryExpression query, RetrieveAllOptions options = null)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc
Microsoft.Xrm.Sdk.Query.QueryExpression	query
RetrieveAllOptions	options

Returns

Type	Description
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>

RetrieveAllLazy(IOrganizationService, String, RetrieveAllOptions)

Retrieves all records for the given query instead of just the first 5000. NOTE: This method is lazy. Call ToList to iterate through the results if needed.

Declaration

public static IEnumerable<Entity> RetrieveAllLazy(this IOrganizationService svc, string fetchXml, RetrieveAllOptions options = null)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc
System.String	fetchXml
RetrieveAllOptions	options

Returns

Type	Description
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>

RetrieveAllLazy<T>(IOrganizationService, QueryExpression, RetrieveAllOptions)

Retrieves all records for the given query instead of just the first 5000. NOTE: This method is lazy. Call ToList to iterate through the results if needed.

Declaration

public static IEnumerable<T> RetrieveAllLazy<T>(this IOrganizationService svc, QueryExpression query, RetrieveAllOptions options = null)
    where T : Entity

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc
Microsoft.Xrm.Sdk.Query.QueryExpression	query
RetrieveAllOptions	options

Returns

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

Type Parameters

Name	Description
T

RetrieveMultiple(IOrganizationService, String, ColumnSet, ConditionExpression[])

Retrieves a list of multiple DynamicEntities using the specified query from the ICrmService.

Declaration

public static EntityCollection RetrieveMultiple(this IOrganizationService service, string entityName, ColumnSet columns, params ConditionExpression[] conditions)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	entityName
Microsoft.Xrm.Sdk.Query.ColumnSet	columns
Microsoft.Xrm.Sdk.Query.ConditionExpression[]	conditions

Returns

Type	Description
Microsoft.Xrm.Sdk.EntityCollection	A list of DynamicEntities.

RetrieveMultiple(IOrganizationService, String, ColumnSet, String, ConditionOperator, Object)

Retrieves a list of multiple DynamicEntities given the conditions.

Declaration

public static EntityCollection RetrieveMultiple(this IOrganizationService service, string entityName, ColumnSet columns, string conditionAttribute, ConditionOperator conditionOp, object conditionValue)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service
System.String	entityName
Microsoft.Xrm.Sdk.Query.ColumnSet	columns
System.String	conditionAttribute
Microsoft.Xrm.Sdk.Query.ConditionOperator	conditionOp
System.Object	conditionValue

Returns

Type	Description
Microsoft.Xrm.Sdk.EntityCollection	A list of DynamicEntities.

UpdateMultiple(IOrganizationService, IEnumerable<Entity>)

Update multiple records for a single dataverse table.

Declaration

public static void UpdateMultiple(this IOrganizationService svc, IEnumerable<Entity> entities)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc	Dataverse client
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>	entities	List of records to create

UploadFile(IOrganizationService, EntityReference, String, Byte[], String, String, Int32)

Uploads a file to the given record / column

Declaration

public static CommitFileBlocksUploadResponse UploadFile(this IOrganizationService service, EntityReference targetEntityReference, string targetColumnName, byte[] fileAsByteArray, string fileName, string mimeType, int maxUploadBlockSizeInBytes = 4194304)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	service	The instance of the organization service
Microsoft.Xrm.Sdk.EntityReference	targetEntityReference	An Entity Reference to the desired record
System.String	targetColumnName	The column name to which the file should be uploaded
System.Byte[]	fileAsByteArray	The file to be uploaded as a byte[]
System.String	fileName	The name to be associated with the uploaded file
System.String	mimeType	The mime type that should be associated to the file (e.g. application/xml or application/pdf)
System.Int32	maxUploadBlockSizeInBytes	An optional parameter that can be used to control how large the individual blocks of data are when being uploading large files. At the time of writing, this value cannot be larger than 4 MB (i.e. 4,194,304 Bytes)

Returns

Type	Description
Microsoft.Crm.Sdk.Messages.CommitFileBlocksUploadResponse	The CommitFileBlocksUploadResponse returned by the upload process

UpsertMultiple(IOrganizationService, IEnumerable<Entity>)

Upserts multiple records for a single dataverse table.

Declaration

public static UpsertResponse[] UpsertMultiple(this IOrganizationService svc, IEnumerable<Entity> entities)

Parameters

Type	Name	Description
Microsoft.Xrm.Sdk.IOrganizationService	svc	Dataverse client
System.Collections.Generic.IEnumerable<Microsoft.Xrm.Sdk.Entity>	entities	List of records to create

Returns

Type	Description
Microsoft.Xrm.Sdk.Messages.UpsertResponse[]