Hide menu Last updated: Jun 01 2017
Area: Episerver Social Applies to versions: 1.4 and higher
Other versions:

Discovering the platform

Several common concepts and conventions apply throughout the Episerver Social platform. An understanding of these strategies is helpful in discovering the tools available to you.

Services

The primary point of interaction with the Episerver Social platform are the service classes exposed by each of the platform's features. Each service implements an interface, which conforms to the following naming convention: I{Feature-Name}Service. Examples include:

  • ICommentService
  • IRatingService
  • IGroupService

If a platform feature is installed to an Episerver CMS site with the feature's site integration package, you can get an instance of a service from the inversion of control (IoC) container.

Example

var commentService = EPiServer.ServiceLocation.ServiceLocator.Current.GetInstance<ICommentService>();

If a platform feature is installed to a non-Episerver CMS site, you can get an instance of a service from the default factory classes provided within the package.

Example

var factory = new EPiServer.Social.Moderation.Factories.DefaultWorkflowServiceFactory();
var workflowService = factory.Create();

Data models

You can find the data models consumed and returned by the Social platform's services beneath the "core" namespace accompanying a particular platform feature. The convention for "core" namespaces is: EPiServer.Social.{Feature-Name}.Core". For example:

  • EPiServer.Social.Comments.Core
  • EPiServer.Social.Ratings.Core

Exceptions

You can find exceptions thrown by the Social platform's services beneath the "Core" namespace accompanying a particular platform feature. The convention for "Core" namespaces is: EPiServer.Social.{Feature-Name}.Core. For example:

  • EPiServer.Social.Comments.Core
  • EPiServer.Social.Ratings.Core

Additionally, you may find exception types, which are shared throughout the platform, in the EPiServer.Social.Common namespace.

Platform exceptions

The features of the Episerver Social platform share a number of exception types to communicate general platform error situations.

SocialAuthenticationException

A SocialAuthenticationException is thrown by all methods of an Episerver Social service when a request is deemed to be unauthentic.

This error most commonly occurs when:

  • The application's configuration is missing one or more of its authentication settings.
  • The application's configuration contains inaccurate authentication settings.
  • The application's server time is inaccurate.

For more information regarding configuration and authentication, see Getting connected.

MaximumDataSizeExceededException

A MaximumDataSizeExceededException is thrown by all methods of an Episerver Social service when a request exceeds the platform's size restrictions.

The platform accepts social content up to 10 kilobytes in size. This restriction applies to the entirety of any given social entity, which includes the native properties of the platform's content models, optional extension data, and any overhead of those models.

For example, consider a simple comment that contains an author reference, body, and parent reference. Consider that you also composed this comment with custom extension data. The content associated with each of those native comment properties as well as that of the extension data contribute to the total size of the request.

The platform does not explicitly restrict the amount of content that can be associated with any individual property of a social content model. This allows you to prioritize the size of content that the application allots to native content models versus custom extension data.

The application should enforce limits on the amount of content that may be contributed, as applicable to its use cases. In doing so, it minimizes the likelihood that this exception may occur.

RateLimitExceededException

A RateLimitExceededException is thrown by all methods of an Episerver Social service when an application issues too many requests over a short period of time. All requests issued to Episerver Social are tallied and compared against the rate limit. When an application exceeds the rate limit, Episerver Social stops processing requests until a certain amount of time has elapsed (referred to as a "request interval").

The exception provides additional information to help the application regulate its request rate. That information includes:

  • RequestInterval - The length of time in which requests are tallied
  • RequestsIssued - The number of requests that have already been issued in the request interval
  • RequestLimit - The maximum number of requests allowed in a given request interval
  • RetryAfter - The amount of time remaining until the application may resume issuing requests

If your application regularly encounters this exception, consider:

  • Optimizing your code to minimize unnecessary API calls
  • Caching data that is frequently accessed
  • Actively regulating the application's request rate to ensure that the application never encounters the issue
  • Implementing logic to pause and retry requests after reaching the limit

SocialCommunicationException

An SocialCommunicationException is thrown by all methods of an Episerver Social service when a request encounters a fundamental communication issue.

This error most commonly occurs when:

  • The application cannot connect or communicate with Episerver Social platform cloud services.
  • A request from the application exceeds the configured timeout.

SocialException

A SocialException is thrown by all methods of an Episerver Social service when a request encounters an unexpected error scenario. The exception contains a message, status code, error code, and additional reasoning to further describe the error.

