SDDev.Net.GenericRepository 10.0.0

SDDev.Net Generic Repository for Azure Cosmos DB

The SDDev.Net.GenericRepository package implements the repository pattern on top of Azure Cosmos DB. It allows you to model your data as Plain Old C# Objects (POCOs) while the library handles container access, partition routing, query construction, and cross-cutting features such as caching, indexing, and patch updates. The goal is to make the common 90% of Cosmos DB development frictionless while still giving you escape hatches (for example, direct access to the Container client) for the remaining scenarios.

Prerequisite: The repository targets .NET 9. Install the .NET 9 SDK before building the solution or referencing the package.

The repository project ships together with a contracts package that contains base entity abstractions and search helpers. This repository hosts both packages, a test suite, and an example application that demonstrate how to use the tooling end-to-end.

Key capabilities

• POCO-first data access – inherit from BaseStorableEntity or BaseAuditableEntity and interact with your models directly.
• Flexible querying – build strongly-typed queries with LINQ expressions or dynamic queries through System.Linq.Dynamic.Core.
• Pagination support – use SearchModel to request page sizes, continuation tokens, offsets, and sorting information.
• Logical and physical deletes – toggle between setting a TTL for soft deletes or forcing an immediate removal.
• Patch support – issue partial updates using CosmosPatchOperationCollection without replacing entire documents.
• Caching decorator – wrap repositories with CachedRepository<T> to reduce hot reads.
• Hierarchical partition support – target containers with composite partition keys through HierarchicalPartitionedRepository<T>.
• Indexing helpers – integrate with Azure Cognitive Search using the indexing abstractions when needed.

Packages

Add the following packages to your application (both target .NET 9):

 dotnet add package SDDev.Net.GenericRepository
 dotnet add package SDDev.Net.GenericRepository.Contracts

SDDev.Net.GenericRepository already references the contracts package. Adding the contracts package explicitly is helpful when you want to compile shared models in a separate project.

Configuration

1. Bind Cosmos DB settings – add the configuration section to appsettings.json:

"CosmosDb": {
  "Uri": "https://<your-account>.documents.azure.com:443/",
  "AuthKey": "<your-key>",
  "DefaultDatabaseName": "AppDatabase",
  "DeleteTTL": 3600,
  "IncludeTotalResultsByDefault": true,
  "PopulateIndexMetrics": false
}

2. Register dependencies – configure the Cosmos client, repository options, and repositories in Program.cs or your DI setup:

builder.Services.Configure<CosmosDbConfiguration>(
    builder.Configuration.GetSection("CosmosDb"));

builder.Services.AddSingleton(sp =>
{
    var settings = sp.GetRequiredService<IOptions<CosmosDbConfiguration>>().Value;
    var cosmosClientOptions = new CosmosClientOptions
    {
        AllowBulkExecution = settings.EnableBulkQuerying
    };

    return new CosmosClient(settings.Uri, settings.AuthKey, cosmosClientOptions);
});

builder.Services.AddScoped<IRepository<MyEntity>, GenericRepository<MyEntity>>();
// Optional decorators
builder.Services.Decorate<IRepository<MyEntity>, CachedRepository<MyEntity>>();

You can override the default database name, container name, or partition key by providing values to the repository constructor when registering the dependency.

Modeling entities

using System.Collections.Generic;

public class MyEntity : BaseAuditableEntity
{
    public string CustomerId { get; set; }
    public string DisplayName { get; set; }
    public List<string> Tags { get; set; } = new();
    public override string PartitionKey => CustomerId;
}

• BaseStorableEntity provides Id, IsActive, ItemType, PartitionKey, and a TTL field.
• BaseAuditableEntity extends BaseStorableEntity and automatically manages CreatedDateTime/ModifiedDateTime metadata.
• Override PartitionKey to supply the value stored in Cosmos DB when your partition key differs from the type name.

Working with repositories

Below is an end-to-end example inside an application service. Every method is asynchronous and can be awaited from ASP.NET Core minimal APIs, controllers, or background services.

public class MyService
{
    private readonly IRepository<MyEntity> _repository;

    public MyService(IRepository<MyEntity> repository)
    {
        _repository = repository;
    }

    public async Task<Guid> CreateAsync(MyEntity entity)
    {
        return await _repository.Create(entity);
    }

    public async Task<MyEntity> GetAsync(Guid id, string partitionKey)
    {
        return await _repository.Get(id, partitionKey);
    }

    public async Task<IReadOnlyCollection<MyEntity>> SearchAsync(string customerId)
    {
        var search = new SearchModel
        {
            PageSize = 20,
            PartitionKey = customerId,
            SortByField = nameof(MyEntity.DisplayName),
            SortAscending = true
        };

        var result = await _repository.Get(x => x.CustomerId == customerId, search);
        return result.Results.ToList();
    }

    public async Task UpdateAsync(MyEntity entity)
    {
        await _repository.Update(entity);
    }

    public async Task<Guid> UpsertAsync(MyEntity entity)
    {
        return await _repository.Upsert(entity);
    }

    public async Task<int> CountAsync(string customerId)
    {
        return await _repository.Count(x => x.CustomerId == customerId, customerId);
    }

    public async Task DeleteAsync(Guid id, string partitionKey, bool force = false)
    {
        await _repository.Delete(id, partitionKey, force);
    }
}

Continuation tokens and paging

SearchModel.ContinuationToken accepts a base64 encoded token returned from a previous query. Set the token on subsequent requests to fetch the next page. You can also use Offset for small paged queries; Cosmos DB recommends continuation tokens for production workloads.

