HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket


A group is a named aggregation of users and content. Users are associated with a group by adding them as a member.

Members are represented with the `Member` class.

Members are managed through a service implementing the interface `IMemberService`. This service provides the ability to persist, retrieve, and remove `Members` that you define.

## Access an IMemberService

When the `Groups` feature is installed to an Optimizely Content Management System (CMS) site with the feature's site integration package, you can get an instance of this service from the inversion of control (IoC) container.

Example:



When the feature is installed to a non-Optimizely CMS site, you can get an instance of a service from the default factory class provided within the package.



## Add a member

To add a member, use the `Add(Member)` method of the `IMemberService`. This method accepts an instance of the `Member` class, and returns a reference to a new instance of that class, which is populated with any additional, system-generated, data (for example, a unique ID).



If the identified group cannot be found, a `GroupDoesNotExistException` is thrown.

If the member already exists, a `DuplicateMemberException` is thrown.

In the above example, the request to add a member is invoked synchronously. An example of adding a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Validate a member

To validate that a user is a member of a group, use the `IsMember(GroupId,Reference)` method of the `IMemberService`. This method accepts an instance of the `GroupId` class, identifying the target group, and an instance of the `Reference` class, identifying the target user. The method returns a Boolean, indicating whether or not the identified user is a member of the identified group.



In the above example, the request to validate if a user is a member of a group is invoked synchronously. An example of validating the membership of a user in a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Remove a member

To remove a specific instance of Member, which was previously added through the platform, use the `Remove(MemberId)` class. This method accepts an instance of the `MemberId` class, which identifies the `MemberId` to be removed. The result is the deletion of the `Member` corresponding to that ID.



In the above example, the request to remove a member is invoked synchronously. An example of removing a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Retrieve a member

You can retrieve a specific instance of a `Member`, which was previously added through the platform, by using the `Get(MemberId)` method of `IMemberService`. This method accepts an instance of the `MemberId` class, which identifies the `Member` to retrieve. It returns the instance of the `Member` class corresponding to that identifier.



If the requested `Member` cannot be found, a `MemberDoesNotExistException` is thrown.

In the above example, the request to retrieve a member is invoked synchronously. An example of retrieving a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of members, which were previously added through the platform, use the `Get(Criteria)` method. This method accepts an instance of `Criteria`, which contains the specifications to retrieve desired `Members`.

The `Filter` property of the `Criteria` class accepts an instance of the `MemberFilter` class. This class contains the specifications that let you refine the result set of Members you want to retrieve. The properties of the `MemberFilter` class include:

  • `Group` – Assigning a value (`GroupId`) to this property refines a result set to Members of the identified group.

  • `MemberIds` – Assigning a value (`IEnumerable`) to this property refines a result set to Members identified in the collection.

  • `Role` – Assigning a value (`RoleId`) to this property refines a result set to Members that have been assigned the identified role.

  • `User` – Assigning a value (`Reference`) to this property refines a result set to Members associated with the identified user.

The specifications of the `MemberFilter` may be applied in conjunction with one another. Each specification, which is assigned a value in the filter, further refines the result set (that is, a logical AND).

The example below demonstrates the retrieval of a result page of `Members` assigned to a group.



In the above examples, the request to retrieve members is invoked synchronously. An example of retrieving members asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The `MemberSortFields` class exposes a set of fields upon which a result set of members may be ordered. You can apply these fields to construct sorting rules that you associate with your criteria. These fields include:

  • `MemberSortFields.Group`

  • `MemberSortFields.Id`

  • `MemberSortFields.User`

The example below demonstrates how to apply sorting rules to order your result set by group ID, in ascending order.



For details on the use of criteria, including information on paging and sorting, see _Criteria_ in [Discovering the platform](🔗).

## Extend members with composites

A `Member` is simply a relationship between a user and a group. You may need to associate additional information with members to further describe and shape them. Continuing an earlier example, where a group represents an athletic team, a member may represent a player on the team. You might want to capture information identifying the player's uniform number or primary position.

Just as you can extend a `Group` with data of your design, a `Member` may also be extended by creating a Composite. For an introduction to Composites, see _Composites_ in [Discovering the platform](🔗).

This section explains, both, the synchronous and asynchronous APIs of the member service that provide support for extending members with composites.

### Add a composite member

To save a Composite Member that you defined, use the `Add<TExtension>(Member, TExtension)` method of the `IMemberService`. This method accepts an instance of the `Member` class and an instance of `TExtension`. It returns a new instance of `Composite<Member,TExtension>`.

Consider the following class, which represents a sample of extension data:



In the example below, a `Member` is composed with an instance of this extension class:



In the above example, the request to add a member is invoked synchronously. An example of adding a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update a composite member

To update a specific instance of a Composite Member, which was previously added through the platform, use the `Update<TExtension>(MemberId, TExtension)` method of the `IMemberService`. This method accepts an instance of the `MemberId` class and an instance of `TExtension`. It returns a new instance of `Composite<Member,TExtension>`.

Consider the following class, which represents a sample of extension data:



For this example the below `IMemberService` has be properly implemented



In the above example, the request to update a member is invoked synchronously. An example of updating a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve a composite member

To retrieve a specific instance of a Composite Member, which was previously added through the platform, use the `Get<TExtension>(MemberId)` method. This method accepts an instance of the `MemberId` class, which identifies the `Member` to retrieve. It returns the instance of the `Composite<Member,TExtension>` class corresponding to that identifier.



If a Composite Member with the specified ID and extension type cannot be found, a `MemberDoesNotExistException` is thrown.

In the above example, the request to retrieve a member is invoked synchronously. An example of retrieving a member asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of Composite Members, which were previously added through the platform, use the `Get<TExtension>(CompositeCriteria<MemberFilter,TExtension>)` method. This method accepts an instance of `CompositeCriteria[MemberFilter,TExtension]`, which contains the specifications necessary to retrieve the desired Members.

The `Filter` property of the `CompositeCriteria<MemberFilter,TExtension>` class accepts an instance of the `MemberFilter` class. This class contains the specifications that let you refine the result set of `Members` that you want to retrieve.

The `ExtensionFilter` property of the `CompositeCriteria<MemberFilter,TExtension>` class accepts a `FilterExpression` that lets you specify a Boolean expression to further refine the result set by values represented within your extension data. (For more information on this type of filter, see _Composite Criteria_ and _Filtering Composites_ in [Discovering the platform](🔗).

Consider the following class, which represents a sample of extension data:



In the example below, a page of Members composed with Player is retrieved, where the players have a position of "Shortstop":



In the above example, the request to retrieve members is invoked synchronously. An example of retrieving members asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The fields of your extension data may also be applied when sorting your result set. The example below demonstrates the use of an extension data field in the definition of a sorting rule.



For details about the use of criteria, including information on paging and sorting, see _Criteria_ in [Discover the platform](🔗).