This error most commonly occurs when:

  • The application's configuration is missing or malformed.
  • The platform encountered an unexpected service error.

Feature exceptions

The individual services of the Episerver Social platform may also throw exceptions that are unique to the feature that they support. Information on feature-specific exceptions can be found in the documentation for each API.

Reference and IDs

The Episerver Social platform has two means of identifying data: by reference and by ID. The structure and function of these classifiers are similar, but there are important semantic distinctions between them.

Ids

The Id classes that appear in each Social platform feature pertain specifically to that feature's entities. Their values are internally-generated and used to distinguish individual entities within the system.

Id classes conform to the following naming convention: {Feature-Name}Id. Examples include:

  • CommentId
  • GroupId
  • WorkflowId

Id classes are accepted by the platform's services when retrieving specific instances of data.

Reference

The Reference class that appears in the Episerver Social platform refers to users or resources outside the platform. References identify entities in other systems. Use a reference value to establish relationships between social content and resources or users to which that content applies.

The value contained within a reference class is defined by the developer. It contains the information necessary to identify or classify the resource or user to which social content is related.

The platform provides a Reference class that is used to identify any target entity in your application. For example, a resource, like Episerver CMS content or a product or a user, like an Episerver CMS user.

Best practices for defining references

You, as a developer, are free to define references as it suits your application. Ultimately, you want to ensure that your reference scheme is:

  • Capable of uniquely identifying your application's entities
  • Capable of being easily interpreted by your application
  • Robust enough to support your application's inevitable enhancements and changes

We are accustomed to thinking of identifiers as unique IDs, such as GUIDs or hashes. These are often sufficient to identify data within a single system but may be insufficient when integrating with multiple systems. When designing your scheme for defining reference values, consider the following factors:

  • Platform. In what platform does your resource or user reside?
  • Provider. Does that platform deliver resources or users through different providers?
  • Classification. What type of data is being referenced? Is it content, a product, a CMS user, an ecommerce customer?
  • Categorization. Is there a taxonomical nature to a resource or a user's identification?
  • Facets. Do you intend to refer to a facet of some resource, like a product's price or color?

These considerations play a role in designing a meaningful reference scheme.

A URI or similar namespace scheme provides an ideal template for a reference. Consider the following example of a reference scheme that might be applied to ecommerce content:

resource://episerver/commerce/{product-identifier}/{variant-identifier}/{facet-identifier}

In this example, the content's classification, platform, hierarchical identifiers, and facets are accounted for.

Criteria

The Episerver Social platform's services let you retrieve custom result sets of the content, which you are managing with it. These services accept criteria that dictate how to retrieve a result set. A class named Criteria<TFilter> encapsulates the specifications necessary to retrieve a collection of results from one of the platform services.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The Criteria class encapsulates the specifications by which platform entities
    //     should be retrieved.
    //
    // Type parameters:
    //   TFilter:
    //     Type of filter specifications comprising this criteria
    public class Criteria<TFilter>
    {
        //
        // Summary:
        //     Constructor
        public Criteria();
        //
        // Summary:
        //     Gets the filter specifications describing the results which 
        //     should be retrieved.
        public TFilter Filter { get; }
        //
        // Summary:
        //     Gets a collection of rules describing how the result set 
        //     should be ordered.
        public List<SortInfo> OrderBy { get; set; }
        //
        // Summary:
        //     Gets or sets the index and size of the page of results to 
        //     be retrieved.
        public PageInfo PageInfo { get; set; }
    }
}

Filter

The type parameter TFilter identifies the class that encapsulates the filter specifications applicable to the service and the content it manages. The particular filter class required by a service is identified in the signature of its retrieval methods.

The Filter property accepts an instance of the filter class, which captures the specifications by which you wish to refine a result set.

PageInfo

The PageInfo property accepts an instance of a class by the same name, which defines the specifications by which a result set is paginated into collections of a fixed number of results.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The PageInfo class represents the criteria necessary to identify a subset of
    //     some larger result set.
    public class PageInfo
    {
        public PageInfo();

        //
        // Summary:
        //     Gets or sets the record offset (zero-based) from which to begin retrieving 
        //     the items that will comprise a page.
        public int PageOffset { get; set; }
        //
        // Summary:
        //     Gets or sets the number of items per page.
        public int PageSize { get; set; }
        //
        // Summary:
        //	Gets or sets whether the total count will be returned in the result page.
        public bool CalculateTotalCount { get; set; }
    }
}

