Interface IRatingService

This interface exposes functionality to rate items, delete ratings, and retrieve user ratings and statistics.

Namespace: EPiServer.Social.Ratings.Core

Assembly: EPiServer.Social.Ratings.Core.dll

Version: 1.5.4

Syntax

public interface IRatingService

Methods

Add(Rating)

Adds a new rating for a referenced item and user.

Declaration

Rating Add(Rating rating)

Parameters

Type	Name	Description
Rating	rating	Rating to add.

Returns

Type	Description
Rating	The added rating.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
DuplicateRatingException	Thrown then rating for target resource by user already exists.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Add<TExtension>(Rating, TExtension)

Adds a new rating with supporting extension metadata for a referenced item and user.

Declaration

Composite<Rating, TExtension> Add<TExtension>(Rating rating, TExtension extension)
    where TExtension : class

Parameters

Type	Name	Description
Rating	rating	Rating to be added.
TExtension	extension	Extended data supporting the rating

Returns

Type	Description
Composite<Rating, TExtension>	A rating composed with the specified extension data

Type Parameters

Name	Description
TExtension	Type of data applied as an extension of the rating

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
DuplicateRatingException	Thrown then rating for target resource by user already exists.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

AddAsync(Rating)

Asynchronously adds a new rating for a referenced item and user.

Declaration

Task<Rating> AddAsync(Rating rating)

Parameters

Type	Name	Description
Rating	rating	Rating to add.

Returns

Type	Description
System.Threading.Tasks.Task<Rating>	The added rating.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
DuplicateRatingException	Thrown then rating for target resource by user already exists.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

AddAsync<TExtension>(Rating, TExtension)

Asynchronously adds a new rating with supporting extension metadata for a referenced item and user.

Declaration

Task<Composite<Rating, TExtension>> AddAsync<TExtension>(Rating rating, TExtension extension)
    where TExtension : class

Parameters

Type	Name	Description
Rating	rating	Rating to be added.
TExtension	extension	Extended data supporting the rating

Returns

Type	Description
System.Threading.Tasks.Task<Composite<Rating, TExtension>>	A rating composed with the specified extension data

Type Parameters

Name	Description
TExtension	Type of data applied as an extension of the rating

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
DuplicateRatingException	Thrown then rating for target resource by user already exists.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Get(Criteria<RatingFilter>)

Gets a page of existing ratings filtered by the criteria, if any are specified.

Declaration

ResultPage<Rating> Get(Criteria<RatingFilter> criteria)

Parameters

Type	Name	Description
Criteria<RatingFilter>	criteria	The criteria for retrieving ratings.

Returns

Type	Description
ResultPage<Rating>	Page of ratings filtered according to the specified criteria

Remarks

Filtering using criteria works as described below: a. To retrieve a user rating for a target resource, specify both, Target and Rater in criteria. b. To retrieve all ratings by a user, specify Rater in criteria. c. To retrieve all ratings by a target target resource, specify Target in criteria. d. To retrieve all ratings in the datastore, specify neither Target nor Rater in criteria. Note: In all cases above PageInfo is optional unless you want to retrieve a specific page of ratings.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Get(Criteria<RatingStatisticsFilter>)

Gets a page of existing rating statistics filtered by the criteria, if any are specified.

Declaration

[Obsolete("This API is deprecated. Please use: RatingStatisticsService:Get(Criteria<RatingStatisticsFilter> criteria)")]
ResultPage<RatingStatistics> Get(Criteria<RatingStatisticsFilter> criteria)

Parameters

Type	Name	Description
Criteria<RatingStatisticsFilter>	criteria	The criteria for retrieving rating statistics.

Returns

Type	Description
ResultPage<RatingStatistics>	Page of rating statistics filtered according to the specified criteria

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Get(RatingId)

Get an existing rating by its identifier.

Declaration

Rating Get(RatingId id)

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to get.

Returns

Type	Description
Rating	The rating.

Exceptions

Type	Condition
System.ArgumentException	Thrown when the rating passed in is null or empty.
RatingDoesNotExistException	Thrown when the identified rating does not exist.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Get<TExtension>(CompositeCriteria<RatingFilter, TExtension>)

Retrieves a page of ratings from the underlying data store, as described by the specified criteria. The ratings are filtered by the type of their associated data.

