Getting Started

Follow these steps to begin using dii.storage with dii.storage.cosmos in your .NET applications.

Dependencies

net5.0

• For use with .NET 5, use up to v1.2.0:
  • MessagePack (>= 2.3.85)
  • Microsoft.Azure.Cosmos (>= 3.27.2)

net6.0

• For use with .NET 6, use latest.
  • MessagePack (>= 2.4.35)
  • Newtonsoft.Json (>= 13.0.1)
  • Microsoft.Azure.Cosmos (>= 3.27.2)

Configuring Your Application

Add a section to your appSettings files that define the startup settings for dii.storage.cosmos.

Example appSettings.{env}.json Section

    {
      ...
      
      "Storage": {
        "Cosmos": {
          "Uri": "database-uri",
          "Key": "database-key",
          "DatabaseId": "my-database-name",
          "AutoCreate": true,
          "MaxRUPerSecond": 4000,
          "AutoAdjustMaxRUPerSecond": false,
          "AutoScaling": true
        }
      }
      
      ...
    }

The application should initialize the Optimizer and DiiCosmosContext when registering other services. Both the Optimizer and DiiCosmosContext are built as singletons and do not need to be registered with the dependency injection mechanism in .NET. dii.storage.cosmos also comes packaged with a concrete class that implements the INoSqlDatabaseConfig interface that matches the example appSettings configuration shown above.

Example Startup.cs ConfigureServices() Code

    public class Startup
    {
    	private IConfiguration _configuration { get; }
    	
    	...
    	
    	public void ConfigureServices(IServiceCollection services)
    	{
    		// Register the configuration from your appSettings.{env}.json file.
    		INoSqlDatabaseConfig dbConfig = new CosmosDatabaseConfig();
    		_configuration.GetSection("Storage:Cosmos").Bind(dbConfig);
    
    		// Initialize the DiiCosmosContext with the configuration.
    		var context = DiiCosmosContext.Init(dbConfig);
    
    		// Ensure the database exists. Make sure to wait for the result.
    		var dbExistsTask = context.DoesDatabaseExistAsync();
    		dbExistsTask.Wait();
    
    		//// If run from an async method, this is preferable:
    		//var dbExistsTask = await context.DoesDatabaseExistAsync().ConfigureAwait(false);
    
    		// Usually an exception is desired if the database does not exist and cannot be created.
    		if (!dbExistsTask.Result)
    		{
    			throw new ApplicationException("CosmosDB database does not exist and failed to be created.");
    		}
    
    		// Initialize the Optimizer. With this overload, true means the Optimizer will attempt
    		// to find all entities that implement the IDiiEntity interface and initalize them. An
    		// exception will be thrown if any of the entities fail to initialize. This exception 
    		// can be disabled with changing the second boolean input to true, however this is not
    		// recommended.
    		var optimizer = Optimizer.Init(true, false);
    
    		// Initialize the tables within the DiiCosmosContext. Depending on your configuration,
    		// this may attempt to create any containers that do not exist at startup.
    		context.InitTablesAsync(optimizer.Tables).Wait();
    
    		//// If run from an async method, this is preferable:
    		//await context.InitTablesAsync(optimizer.Tables).ConfigureAwait(false);
    	}
    	
    	...
    }

That's it! The Optimizer and DiiCosmosContext can now be used throughout your application by simply calling their Get() method.

Example Optimizer.Get() Code

var optimizer = Optimizer.Get();

Example DiiCosmosContext.Get() Code

var diiCosmosContext = DiiCosmosContext.Get();

Adapter Usage

The DiiCosmosAdapter usage is best demonstrated in the dii.storage.cosmos.examples project.

DiiCosmosAdapter is built as a generic abstract class that accepts a type that implements the IDiiEntity interface. Under the hood, the DiiCosmosAdapter provides the necessary (but also bare bones) usage of the Optimizer and DiiCosmosContext to perform common CosmosDB operations. If you choose to use the DiiCosmosAdapter, all Optimizer usage in regard to storing data in (and retrieving from) CosmosDB is handled for you.