The PageInfo class captures a page size, representing the maximum number of results to retrieve. The page size must be greater than or equal to zero. If page size is not specified, a default of 10 items is applied.

PageInfo also captures a page offset, representing the index (zero-based) from which to begin retrieving results. The page offset must be greater than or equal to zero.

PageInfo also allows the user to specify if they want to calculate a total result count for the query. This count is returned with the TotalCount property on the ResultPage. By default, no total count is calculated.

Best practices for paginating results

Your page size, page offsets, and total count are important to consider when optimizing your implementation. Large page sizes or deep offsets can negatively impact the performance of your content retrieval. Consider your request size, request volume, and user experience to find the appropriate balance when determining your application's pagination strategy. Additionally, retrieving the TotalCount for a query when it is not needed adversely affects the time it takes to return a ResultPage.

OrderBy

The OrderBy property accepts a collection of rules describing how to sort the result set. Each sorting rule is represented by an instance of a class named SortInfo.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The SortInfo class is a data structure describing the manner in which a result
    //     set should be sorted.
    public class SortInfo
    {
        //
        // Summary:
        //     Constructor
        //
        // Parameters:
        //   field:
        //     Field on which to sort
        //
        //   ascending:
        //     Direction in which to sort
        public SortInfo(SortField field, bool ascending);

        //
        // Summary:
        //     Gets the direction in which to sort.
        public bool Ascending { get; }
        //
        // Summary:
        //     Gets the field on which to sort.
        public SortField Field { get; }
    }
}

An instance of the SortInfo class identifies the field on which to sort and the direction in which to sort. For example, you might sort a result set of comments by the field representing their publication date in descending order.

A subset of the fields on the platform's data models is available for sorting. This curated set of fields is exposed through classes which adhere to a particular convention. These fields are statically exposed on classes named {Feature-Name}SortFields. For example, CommentSortFields and RatingSortFields.

The sorting rules identified in the collection are processed in order by the service, which executes the result retrieval. Each subsequent rule in the collection represents a fallback, if multiple results share a matching value in the field identified by the preceding sorting rule. For example, if you sort ratings by their value, you might specify a fallback of the ratings' modification date to ensure that the platform consistently orders ratings with the same value.

Best practices for sorting results

The platform cannot guarantee the order of results, from request to request, if a field targeted for sorting contains matching values for multiple result items. If consistency in result ordering is relevant, it is important to specify one or more fallback sorting rules. Consistency is particularly important if your application lets users navigate through multiple pages of result items.

Sorting of string values will occur based upon the Unicode value of a character. If your application requires alternative ordering for a property it is recommended that the data be standardized in code and stored as a duplicate property on the extension data.

Result sets

The services of the Episerver Social platform, which expose bulk retrieval capabilities, deliver their results in a paginated fashion. A page of results is represented with a class named ResultPage<T>.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The ResultPage class represents a single page of results retrieved from the 
    //     Social platform.
    //
    // Type parameters:
    //   T:
    //     Type of the result items comprising the page
    public class ResultPage<T>
    {
        //
        // Summary:
        //     Constructor
        //
        // Parameters:
        //   results:
        //     Collection of result items comprising the page
        //
        // totalCount:
        //	Total count of items resulting from the query
        //
        // info:
        //	Information describing the specifications of the page
        //
        // hasMore:
        //	Boolean denoting whether the query has found more items beyond this page.
        ResultPage(IEnumerable<T> results, long totalCount, PageInfo info, bool hasMore);

        //
        // Summary:
        //     Gets information describing the specifications of this page.
        public PageInfo Info { get; }
        //
        // Summary:
        //     Gets the collection of result items comprising the page.
        public IEnumerable<T> Results { get; }
        //
        // Summary:
        //     Gets the total count of items resulting from the query that produced this
        //     page.
        public long TotalCount { get; }
        ///
        /// Summary:
        ///	Gets whether there are additional items to be returned in a subsequent request.
        public bool HasMore { get; }
    }
}

Results

The type parameter T identifies the class representing the model for the data to be returned. For example, Comment or Rating. The Results property gets the collection of individual result items which comprise the page.

TotalCount

The TotalCount property provides a total count of items resulting from the query. For example, a product has 20 comments. In requesting this product's comments, a page size of 10 is specified. The resulting page of comments would include 10 items, while its TotalCount property would have a value of 20. A total count is calculated when the CalculateTotalCount property of the PageInfo associated with your criteria is assigned a value of true. If CalculateTotalCount is set to false, the total count is -1.