Declaration

ResultPage<Composite<Rating, TExtension>> Get<TExtension>(CompositeCriteria<RatingFilter, TExtension> criteria)
    where TExtension : class

Parameters

Type	Name	Description
CompositeCriteria<RatingFilter, TExtension>	criteria	Criteria by which to filter ratings

Returns

Type	Description
ResultPage<Composite<Rating, TExtension>>	Page of composite ratings

Type Parameters

Name	Description
TExtension	Type of data associated with the desired ratings

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Get<TExtension>(RatingId)

Gets a rating with extension data by its rating identifier.

Declaration

Composite<Rating, TExtension> Get<TExtension>(RatingId id)
    where TExtension : class

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to get.

Returns

Type	Description
Composite<Rating, TExtension>	The composite rating.

Type Parameters

Name	Description
TExtension	Type of data associated with the desired ratings

Exceptions

Type	Condition
System.ArgumentException	Thrown when invalid data passed for id.
RatingDoesNotExistException	Thrown when the identified rating does not exist.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

GetAsync(Criteria<RatingFilter>)

Asynchronously gets a page of existing ratings filtered by the criteria, if any are specified.

Declaration

Task<ResultPage<Rating>> GetAsync(Criteria<RatingFilter> criteria)

Parameters

Type	Name	Description
Criteria<RatingFilter>	criteria	The criteria for retrieving ratings.

Returns

Type	Description
System.Threading.Tasks.Task<ResultPage<Rating>>	Page of ratings filtered according to the specified criteria

Remarks

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

GetAsync(Criteria<RatingStatisticsFilter>)

Asynchronously gets a page of existing rating statistics filtered by the criteria, if any are specified.

Declaration

[Obsolete("This API is deprecated. Please use: RatingStatisticsService:GetAsync(Criteria<RatingStatisticsFilter> criteria)")]
Task<ResultPage<RatingStatistics>> GetAsync(Criteria<RatingStatisticsFilter> criteria)

Parameters

Type	Name	Description
Criteria<RatingStatisticsFilter>	criteria	The criteria for retrieving rating statistics.

Returns

Type	Description
System.Threading.Tasks.Task<ResultPage<RatingStatistics>>	Page of rating statistics filtered according to the specified criteria

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

GetAsync(RatingId)

Asynchronously get an existing rating by its identifier.

Declaration

Task<Rating> GetAsync(RatingId id)

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to get.

Returns

Type	Description
System.Threading.Tasks.Task<Rating>	The rating.

Exceptions

Type	Condition
System.ArgumentException	Thrown when the rating passed in is null or empty.
RatingDoesNotExistException	Thrown when the identified rating does not exist.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

GetAsync<TExtension>(CompositeCriteria<RatingFilter, TExtension>)

Asynchronously retrieves a page of ratings from the underlying data store, as described by the specified criteria. The ratings are filtered by the type of their associated data.

Declaration

Task<ResultPage<Composite<Rating, TExtension>>> GetAsync<TExtension>(CompositeCriteria<RatingFilter, TExtension> criteria)
    where TExtension : class

Parameters

Type	Name	Description
CompositeCriteria<RatingFilter, TExtension>	criteria	Criteria by which to filter ratings

Returns

Type	Description
System.Threading.Tasks.Task<ResultPage<Composite<Rating, TExtension>>>	Page of composite ratings

Type Parameters

Name	Description
TExtension	Type of data associated with the desired ratings

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when null passed for criteria.
InvalidPageInfoException	Thrown when the page info is invalid such as using a negative value for PageOffset or PageSize or using a PageSize that exceeds 1000.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

GetAsync<TExtension>(RatingId)

Asynchronously gets a rating with extension data by its rating identifier.

Declaration

Task<Composite<Rating, TExtension>> GetAsync<TExtension>(RatingId id)
    where TExtension : class

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to get.

Returns

Type	Description
System.Threading.Tasks.Task<Composite<Rating, TExtension>>	The composite rating.

Type Parameters

Name	Description
TExtension	Type of data associated with the desired ratings

Exceptions

Type	Condition
System.ArgumentException	Thrown when invalid data passed for id.
RatingDoesNotExistException	Thrown when the identified rating does not exist.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Remove(RatingId)

