IReadOnlyRepository<TItem>

This is the read-only repository interface for any implementation of

Namespace: Microsoft.Azure.CosmosRepository
Kind: interface

This is the read-only repository interface for any implementation of TItem, exposing asynchronous read functionality.

public interface IReadOnlyRepository<TItem> where TItem : IItem

Type parameters

Name	Description
`TItem`	The `IItem` implementation class type.

Example

With DI, use .ctor injection to require any implementation of IItem:

public class ConsumingService
{
    readonly IReadOnlyRepository<SomePoco> _pocoRepository;

    public ConsumingService(
        IReadOnlyRepository<SomePoco> pocoRepository) =>
        _pocoRepository = pocoRepository;
}

Members

Methods

IReadOnlyRepository<TItem>.TryGetAsync(string, string?, CancellationToken)

Attempts to get an IItem that corresponds to the given id.

ValueTask<TItem?> TryGetAsync(string id, string? partitionKeyValue = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`id`	`String`	The string identifier.
`partitionKeyValue`	`String`	The partition key value if different than the `Id`.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — ValueTask{{TItem}}

This implementation handles the case in which a CosmosException with the status code of 404. It will return null when this exception is thrown.

IReadOnlyRepository<TItem>.GetAsync(string, string?, CancellationToken)

Gets the IItem implementation class instance as a TItem that corresponds to the given id.

ValueTask<TItem> GetAsync(string id, string? partitionKeyValue = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`id`	`String`	The string identifier.
`partitionKeyValue`	`String`	The partition key value if different than the `Id`.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — ValueTask{{TItem}}: A ValueTask representing the IItem implementation class instance as a TItem.

If the typeof(TItem).Name differs from the item.Type you’re attempting to retrieve, null is returned.

IReadOnlyRepository<TItem>.GetAsync(string, PartitionKey, CancellationToken)

Gets the IItem implementation class instance as a TItem that corresponds to the given id.

ValueTask<TItem> GetAsync(string id, PartitionKey partitionKey, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`id`	`String`	The string identifier.
`partitionKey`	`PartitionKey`	The `PartitionKey` value if different than the `Id`.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — ValueTask{{TItem}}: A ValueTask representing the IItem implementation class instance as a TItem.

If the typeof(TItem).Name differs from the item.Type you’re attempting to retrieve, null is returned.

IReadOnlyRepository<TItem>.GetAsync(Expression<Func<TItem, bool>>, CancellationToken)

Gets an IEnumerable collection of IItem implementation classes that match the given predicate.

ValueTask<IEnumerable<TItem>> GetAsync(Expression<Func<TItem, bool>> predicate, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	The expression used for evaluating a matching item.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — IEnumerable{{TItem}}}: A collection of item instances who meet the predicate condition.

If the typeof(TItem).Name differs from the item.Type you’re attempting to retrieve, the item is not returned.

IReadOnlyRepository<TItem>.GetByQueryAsync(string, CancellationToken)

Gets an IEnumerable collection of IItem by the given Cosmos SQL query

ValueTask<IEnumerable<TItem>> GetByQueryAsync(string query, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`query`	`String`	The Cosmos SQL query
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — IEnumerable{{TItem}}}: A collection of item instances returned by the given query Cosmos SQL query.

IReadOnlyRepository<TItem>.GetByQueryAsync(QueryDefinition, CancellationToken)

Gets an IEnumerable collection of IItem by the given Cosmos QueryDefinition

ValueTask<IEnumerable<TItem>> GetByQueryAsync(QueryDefinition queryDefinition, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`queryDefinition`	`QueryDefinition`	—
`cancellationToken`	`CancellationToken`	—

Returns — IEnumerable{{TItem}}}: A collection of item instances returned by the given queryDefinition Cosmos SQL query.

IReadOnlyRepository<TItem>.ExistsAsync(string, string?, CancellationToken)

Queries cosmos DB to see if an item exists.

ValueTask<bool> ExistsAsync(string id, string? partitionKeyValue = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`id`	`String`	The string identifier.
`partitionKeyValue`	`String`	The partition key value if different than the `Id`.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — Boolean}: A ValueTask representing the asynchronous exists operation.

This method performs a point read to decide whether or not an item exists.

IReadOnlyRepository<TItem>.ExistsAsync(string, PartitionKey, CancellationToken)

Queries cosmos DB to see if an item exists.

ValueTask<bool> ExistsAsync(string id, PartitionKey partitionKey, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`id`	`String`	The string identifier.
`partitionKey`	`PartitionKey`	The `PartitionKey` value if different than the `Id`.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — Boolean}: A ValueTask representing the asynchronous exists operation.

This method performs a point read to decide whether or not an item exists.

IReadOnlyRepository<TItem>.ExistsAsync(Expression<Func<TItem, bool>>, CancellationToken)

Queries cosmos DB to see if an item exists.

ValueTask<bool> ExistsAsync(Expression<Func<TItem, bool>> predicate, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	The expression used for evaluating any matching items.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — Boolean}: A ValueTask representing the asynchronous exists operation.

This checks the count of the resulting query any count greater than 1 will return true.

IReadOnlyRepository<TItem>.CountAsync(CancellationToken)

Queries cosmos DB to obtain the count of items.

ValueTask<int> CountAsync(CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — Int32}: A ValueTask representing the asynchronous count operation.

This queries the total number of documents in the container.

IReadOnlyRepository<TItem>.CountAsync(Expression<Func<TItem, bool>>, CancellationToken)

Queries cosmos DB to obtain the count of items.

ValueTask<int> CountAsync(Expression<Func<TItem, bool>> predicate, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	The expression used for evaluating any matching items.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — Int32}: A ValueTask representing the asynchronous count operation.

This queries the total number of documents in the container as filtered by the provided predicate.

IReadOnlyRepository<TItem>.PageAsync(Expression<Func<TItem, bool>>?, int, string?, bool, CancellationToken)

Offers a load more paging implementation for infinite scroll scenarios. Allows for efficient paging making use of cosmos DBs continuation tokens, making this implementation cost effective.

ValueTask<IPage<TItem>> PageAsync(Expression<Func<TItem, bool>>? predicate = null, int pageSize = 25, string? continuationToken = null, bool returnTotal = false, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	A filter criteria for the paging operation, if null it will get all `IItem`s
`pageSize`	`Int32`	The size of the page to return from cosmos db.
`continuationToken`	`String`	The token returned from a previous query, if null starts at the beginning of the data
`returnTotal`	`Boolean`	Specifies whether or not to return the total number of items that matched the query. This defaults to false as it can be a very expensive operation.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — IPage{{TItem}}}: An IPage of IItems

This method makes use of cosmos dbs continuation tokens for efficient, cost effective paging utilising low RUs

IReadOnlyRepository<TItem>.QueryAsync<TResult>(ISpecification<TItem, TResult>, CancellationToken)

Get items based on a specification. The specification is used to define which filters are used, the order of the search results and how they are paged. Depending on how results are paged derive specification implementations from different classes: For non paged results derive DefaultSpecification For continuation token derive ContinuationTokenSpecification For page number results derive OffsetByPageNumberSpecification

ValueTask<TResult> QueryAsync<TResult>(ISpecification<TItem, TResult> specification, CancellationToken cancellationToken = default) where TResult : IQueryResult<TItem>

Parameters

Name	Type	Description
`specification`	`ISpecification{{TItem},{TResult}}`	A specification used to filtering, ordering and paging. A `ISpecification`
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — ValueTask{{TResult}}: The selected TResult implementation that implements IQueryResult of IItem

This method makes use of cosmos dbs continuation tokens for efficient, cost effective paging utilising low RUs

IReadOnlyRepository<TItem>.PageAsync(Expression<Func<TItem, bool>>?, int, int, bool, CancellationToken)

Offers a load more paging implementation for infinite scroll scenarios. Allows for efficient paging making use of cosmos DBs continuation tokens, making this implementation cost effective.

ValueTask<IPageQueryResult<TItem>> PageAsync(Expression<Func<TItem, bool>>? predicate = null, int pageNumber = 1, int pageSize = 25, bool returnTotal = false, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	A filter criteria for the paging operation, if null it will get all `IItem`s
`pageNumber`	`Int32`	The page number to return from cosmos db.
`pageSize`	`Int32`	The size of the page to return from cosmos db.
`returnTotal`	`Boolean`	Specifies whether or not to return the total number of items that matched the query. This defaults to false as it can be a very expensive operation.
`cancellationToken`	`CancellationToken`	The cancellation token to use when making asynchronous operations.

Returns — IPageQueryResult{{TItem}}}: An IPageQueryResult of IItems

This method makes use of Cosmos DB’s continuation tokens for efficient, cost effective paging utilizing low RUs

IReadOnlyRepository<TItem>.PageAsync(Expression<Func<TItem, bool>>?, int, int, CancellationToken)

Wraps the existing paging support to return an IAsyncEnumerable where T is TItem.

IAsyncEnumerable<TItem> PageAsync(Expression<Func<TItem, bool>>? predicate = null, int limit = 1000, int pageSize = 25, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`predicate`	`Boolean}}`	A filter criteria for the paging operation, if null it will get all `IItem`s
`limit`	`Int32`	The limit of how many items to yield. Defaults to `1,000`.
`pageSize`	`Int32`	The size of the page to return from cosmos db.
`cancellationToken`	`CancellationToken`	The optional `CancellationToken` used to

Returns — IAsyncEnumerable{{TItem}}: An IAsyncEnumerable where T is TItem.

This method makes use of Cosmos DB’s continuation tokens for efficient, cost effective paging utilizing low RUs