Info

The Info property provides a reference to the paging specifications, which were specified when the request that produced the page was issued.

HasMore

The HasMore property provides a boolean that denotes whether the query has found more items beyond the page returned. An example of this would be a query with 11 results in the database, and a query is issued with a PageSize of 10. The ResultPage would return 10 results and have a HasMore value of true. This provides a developer insight into whether an additional query with a PageOffset of 10 would return any items in the ResultPage. In this example, if a second query were issued, it would return 1 item in the ResultPage and have a HasMore value of false.

Composites

Every application has unique needs with regard to the structure of its social content. Applications have different systems to integrate with, different visions of a what community-generated content is comprised of, and different entities and actions to moderate. An application needs the freedom to store, relate, and present social content in a form that it determines appropriate. With this in mind, the features of the Episerver Social platform distill social concepts to their essence and invite data extensibility by allowing its native entities to be composed with custom data models.

What is a composite?

The Episerver Social platform encourages data extensibility through the composition of native platform entities with custom extension data. Extension data is a .NET class, defined within your application, intended to capture additional details necessary to shape a platform entity to meet your application's needs.

The platform's services encapsulate the relationship between their entities and extension data with the Composite class. The Composite class represents a simple pairing, an instance of a native platform entity and its associated extension data.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The Composite class represents the composition of a data model from the Social
    //     platform and custom data applied to extend that model.
    //
    // Type parameters:
    //   TModel:
    //     Type of data model to be extended in the composition
    //
    //   TExtension:
    //     Type of data applied as an extension
    public class Composite<TModel, TExtension>
    {
        //
        // Summary:
        //     Constructor
        //
        // Parameters:
        //   data:
        //     Primary data model to be extended through composition
        //
        //   extension:
        //     Data applied as an extension in this composition
        public Composite(TModel data, TExtension extension);

        //
        // Summary:
        //     Gets the primary data model in this composition.
        public TModel Data { get; }
        //
        // Summary:
        //     Gets the data applied as an extension of the primary data model.
        public TExtension Extension { get; }
    }
}

Defining extension data

Extension data is a .NET class, defined within your application, and intended to capture additional details necessary to shape a platform entity to meet your application's needs. As you design the classes that represent your extension data, consider the following:

  • Queryability. The platform is capable of sorting and filtering composite result sets according to a select set of primitive value types within your extension data. If you intend to filter or sort by particular extension data values, it is important to design your extension data class accordingly. (See Filtering Composites.)
  • Maintainability. Anticipate the likelihood of future enhancements to your application's data and the impact of changes on your classes or business logic. Think of your extension data as a schema and approach its design carefully.
  • Performance. Keep extension data light to minimize the likelihood of performance penalties in its transfer.

Extension data is subject to the realities and limitations of today's serialization engines. To ensure that your data can be stored and retrieved successfully, the extension data class must abide by the following constraints:

  • It must have a public, parameter-less constructor.
  • It must not refer to nested data in a polymorphic manner. For example, the class must not refer to a child as the Object type.
  • It must not contain self-references or referential loops.
  • The class name, as well as the names of the assemblies and namespaces that contain it, must remain stable to ensure that the platform can identify the data that has been stored.
  • An instance of this data contributes to the total size of a request to the platform. Minimize the size of this data to avoid exceeding platform size restrictions.

If these constraints are not respected, you may encounter errors while storing and retrieving composites.

It is strongly recommended that you utilize only classes defined within your application when defining extension data. The data models of this platform are not guaranteed to be serializable. Defining your own classes, rather than utilizing those of a third-party library, also helps to future-proof your schema. This mitigates the risk of volatility within your dependencies. 

When defining extension data, consider these additional caveats:

  • DateTime values in extension data are stored and returned as Universal Time Coordinated (UTC).
  • DateTime precision is consistent up to the millisecond value.
  • There is no support for the Decimal type in the Episerver Social Platform. As a result, a Decimal value is stored as a double and can be subject to a rounding error.

Composite criteria

The Episerver Social platform lets you retrieve result sets of composite data in a manner similar to that of its standard entities. Each platform service that supports Composites provides methods for retrieving them. The services delivering result sets of composite data accept composite criteria. This criteria is represented by a class named CompositeCriteria<TFilter, TExtension>.