Removes an existing rating by entity Id.

Declaration

void Remove(RatingId id)

Parameters

Type	Name	Description
RatingId	id	RatingId to delete.

Exceptions

Type	Condition
System.ArgumentException	Thrown when the rating passed in is null or empty.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

RemoveAsync(RatingId)

Asynchronously removes an existing rating by entity Id.

Declaration

Task RemoveAsync(RatingId id)

Parameters

Type	Name	Description
RatingId	id	RatingId to delete.

Returns

Type	Description
System.Threading.Tasks.Task

Exceptions

Type	Condition
System.ArgumentException	Thrown when the rating passed in is null or empty.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Update(RatingId, RatingValue, RatingValue)

Updates the rating value of an existing rating.

Declaration

Rating Update(RatingId id, RatingValue currentValue, RatingValue newValue)

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to update.
RatingValue	currentValue	The current value of the identified rating. This value is used to ensure consistency in statistical calculations.
RatingValue	newValue	The new rating value to set in the rating.

Returns

Type	Description
Rating	The updated rating.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
RatingDoesNotExistException	Thrown when rating for the identified rating could not be found or its value was updated in another context and is no longer consistent with the specified parameters.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

Update<TExtension>(RatingId, RatingValue, RatingValue, TExtension)

Updates the rating value of an existing rating with supporting extension metadata.

Declaration

Composite<Rating, TExtension> Update<TExtension>(RatingId id, RatingValue currentValue, RatingValue newValue, TExtension extension)
    where TExtension : class

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to update.
RatingValue	currentValue	The current value of the identified rating. This value is used to ensure consistency in statistical calculations.
RatingValue	newValue	The new rating value to set in the rating.
TExtension	extension	Extended data supporting the rating

Returns

Type	Description
Composite<Rating, TExtension>	An rating composed with the specified extension data

Type Parameters

Name	Description
TExtension	Type of data applied as an extension of the rating

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
RatingDoesNotExistException	Thrown when rating for the identified rating could not be found or its value was updated in another context and is no longer consistent with the specified parameters.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

UpdateAsync(RatingId, RatingValue, RatingValue)

Asynchronously updates the rating value of an existing rating.

Declaration

Task<Rating> UpdateAsync(RatingId id, RatingValue currentValue, RatingValue newValue)

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to update.
RatingValue	currentValue	The current value of the identified rating. This value is used to ensure consistency in statistical calculations.
RatingValue	newValue	The new rating value to set in the rating.

Returns

Type	Description
System.Threading.Tasks.Task<Rating>	The updated rating.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
RatingDoesNotExistException	Thrown when rating for the identified rating could not be found or its value was updated in another context and is no longer consistent with the specified parameters.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.

UpdateAsync<TExtension>(RatingId, RatingValue, RatingValue, TExtension)

Asynchronously updates the rating value of an existing rating with supporting extension metadata.

Declaration

Task<Composite<Rating, TExtension>> UpdateAsync<TExtension>(RatingId id, RatingValue currentValue, RatingValue newValue, TExtension extension)
    where TExtension : class

Parameters

Type	Name	Description
RatingId	id	Identifier of the rating to update.
RatingValue	currentValue	The current value of the identified rating. This value is used to ensure consistency in statistical calculations.
RatingValue	newValue	The new rating value to set in the rating.
TExtension	extension	Extended data supporting the rating

Returns

Type	Description
System.Threading.Tasks.Task<Composite<Rating, TExtension>>	An rating composed with the specified extension data

Type Parameters

Name	Description
TExtension	Type of data applied as an extension of the rating

Exceptions

Type	Condition
System.ArgumentNullException	Thrown when any of the parameters passed in are null.
System.ArgumentException	Thrown when any of the parameters passed in are invalid.
RatingDoesNotExistException	Thrown when rating for the identified rating could not be found or its value was updated in another context and is no longer consistent with the specified parameters.
SocialException	Thrown when an error occurs while processing the request.
SocialAuthenticationException	Thrown when an authentication error occurs while processing the request.
MaximumDataSizeExceededException	Thrown when a Social object is submitted, which exceeds the size restrictions of the system.
SocialCommunicationException	Thrown when errors occur communicating with the cloud services.