updated readme files for 0.8.0 release

Author: feO2x

Code/src/Synnotech.Migrations.RavenDB/readme.md

@@ -5,15 +5,15 @@
 [![Synnotech Logo](https://github.com/Synnotech-AG/Synnotech.Migrations/raw/main/synnotech-large-logo.png)](https://www.synnotech.de/)
 
 [![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://github.com/Synnotech-AG/Synnotech.Migrations/blob/main/LICENSE)
-[![NuGet](https://img.shields.io/badge/NuGet-0.7.0-blue.svg?style=for-the-badge)](https://www.nuget.org/packages/Synnotech.Migrations.RavenDB/)
+[![NuGet](https://img.shields.io/badge/NuGet-0.8.0-blue.svg?style=for-the-badge)](https://www.nuget.org/packages/Synnotech.Migrations.RavenDB/)
 
 # How to Install
 
 Synnotech.Migrations.RavenDB is compiled against [.NET Standard 2.0 and 2.1](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) and thus supports all major plattforms like .NET 5, .NET Core, .NET Framework 4.6.1 or newer, Mono, Xamarin, UWP, or Unity.
 
 Synnotech.Migrations.RavenDB is available as a [NuGet package](https://www.nuget.org/packages/Synnotech.Migrations.RavenDB/) and can be installed via:
 
-- **Package Reference in csproj**: `<PackageReference Include="Synnotech.Migrations.RavenDB" Version="0.7.0" />`
+- **Package Reference in csproj**: `<PackageReference Include="Synnotech.Migrations.RavenDB" Version="0.8.0" />`
 - **dotnet CLI**: `dotnet add package Synnotech.Migrations.RavenDB`
 - **Visual Studio Package Manager Console**: `Install-Package Synnotech.Migrations.RavenDB`
 
@@ -23,7 +23,7 @@ If you want to run with the default setup, registration is pretty easy. Synnotec
 
 ## Set Up in ASP.NET Core Apps
 
-If you write an ASP.NET Core app, you can simply call `AddSynnotechMigration` in `Startup.ConfigureService`:
+If you write an ASP.NET Core app, you can simply call `AddSynnotechMigrations` in `Startup.ConfigureService`:
 
 ```csharp
 public sealed class Startup
@@ -49,20 +49,25 @@ public sealed class Startup
 }
 ```
 
-`AddSynnotechMigrations` registers the `SessionFactory` as well as the `MigrationEngine` with a transient lifetime. If there is not already a registration for `IAsyncDocumentSession`, one will be created as well with a transient lifetime. Take a look at the [ServiceCollectionExtensions](https://github.com/Synnotech-AG/Synnotech.Migrations/blob/main/Code/src/Synnotech.Migrations.RavenDB/ServiceCollectionExtensions.cs) class to see what is going on exactly.
+`AddSynnotechMigrations` registers the `MigrationEngine`, all required services, and your migrations (classes that derive from `Migration` directly or indirectly) with a transient lifetime. Take a look at the [ServiceCollectionExtensions](https://github.com/Synnotech-AG/Synnotech.Migrations/blob/main/Code/src/Synnotech.Migrations.RavenDB/ServiceCollectionExtensions.cs) class to see what is going on exactly.
 
 Please ensure that a registration for `IDocumentStore` is already present in the DI container. You can use [Synnotech.RavenDB](https://github.com/Synnotech-AG/Synnotech.RavenDB) to do that.
 
 We suggest that you run your migrations at the beginning of `Startup.Configure`, so that the target database is up to date every time the web app starts. Of course, you are not limited to that - you could e.g. create a dedicated controller action that executes migrations.
 
 ## Setup in Other Apps
 
-To instantiate the `MigrationEngine`, you need to provide an `ISessionFactory<MigrationSession, MigrationInfo>` to the constructor. This interface is implemented by `SessionFactory`. `SessionFactory` itself requires an instance of RavenDB's `IDocumentStore`. With Pure DI, you can create a migration engine instance this way:
+To instantiate the `MigrationEngine`, you need to provide the following services:
 
-```csharp
+- `ISessionFactory<MigrationInfo, Migration, IAsyncDocumentSession>`: the default implementation is `SessionFactory`
+- `IMigrationFactory<Migration>`: there are two options here by default - `MicrosoftDependencyInjectionMigrationFactory<TMigration>` uses your DI container (via `IServiceProvider`) to instantiate migrations. If you use this option, all your migrations must be registered against the DI container (you can use the [AddMigrationTypes](https://github.com/Synnotech-AG/Synnotech.Migrations/blob/main/Code/src/Synnotech.Migrations.Core/Migrations.cs#L27) extension method for that). `ActivatorMigrationFactory<TMigration>` uses `Activator.CreateInstance` to call the default constructor of a migration. You can also derive from `BaseMigrationFactory<TMigration>` to implement your own factory (e.g. when you want to adapt for your custom DI container).
+- `Func<Migration, DateTime, MigrationInfo>`: this delegate is used to instantiate migration infos from migrations and a timestamp.
+
+ ```csharp
 IDocumentStore store = InitializeDocumentStore(); // Configures connection to RavenDB server
 var sessionFactory = new SessionFactory(store);
-var migrationEngine = new MigrationEngine(sessionFactory);
+var migrationFactory = new ActivatorMigrationFactory<Migration>();
+var migrationEngine = new MigrationEngine(sessionFactory, migrationFactory, MigrationInfo.Create);
 ```
 
 If you use a DI container, you could register the types similar to the following pseudo code:
@@ -71,12 +76,16 @@ If you use a DI container, you could register the types similar to the following
 IDocumentStore store = InitializeDocumentStore(); // Configures connection to RavenDB server
 container.RegisterSingleton(store)
          .RegisterTransient<SessionFactory>()
-         .RegisterTransient(c => new MigrationEngine(c.Resolve<SessionFactory>()))
+         .RegisterTransient<ActivatorMigrationFactory<Migration>>()
+         .RegisterSingleton<Func<Migration, DateTime, MigrationInfo>>(MigrationInfo.Create)
+         .RegisterTransient(c => new MigrationEngine(c.Resolve<SessionFactory>(),
+                                                     c.Resolve<ActivatorMigrationFactory<Migration>>(),
+                                                     c.Resolve<Func<Migration, DateTime, MigrationInfo>>()));
 ```
 
 ## Writing Migrations
 
-A migration is a `public` class that derives from the `Migration` base class and is decorated with the `MigrationVersion` attribute. It has a single method called `ApplyAsync` where you receive a `MigrationSession` that you can use to manipulate the target database.
+A migration is a `public` class that derives from the `Migration` base class and is decorated with the `MigrationVersion` attribute. It has a single method called `ApplyAsync` where you receive RavenDB's `IAsyncDocumentSession` and a `CancellationToken` that you can use to manipulate the target database.
 
 A typical migration might look like this:
 
@@ -91,12 +100,11 @@ namespace MyRavenDBAccessLayer
     [MigrationVersion("1.0.0")]
     public sealed class InitialMasterData : Migration
     {
-        public override async Task ApplyAsync(MigrationSession context)
+        public override async Task ApplyAsync(IAsyncDocumentSession session)
         {
-            IAsyncDocumentSession session = context.Session;
             var masterData = MasterData.GetInitialMasterData();
 
-            foreach(var item in masterData)
+            foreach (var item in masterData)
             {
                 await session.StoreAsync(item);
             }
@@ -108,9 +116,10 @@ namespace MyRavenDBAccessLayer
 When writing migrations, keep the following things in mind:
 
 1. You don't need to call `session.SaveChangesAsync` - the migration engine will do that for you.
-1. Every migration gets a fresh `MigrationSession` instance. `WaitForIndexesAfterSaveChanges` is activated by default, so you can be sure that you can query data that was inserted in previous migrations.
+1. Every migration gets a fresh session instance. `WaitForIndexesAfterSaveChanges` is activated by default, so you can be sure that you can query data that was inserted in previous migrations.
 1. Also, you do not need to add `MigrationInfo` instances manually to the database, the migration engine will do that for you.
 1. The `MigrationVersion` uses the default `System.Version` class internally to determine the version. We suggest you use [Semantic Versioning](https://semver.org/) for your migrations.
+1. If you use the default setup, or resolve your migrations via a DI container, you can incorporate Dependency Injection in your migration classes (usually via Constructor Injection). If your migration implements `IAsyncDisposable` or `IDisposable`, the migration engine will dispose them after execution.
 1. We encourage you to organize your migations in a dedicated subfolder of your RavenDB data access folder / project (see picture below).
 1. We suggest that you create a dedicated integration test that tries to apply all migrations at once to a fresh RavenDB database, thus you can be sure everything works correctly before rolling out your software.
 
@@ -123,7 +132,7 @@ When writing migrations, keep the following things in mind:
 The migration engine offers you three methods to apply migrations to the target database:
 
 1. `MigrateAsync` does all in one go: it first checks the target system and tries to retrieve information about the latest applied migration. Based on this, it then determines which migrations need to be applied and executes them against the target database.
-2. `GenerateMigrationPlanAsync` only checks the target database and retrieves information about the latest applied migration. It also determines which migrations need to be applied and returns both information. This is useful if the calling code wants to know if there are any pending migrations and then ask the user to confirm the database changes.
+2. `GetPlanForNewMigrationsAsync` only checks the target database and retrieves information about the latest applied migration. It also determines which migrations need to be applied and returns both information. This is useful if the calling code wants to know if there are any pending migrations and then ask the user to confirm the database changes.
 3. `ApplyMigrationsAsync` takes a list of migrations and applies them to the target database. Is often used in combination with `GenerateMigrationPlanAsync`.
 
 In most apps, we suggest that you simply use `MigrateAsync` at application start to keep the database up-to-date. The two other methods are typically used if you have a dedicated Export-to-Database functionality where the user can agree or disagree with applying the latest migrations.
@@ -139,7 +148,7 @@ public static class RavenDbExtensions
 {
     public static async Task MigrateAsync(this MigrationEngine migrationEngine, ILogger logger)
     {
-        var summary = await migrationEngine.MigrateAsync(typeof(RavenDbExtensions).Assembly, DateTime.UtcNow);
+        var summary = await migrationEngine.MigrateAsync();
 
         // First we try to log all applied migrations of this run
         if (summary.TryGetAppliedMigrations(out var appliedMigrations))

README.md

@@ -5,7 +5,7 @@
 [![Synnotech Logo](synnotech-large-logo.png)](https://www.synnotech.de/)
 
 [![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://github.com/Synnotech-AG/Synnotech.Migrations/blob/main/LICENSE)
-[![NuGet](https://img.shields.io/badge/NuGet-0.7.0-blue.svg?style=for-the-badge)](https://www.nuget.org/packages?q=Synnotech.Migrations)
+[![NuGet](https://img.shields.io/badge/NuGet-0.8.0-blue.svg?style=for-the-badge)](https://www.nuget.org/packages?q=Synnotech.Migrations)
 
 When starting a new project, do you always spent too much time on how you can migrate your database? Do you want a migration mechanism that is independent of any persistence technology, like ORMs for relational databases? Worry no more because **Synnotech.Migrations** offers just that! Our generic migration engine is written in such a way so that you can easily adapt it to your own data access layer, no matter the technology: relational databases with and without ORMs, document or graph databases, the file system, or web services - the possibilities are endless.
 
@@ -26,7 +26,7 @@ Please visit the corresponding pages for further documentation.
 
 ## Supported Frameworks
 
-**Synnotech.Migrations** is build for .NET Standard 2.0, so you can use it on [all platforms that support it](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), e.g. like:
+**Synnotech.Migrations** is build for .NET Standard 2.0 and .NET Standard 2.1, so you can use it on [all platforms that support it](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), e.g. like:
 
 - .NET 5 or newer
 - .NET Core 2.0 or newer