namespace EPiServer.Social.Common
{
    //
    // Summary:
    //     The CompositeCriteria class encapsulates the specifications by which platform
    //     entities, composed with extension data, should be retrieved.
    //
    // Type parameters:
    //   TFilter:
    //     Type of filter specifications comprising this criteria
    //
    //   TExtension:
    //     Type of data, applied as an extension of platform entities, by which to filter
    public class CompositeCriteria<TFilter, TExtension> : Criteria<TFilter>
    {
        //
        // Summary:
        //     Constructor
        public CompositeCriteria();

        //
        // Summary:
        //     Gets or sets an expression describing a filter targeting data applied as 
        //     an extension to platform entities.
        public FilterExpression ExtensionFilter { get; set; }
        //
        // Summary:
        //     Gets or sets a boolean indicating whether the result set should include
        //     subclasses of the specified type filter.
        public bool IncludeSubclasses { get; set; }
    }

The CompositeCriteria class extends the standard Criteria class, incorporating its capabilities. The filters and other specifications exposed by Criteria may be applied in conjunction with the additional enhancements afforded by the CompositeCriteria class.

ExtensionFilter

The TExtension type parameter identifies the type of extension data to be retrieved. This serves as an implicit filter; only Composites with extension data of this type are retrieved.

The ExtensionFilter property accepts a Boolean expression capable of filtering your result set by values represented within your extension data. This expression is represented as a tree structure and may combine multiple Boolean expressions with logical operators (like "AND"), also provided by the platform. For more information regarding the construction of these expressions, see Filtering Composites.

IncludeSubclasses

The IncludeSubclasses property accepts a value, which indicates if the result set should include items bearing extension data that implements a subclass of the type identified by the TExtension type parameter.

  • True indicates that the result set may include composites where TExtension appears anywhere within the type hierarchy of their associated extension data. This is the default behavior.
  • False indicates that the result set includes only composites where their extension data is explicitly of the TExtension type.

Filtering composites

Composites allow a developer to extend the platform by composing platform entities with supplemental data of their own design. This feature is enhanced by the ability to define custom filters for result sets, which include that data. We refer to this type of refinement as a Filter Expression.

Filter Expressions are Boolean expressions, represented as tree structures, which can filter a result set of Composites by values included within their extension data. Consider an example where an application composes a comment with extension data via the following definition:

public class MyCommentExtension
{
    public int LuckyNumber { get; set; }
    public string FavoriteTeam { get; set; }
    public DateTime Birthday { get; set; }
}

In this example, our application requires us to filter composite comments to those with a LuckyNumber of 7 and a Birthday prior to 1990. A filter that accounts for these specifications can be represented as the following expression tree:

The platform provides the tools necessary to easily construct such an expression tree. The primary point of access for doing so is a class named FilterExpressionBuilder<TExtension>.

The FilterExpressionBuilder exposes convenient methods and operator overloads for individual Boolean and logical operators available to developers when defining Filter Expressions. This class's TExtension type parameter identifies the type of extension data, which the resulting expression is intended to target.

The operators available for defining filters include:

Builder methodClassDescriptionBuilder Operator Overloads
Field FieldExpression Represents a field.  
EqualTo EqualToExpression Represents an equality comparison. ==
Contains ContainsExpression Represents an equality comparison in collections  
GreaterThan GreaterThanExpression Represents a greater than comparison >
GreaterThanOrEqualTo GreaterThanOrEqualToExpression Represents a greater than or equal to comparison >=
LessThan LessThanExpression Represents a less than comparison <
LessThanOrEqualTo LessThanOrEqualToExpression Represents a less than or equal to comparison <=
And AndExpression Represents a logical AND of a collection of filter expressions. &
Or OrExpression Represents a logical OR of a collection of filter expressions. |

The expressions representing Boolean operators, which are available within the platform, can compare fields of the following .NET data types:

  • String
  • Boolean
  • Int
  • Long
  • Double
  • DateTime

Continuing the above example, consider how a developer would leverage the FilterExpressionBuilder to construct the necessary Filter Expression.

var luckyNumberOf7 = FilterExpressionBuilder<MyCommentExtension>.Field(d => d.LuckyNumber).EqualTo(7);

The snippet above constructs a Boolean expression, which evaluates the LuckyNumber field of our extension data for a value of 7. This example features two method calls:

  • The Field method accepts a lambda expression, which selects the extension data field we intend to represent in the Filter Expression.
  • The FieldExpression's EqualTo method accepts a value, constructing an EqualToExpression where our FieldExpression represents its left operand, and the value represents its right operand.

The result of this operation is the expression tree below:

expression tree2

var bornBefore1990 = FilterExpressionBuilder<MyCommentExtension>.Field(d => d.Birthday).LessThan(new DateTime(1990, 1, 1));

Similarly, the snippet above constructs a Boolean expression which evaluates the Birthday field of our extension data for a value prior to the year 1990. The result of this operation is the expression tree below:

expression tree3

We can combine these two Boolean expressions into a single Filter Expression by logically ANDing them, as demonstrated in the snippet below:

var combinedExpression = FilterExpressionBuilder<MyCommentExtension>.And(luckyNumberOf7, bornBefore1990);

The result of this operation, which completes our filter for this example, is the expression tree below:

expression tree4

To put these snippets in context, the construction of criteria reflecting a request for composite comments might appear as follows:

var luckyNumberOf7 = FilterExpressionBuilder<MyCommentExtension>.Field(d => d.LuckyNumber).EqualTo(7);
var bornBefore1990 = FilterExpressionBuilder<MyCommentExtension>.Field(d => d.Birthday).LessThan(new DateTime(1990, 1, 1));
var combinedExpression = FilterExpressionBuilder<MyCommentExtension>.And(luckyNumberOf7, bornBefore1990);
var criteria = new CompositeCriteria<Comment, MyCommentExtension>
{                
    ExtensionFilter = combinedExpression
};

Best practices for defining filter expressions

  • Elaborate filter expressions can impact the performance of your requests. For optimal performance, minimize the complexity and depth of your expressions.
  • Changes to the structure of your extension data classes may result in malformed expressions.
  • Malformed expressions may result in unexpected results or empty result sets. Think of your extension data as a schema and approach its design with care.

Sorting composites

Just as fields represented within extension data may be referenced in filtering Composite result sets, they may also be applied in sorting result sets. Sorting rules are defined with the CompositeCriteria class, just as they are for the standard Criteria class. Its OrderBy property accepts a collection of rules describing how to sort the result set. Each sorting rule is represented by an instance of a class named SortInfo.

An instance of the SortInfo class identifies the field and the direction on which to sort. A field represented in your extension data may be identified in the construction of SortInfo by leveraging the FilterExpressionBuilder. (For more information on the FilterExpressionBuilder, see Filtering Composites.)

Consider an example where an application composes a comment with extension data with the following definition:

public class MyCommentExtension
{
    public int LuckyNumber { get; set; }
    public string FavoriteTeam { get; set; }
    public DateTime Birthday { get; set; }
}

The snippet below demonstrates the construction of an instance of SortInfo, targeting the LuckyNumber field of such an extension:

var sortField = new SortField(FilterExpressionBuilder<MyCommentExtension>.Field(d => d.LuckyNumber));
var sortingRule = new SortInfo(sortField, true);
var criteria = new CompositeCriteria<Comment, MyCommentExtension>
{                
    OrderBy = new List<SortInfo> { sortingRule }
};

In this example, an instance of SortField is constructed. It accepts a FieldExpression representing the LuckyNumber field of our extension data. Next, an instance of SortInfo is constructed to refer to this SortField, and assigned to the criteria as a sorting rule.

Sorting rules targeting the fields represented within extension data may be applied to your criteria in conjunction with those targeting the curated set of sort fields available for platform entities. (For more information, see Criteria.)

Asynchronous Methods

In addition to methods that run synchronously, the Episerver Social services also expose method overloads for use in an asynchronous programming model. If the needs of your application are such that you cannot block an application thread while invoking the Episerver Social services, you can employ a corresponding overload of that method.

In a synchronous operation, the calling thread cannot continue until the API completes its operation. On the other hand, when these overloads are invoked using the appropriate asynchronous .NET techniques, it can now run to completion without blocking. Meanwhile, the calling thread in your application can perform its additional business logic in parallel. Being able to perform tasks in parallel can improve the overall responsiveness and performance of your application.

All asynchronous methods in the Episerver Social framework end with the Async suffix and return a .NET Task object. A Task object is used to represent an asynchronous operation. For more details refer to Microsoft's documentation for Task-based Asynchronous Programming. An Async overload is available for any Episerver Social method that can potentially block the calling thread while communicating with the framework's cloud services to perform an operation.

You can use C#'s async and await keywords to perform long-running work without blocking the calling thread. For more details refer Microsoft's documentation on Asynchronous Programming with async and await.

Episerver Social asynchronous overloads are discussed in detail with code examples along side their synchronous versions in the Episerver Social feature documentation.

Comments