Dynamic queries

If you need to build queries at runtime, call Get(string query, ISearchModel model) and pass a dynamic LINQ expression:

var search = new SearchModel { PartitionKey = customerId, PageSize = 50 };
var response = await _repository.Get("DisplayName.StartsWith(\"A\")", search);

Logical vs. physical delete

• Delete(id, partitionKey, force: false) (the default) sets the entity TTL to the configured DeleteTTL. Cosmos DB removes the document automatically after the interval, giving you a soft delete window.
• Delete(id, partitionKey, force: true) immediately removes the document. Use this when you are certain you no longer need the data.

Patch updates

Use CosmosPatchOperationCollection to build partial updates. Audit metadata is updated automatically when targeting auditable entities.

using SDDev.Net.GenericRepository.CosmosDB.Patch.Cosmos;

var operations = new CosmosPatchOperationCollection<MyEntity>();
operations.Set(x => x.DisplayName, "Contoso (updated)");
operations.Add(x => x.Tags, "priority");

await _repository.Patch(entityId, partitionKey: customerId, operations);

Cached repositories

Wrap repositories with CachedRepository<T> to store point reads in IDistributedCache implementations such as Redis:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

builder.Services.AddScoped<IRepository<MyEntity>, GenericRepository<MyEntity>>();
builder.Services.Decorate<IRepository<MyEntity>, CachedRepository<MyEntity>>();

• Cache entries default to a 60 second sliding window.
• Call ICachedRepository<T>.Evict or Delete to remove cache entries explicitly when executing cross-entity operations.

Hierarchical partition keys

For containers that use composite partition keys, use IHierarchicalPartitionRepository<T> / HierarchicalPartitionedRepository<T> and pass the ordered key list:

builder.Services.AddScoped<IHierarchicalPartitionRepository<MyEntity>>(sp =>
    new HierarchicalPartitionedRepository<MyEntity>(
        sp.GetRequiredService<CosmosClient>(),
        sp.GetRequiredService<ILogger<HierarchicalPartitionedRepository<MyEntity>>>(),
        sp.GetRequiredService<IOptions<CosmosDbConfiguration>>(),
        new List<string> { "CustomerId", "Region" },
        collectionName: "MyEntities"));

var entity = await hierarchicalRepo.Get(id, new List<string> { customerId, region });

The repository handles translating the key list into a PartitionKey compatible with the Cosmos SDK.

Indexing integration

The IndexedRepository<T, TIndex> adds Azure Cognitive Search support on top of the base repository. When you decorate a repository with indexing, patch and CRUD operations synchronize content with your search index. Consult the indexing tests for practical examples and the following tips when wiring up the decorator:

• One-time setup – call Initialize(indexClientName, repository, options) (or SetRepository/SetIndexClientName) after construction so the decorator knows which IRepository<T> instance and Azure client registrations to use.
• Customize mapping – subscribe to the AfterMapping or AfterMappingAsync events to enrich the index model with data that is not stored in Cosmos DB.
• Manual index rebuilds – use CreateOrUpdateIndex() to deploy your schema and UpdateIndex(...) overloads to repopulate the index. The overload that accepts an id now supports an optional partitionKey parameter; omit it when your entity uses the default key.
• Parallel refresh – UpdateIndex(IList<T> entities, int maxDegreeOfParallelism = 1) lets you batch updates efficiently. Increase the degree of parallelism when reindexing larger datasets.
• Bring-your-own models – call Create(entity, indexModel) or Update(entity, indexModel) if you want to control the mapping step entirely.

var indexedRepository = serviceProvider.GetRequiredService<IIndexedRepository<MyEntity, MyEntityIndex>>();
indexedRepository.Initialize("SearchClient", innerRepository, new IndexRepositoryOptions
{
    IndexName = "my-entities",
    RemoveOnLogicalDelete = true
});

indexedRepository.AfterMapping += (indexModel, entity) =>
{
    indexModel.Region = ResolveRegion(entity.CustomerId);
};

await indexedRepository.UpdateIndex(id, partitionKey: null); // optional partition key parameter

Samples and reference material

• Example application: SDDev.Net.GenericRepository.Example – bootstrap project that you can expand to prototype your own usage.
• Integration tests: SDDev.Net.GenericRepository.Tests – comprehensive test suite covering query composition, patch operations, hierarchical partitioning, caching, and more. Specific files worth reviewing include:
  • GenericRepositoryTests.cs for CRUD, queries, deletes, and counts.
  • CachedRepositoryTests.cs for cache behavior.
  • PatchOperationCollectionTests.cs for patch examples.
  • HierarchicalPartitionRepositoryTests.cs for composite partition keys.
  • IndexedRepositoryTests.cs for search integration.

Feel free to copy these tests into your solution as living documentation—they demonstrate the majority of supported operations and edge cases.

Troubleshooting

• Cross-partition queries – the repository warns when a search spans multiple partitions. Provide SearchModel.PartitionKey whenever possible to avoid RU spikes.
• Index metrics – set CosmosDbConfiguration.PopulateIndexMetrics to true while tuning indexes. The repository logs Cosmos index metrics for the first page of results to aid diagnostics.
• Bulk workloads – enable CosmosDbConfiguration.EnableBulkQuerying to turn on the Cosmos SDK bulk executor, reducing throttling for high-volume operations.

Contributing

Issues and pull requests are welcome! Run the test suite from the repository root before submitting changes:

 dotnet test SDDev.Net.GenericRepository.sln

Happy coding!