Most Useful Extension Methods

There are quite a few extension methods available in Hsl.Xrm.Sdk and they're all useful but this list's goal is to get you familiar with some of the most helpful ones available. Reviewing the other extension methods available in the API documentation is recommended.

IOrganizationService extensions

• RetrieveAllLazy - loads and pages through all pages of records based on fetchxml or a QueryExpression getting you all of them beyond the first 5000 records.
  • Similar methods RetrieveAllAsync and FetchAllAsync exists for IAsyncOrgService to use with the async org service.
• BulkRetrieveByIds - loads a set of records by primary ids. When possible, use a single query instead but it isn't always possible.
  • Ex: You retrieve a set of accounts and want to get the primary contacts for each of them: Use a join instead.
  • Ex: You have a list of accounts and the user checks the ones they want to run an operation on. You need to retreive additional info for the checked accounts: Use this method.
• ExecuteMultiple - executes multiple OrganizationService requests. This will automatically batch the requests if there are too many.
• Retrieve<T>, Fetch<T>, RetrieveAllLazy<T> automatically converts the returned data to the specified early bound type.

Entity extensions

• GetFieldValue<T> gets the field as the specified type. Besides the SDK types like OptionSetValue, the following are supported:
  • Currency - decimal, decimal?
  • Picklist - int, int?, enum, enum?
  • Multiselect - int[], List<int>, enum[], List<enum> (returns an empty list instead of null by default if the field is null)
  • EntityReference - Guid, Guid?, string (Name)
  • Auto-unwrapping AliasedValue Ex: GetFieldValue<int> for an alias picklist field would return the numeric value of the field.
• GetFieldDisplayText - gets text for the field appropriate to display to end users. (Formatted value if available otherwise EntityReference Name or string field value)
• TryRemoveUnchangedFields - compares field values from the current values for a record and what you want to update those values to and removed unchanged ones from the UpdateRequest. It does the best it can without hitting the database but unchanged fields aren't always removed. For example, alternate keys are not checked. See documentation for more details. Benefits of doing this include faster execution, eliminate unnecessary triggering of plugins/workflows that are set to trigger from the unchanged field being updated, and a cleaner audit log.

Other extensions

• int?.ToOptionSetValue converts a nullable int to a OptionSetValue or null. Eliminates intValue == null ? null : new OptionSetValue(intValue.Value) boilerplate.
• decimal?.ToMoney - similar to int?.ToOptionSetValue but for currency fields
• Guid?.ToEntityReference - similar to int?.ToOptionSetValue but for lookup fields
• Exception.ToTraceString - inclues some additional details from FaultException<OrganizationServiceFault>'s Detail that aren't included with the regular ToString method.