Halforbit Document Stores

   

Document Stores lets you easily create queryable stores with strongly-typed keying over document databases like CosmosDb, without the need for high-ceremony repository patterns or bare-metal integrations.

Features

• Queryable: Document stores let you use IQueryable or SQL language to query for strongly- or dynamically-typed documents.

• Easy Strongly-Typed Keying: Define partition keys and document IDs as properties using simple lambda expressions.

• No Repository Pattern Needed: Ditch the hand-made, error-prone, high-ceremony repository implementations.

Getting Started

1. Install NuGet Packages: Install the NuGet packages for your desired storage providers and formats:

   Install-Package Halforbit.DocumentStores.CosmosDb

   See the NuGet Packages section below for a list of available NuGet packages and what storage providers and formats they support.

2. Define Your Stores: Use the DocumentStore type to create ad-hoc stores, or define them as properties on a data context.

3. Use Your Stores: Persist, retrieve, and query data with your stores.

A store can be defined as a property of a data context, or created ad-hoc and stored in a local variable.

Example Usage

What do you want to store?

To create a document store, first decide on your document type. This can be any JSON-friendly class, record, or JObject. Let's make a record to track a person:

public record Person(
    Guid PersonId,
    string FirstName,
    string LastName);

Our document type has a Guid key property named PersonId. Key properties can be simple value types like Guid, int, and string.

For more information on keying, see Keying with Halforbit Document Stores.

Build a Document Store

Use the fluent builder to describe and create your document stores:

IDocumentStore<Guid, Person> store = DocumentStore
    .Describe()
    .CosmosDb()
    .ConnectionString("<connection-string-here>")
    .Database("test-database")
    .Container("test-container")
    .Document<Person>()
    .Key(d => d.PersonId)
    .Build();

If your database or container do not exist, you can use your store to create them:

await store.CreateStoreIfNotExistsAsync();

Put a document in a store

Let's create a Person and put it in our document store:

var person = new Person(
    PersonId: Guid.NewGuid(),
    FirstName: "Steve",
    LastName: "Smith");

await store.UpsertAsync(person);

Get a document from a store

You can get a document with its key:

var person = await store.GetAsync(personId);

Query the documents in a store

You can use LINQ IQueryable or raw SQL to query your store with the QueryAsync methods. The results are given to you as an IAsyncEnumerable<>.

await foreach (var person in store.QueryAsync(q => q
    .Where(p => p.LastName == "Smith")))
{
    // do something with person here.
}

Delete a document from a store

You can delete a document with its key:

await store.DeleteAsync(personId);

NuGet Packages

The following NuGet packages are provided, parted out by their dependencies. Install the ones that contain the storage providers and formats you wish to use.

Storage Provider or Format	NuGet Package
(Base Library)	Halforbit.DocumentStores
Azure CosmosDb	Halforbit.DocumentStores.CosmosDb

License

Data Stores is licensed under the MIT License. See the LICENSE file for details.