Table of Contents

Class OrganizationServiceExtensions

Namespace
Hsl.Xrm.Sdk
Assembly
Hsl.Xrm.Sdk.Core.dll

Extension methods for IOrganizationService

public static class OrganizationServiceExtensions
Inheritance
OrganizationServiceExtensions
Inherited Members

Methods

AssociateManySafe(IOrganizationService, string, EntityReference, string, IEnumerable<Guid>, bool)

Associates the given records unless they're already associated.

[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

service IOrganizationService
relationshipName string
record1Ref EntityReference
associateEntityName string
idsToAssociate IEnumerable<Guid>
skipExistingCheck bool

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.

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

Parameters

service IOrganizationService

The org service.

record EntityReference

The record to which relatedRecords will be associated.

relationship Relationship

The many-to-many relationship. If the relationship is reflexive (same entity on both sides), then the PrimaryEntityRole property must be specified.

relatedRecords EntityReferenceCollection

The records to associate.

intersectEntityName string

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.

intersectEntityAttributeToRecord string

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.

intersectEntityAttributeToRelated string

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

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.

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

Parameters

service IOrganizationService

The org service.

record EntityReference

The record to which relatedRecord will be associated.

relationship string

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.

relatedRecord EntityReference

The record to associate.

intersectEntityName string

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.

intersectEntityAttributeToRecord string

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.

intersectEntityAttributeToRelated string

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

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, bool)

Associates the given records unless they're already associated.

[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

service IOrganizationService
relationshipName string
record1Ref EntityReference
record2Ref EntityReference
skipExistingCheck bool

BulkRetrieveByIds(IOrganizationService, string, IEnumerable<Guid>, ColumnSet, BulkRetrieveByIdsOptions?)

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

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

Parameters

svc IOrganizationService
entityName string
ids IEnumerable<Guid>
columns ColumnSet
options BulkRetrieveByIdsOptions

Returns

IEnumerable<Entity>

CreateMultiple(IOrganizationService, IEnumerable<Entity>)

Creates multiple records for a single dataverse table.

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

Parameters

svc IOrganizationService

Dataverse client

entities IEnumerable<Entity>

List of records to create

Returns

Guid[]

Ids of the created records

DeleteFile(IOrganizationService, EntityReference, string)

Deletes the file from the given record / column

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

Parameters

service IOrganizationService

The instance of the organization service

targetEntityReference EntityReference

An Entity Reference to the desired record

targetColumnName string

The column name from which the file should be downloaded

DeleteFile(IOrganizationService, Guid)

Deletes the file identified via the GUID

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

Parameters

service IOrganizationService

The instance of the organization service

fileId Guid

The GUID of the file to be deleted

DisassociateSafe(IOrganizationService, string, EntityReference, EntityReference, bool)

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

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

Parameters

service IOrganizationService
relationshipName string
record1Ref EntityReference
record2Ref EntityReference
skipExistingCheck bool

DownloadFile(IOrganizationService, EntityReference, string, int)

Downloads a file from the given record / column

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

Parameters

service IOrganizationService

The instance of the organization service

targetEntityReference EntityReference

An Entity Reference to the desired record

targetColumnName string

The column name from which the file should be downloaded

maxDownloadBlockSizeInBytes int

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

byte[]

A byte[] representation of the file

ExecuteMultiple(IOrganizationService, bool, bool, params OrganizationRequest[])

Executes the specified set of requests.

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

Parameters

service IOrganizationService
continueOnError bool
returnResponses bool
requests OrganizationRequest[]

Returns

ExecuteMultipleResponse

Fetch(IOrganizationService, string)

Fetches records based on the given fetchxml.

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

Parameters

service IOrganizationService
fetchXml string

Returns

EntityCollection

Fetch<T>(IOrganizationService, string)

Fetches records based on the given fetchxml.

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

Parameters

service IOrganizationService
fetchXml string

Returns

List<T>

Type Parameters

T

Retrieve(IOrganizationService, EntityReference, params string[])

Retrieves the given record by alternate key or primary id.

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

Parameters

service IOrganizationService
entity EntityReference

Either a primary id or alternate key reference to the record to retrieve

columns string[]

Returns

Entity

RetrieveAllLazy(IOrganizationService, QueryExpression, RetrieveAllOptions?)

Pages through records until options.MaxResults is reached.

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

Parameters

svc IOrganizationService
query QueryExpression
options RetrieveAllOptions

Returns

IEnumerable<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.

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

Parameters

svc IOrganizationService
fetchXml string
options RetrieveAllOptions

Returns

IEnumerable<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.

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

Parameters

svc IOrganizationService
query QueryExpression
options RetrieveAllOptions

Returns

IEnumerable<T>

Type Parameters

T

RetrieveMultiple(IOrganizationService, string, ColumnSet, params ConditionExpression[])

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

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

Parameters

service IOrganizationService
entityName string
columns ColumnSet
conditions ConditionExpression[]

Returns

EntityCollection

A list of DynamicEntities.

RetrieveMultiple(IOrganizationService, string, ColumnSet, string, ConditionOperator, object)

Retrieves a list of multiple DynamicEntities given the conditions.

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

Parameters

service IOrganizationService
entityName string
columns ColumnSet
conditionAttribute string
conditionOp ConditionOperator
conditionValue object

Returns

EntityCollection

A list of DynamicEntities.

Retrieve<T>(IOrganizationService, Guid, params string[])

Retrieves the record with the given id.

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

Parameters

service IOrganizationService

The instance of the organization service

id Guid

Primary id of the record to retrieve

columns string[]

The set of attributes to retrieve

Returns

T

Retrieved record

Type Parameters

T

Early bound type to use.

UpdateMultiple(IOrganizationService, IEnumerable<Entity>)

Update multiple records for a single dataverse table.

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

Parameters

svc IOrganizationService

Dataverse client

entities IEnumerable<Entity>

List of records to create

UploadFile(IOrganizationService, EntityReference, string, byte[], string, string, int)

Uploads a file to the given record / column

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

Parameters

service IOrganizationService

The instance of the organization service

targetEntityReference EntityReference

An Entity Reference to the desired record

targetColumnName string

The column name to which the file should be uploaded

fileAsByteArray byte[]

The file to be uploaded as a byte[]

fileName string

The name to be associated with the uploaded file

mimeType string

The mime type that should be associated to the file (e.g. application/xml or application/pdf)

maxUploadBlockSizeInBytes int

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

CommitFileBlocksUploadResponse

The CommitFileBlocksUploadResponse returned by the upload process

UpsertMultiple(IOrganizationService, IEnumerable<Entity>)

Upserts multiple records for a single dataverse table.

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

Parameters

svc IOrganizationService

Dataverse client

entities IEnumerable<Entity>

List of records to create

Returns

UpsertResponse[]