7.0.0-preview1

TODO: add more complete releases notes ASAP!

Short version:

• This version includes the new Deferred Value Checks and Layer Caching API!
• Directory subspace API has changed (documentation is out of date!)
• Dropped support for .NET Standard 2.1 / .NET Core 3.1, replaced with .NET 5.0

6.2.0-preview1

Please do not use this release!

5.2.1-preview2

Changes

• Bumped from .NET 4.7.1 to 4.7.2, and from .NET Core 2.1 to 2.2. Still "supporting" .NET 4.6.1
• Max API bumped to API level 600 (by default)
• Reworked the Dynamic and Typed key subspaces so that all methods for generating ranges have proper names (ToRange(item1, item2, ...) vs PackRange(tuple)) (7636b1b)
• Added a lot of missing properties on the metrics exposed by status json to get in line with 5.x and 6.0 (c4c36d3)
• Added the IFdbDatabaseProvider and IFdbDatabaseScopeProvider to help use fdb with dependency injection framework (the norm for ASP.NET Core apps).
• Steamlined the Directory API exposed on database instances (#88)
• Completely removed the FdbDatabasePartition type that is not needed anymore (following the change in Directory API).
• Fixed clearrange command in FdbShell (a6a5d02)
• Updated and reworked FdbTop to expose all the new metrics from 5.x and 6.x
• Deprecated TLSPlugin and other TLS options since they are also deprecated in fdb 6.0

Changes in the Directory API

The FdbDatabasePartition type is gone, and now IFdbDatabase looks like this:

public interface IFdbDatabase
{
    // ...
    IFdbDirectory Directory { get; }
}

Code that has to use the Directory layer inside a retry-loop now looks like this:

var partition = new [] { "Tests", "ACME", Environment.MachineName };
this.Db = await Fdb.OpenAsync(new FdbConnectionOptions() { PartitionPath = partition }, ct);
await this.Db.ReadWriteAsync(async tr =>
{
	foreach(var dir in await this.Db.Directory.TryListAsync(tr))
	{
		await this.Db.Directory.RemoveAsync(tr, new [] { dir });
	}
}, ct);

Another change is that most Directory Layer overloads will expect a IEnumerable<string> anymore, but for a new struct called FdbDirectoryPath. This struct encapsulate the concept of 'path of a subdirectory', and has mutiple implicit and explicit cast from string, string arrays, and so on. This is the first step into being able to use types other than string for the folder names (int, guid, ...).

IFdbDatabaseScopeProvider

To be able to use FoundationDB with ASP.NET Core web site that make heavy use of dependency injection, we needed additional types to make it work better.

The new IFdbDatabaseProvider and IFdbDatabaseScopeProvider are interfaces that can be registered with the DI framework, and can be used to obtain an IFdbDatabase instance inside MVC controllers, for example.

The reason we are not registering an IFdbDatabase singleton directly is that the creation of this instance is async, and it is possible that the cluster is down while the web site is starting up.

The IFdbDatabaseScopeProvider on the other hand, only wraps the desiered connection options, and has a method GetDatabaseAsync that returns a cached database instance asynchronously:

public interface IFdbDatabaseScopeProvider : IDisposable
{
		// ... other methods

		/// <summary>Return an instance of the database, once it is ready</summary>
		/// <remarks>During the startup of the application, the task returned will wait until the database becomes ready. After that, the task will immediately return the database singleton.</remarks>
		[ItemNotNull]
		ValueTask<IFdbDatabase> GetDatabase(CancellationToken ct);
 
}

The expected usage of this interface is to require an IFdbDatabaseScopeProvider in your controller's constructor, and then await provider.GetDatabase(...) to get the IFdbDatabase instance. While the application is still in the early startup stage, and the database connection is not yet ready, this task will block until it is ready. Once the connection has been set up, then this task will immediately return the cached instance (hence why this is a ValueTask<...>.

To simplify the code, there is a set of extensions methods ReadAsync(...), ReadWriteAsync(..) and WriteAsync(...) on providers that are identicial to the version on a database instance, and handle all of this under the hood.

This means that in practice, MVC controllers can treat an IFdbDatabaseScopeProvider the same way as an IFdbDatabase.

Startup class:

    public class Startup
    {

        public void ConfigureServices(IServiceCollection services)
        {
                // registers the various `IFdbDatabaseProvider` and `IFdbDatabaseScopeProvider` services with DI
                services.AddFoundationDb(520, options =>
                {
                        options.ConnectionOptions.PartitionPath = new[] { "FooBarApp", "AcmeCustomer", .... };
                        // other options here
                });
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApplicationLifetime lifetime)
        {
                // Plug with the "start" event of the web app, so that it calls "Start()" and "Stop()" on the root provider.
                app.UseFoundationDb((fdb) =>
                {
                        // more setup possible here
                });
        }
    }

Example controller:

public class FooController
{ 

    public IFdbDatabaseScopeProvider Db { get; }

    public FooController(IFdbDatabaseScopeProvider db, /* other services required */)
    {
        this.Db = db;
        //...
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<FooModel>>> Get(CancellationToken ct)
    {
        return await this.Db.ReadAsync((tr) =>
        {
            // regular transaction code that reads a range and returns an sequence of 'FooModel'
        }, ct);
    }

    //....
}

5.2.0-preview1

IMPORTANT: This updates introduce a few breaking changes!

• Added multi-targeting to .NET 4.6.1, .NET 4.7.1 and .NET Standard 2.0
• Added support for API version 520 (AppendsIfFit, offset in SetVersionStampedValue, ...)
• [BREAKING] Changed binary format of embedded tuples to match the latest specifications (#84)
• [BREAKING] Renamed ITuple to IVarTuple to fix naming conflict in .NET Framework 4.7.1 (#89)
• Added FdbConnectionOptions and a corresponding Fdb.OpenAsync(..) that should be used as the default starting point.
• Deprecated all the other Fdb.OpenAsync(..) and Fdb.Directory.OpenNamedPartitionAsync(...)
• Fixed a few things regarding use of Watches (187ac16)
• Optimized futures to use TaskCreationOptions.RunContinuationsAsynchronously instead of queueing a workitem on the thread pool (a22228c)
• Added GetRangeKeys and GetRangeValues helpers that attempt to reduce the other of copying data that will not be used (7c46b38). Note that this feature is emulated client-side because it is not supported by the db at this time!
• [BREAKING] FdbRangeChunk has been changed from a struct to a class (0167365)
• Added a few commands to FDBShell
• Made FDBTop work on smaller terminal sizes.

5.1.0-alpha2

This release aligns the encoding of embedded tuples and booleans with the new specifications.

THIS IS A BREAKING CHANGE: any data previously inserted in the database using embedded tuples or booleans will not be compatible with this new version!

• Change the encoding of embedded tuples from type 0x03 to 0x05 (#84)
• Change the encoding of booleans from integers to types 0x26 and 0x27 (#84)
• Add pre-emptive support for new handling of versionstamped keys and values in API 520 (f09709c)
• Remove redundant async/await in Fdb.OpenAsync(...) call (#86)

5.1.0-alpha1

Updated version that targets FoundationDB API v510 by default and .NET Standard 2.0

• Use API version 510 by default (#63)
• Migrated projects to target .NET Standard 2.0 (#68)
• Added initial support for VersionStamps (#72)
• Added integration with System.ValueTuple (#73)
• Updated the Tuple Encoder layer and Slice code (breaking change)
• Updated the IKeyEncoder and Subspace API (breaking change)

warning: the API is still marked as unstable and may change again in the next alpha or beta release!

0.9.8-pre

Pre-release of the NuGet package for the FoundationDB .NET Binding, as well as the FDBShell and FDBTop command line tools.

This release adds support for the new FoundationDB v3.x API.

0.9.7-pre

Pre-release of the NuGet package for the FoundationDB .NET Binding and the FDBShell command line tool.