Updated documentation

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2022 MASES s.r.l.
+   Copyright 2023 MASES s.r.l.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

src/documentation/articles/kafkadbcontext.md

@@ -1,16 +1,26 @@
 # KEFCore: KafkaDbContext
 
-`KafkaDbContext` is a special class to define the `DbContext` to use with EntityFrameworkCore:
-- it inherits from `DbContext`: to define the model, and/or creating the database, see [getting started](https://docs.microsoft.com/ef/core/get-started/) in the docs
-- it defines the following properties:
+`KafkaDbContext` is a special class which helps to define the `DbContext` and use Entity Framework Core with Apache Kafka:
+- `KafkaDbContext` inherits from `DbContext`: to define the model, and/or creating the database, see [getting started](https://docs.microsoft.com/ef/core/get-started/) in the docs and [KEFCore usage](usage.md)
+- `KafkaDbContext` defines the following properties:
   - **BootstrapServers**: the server hosting the broker of Apache Kafka
   - **ApplicationId**: the application identifier used to identify the context
   - **DbName**: the user defined name which declares the database name, it is used to prepend every Topic which belongs to this database
   - **DefaultNumPartitions**: the default number of partitions used when topics are created for each entity
   - **DefaultReplicationFactor**: the replication factor to use when data are stored in Apache Kafka
+  - **DefaultConsumerInstances**: the consumer instances to be allocated when UseCompactedReplicator is **true**
   - **UsePersistentStorage**: set to **true** to use a persintent storage between multiple application startup
-  - **UseProducerByEntity**: use a different producer for each enity of EntityFrameworkCore model
+  - **UseCompactedReplicator**: Use `KNetCompactedReplicator` instead of Apache Kafka Streams to manage data to or from topics
   - **ProducerConfigBuilder**: parameters to use for Producer
-  - **StreamsConfigBuilder**: parameters to use for Stream application
+  - **StreamsConfigBuilder**: parameters to use for Apche Kafka Streams application
   - **TopicConfigBuilder**: parameters to use on topic creation for each entity
 
+## How to use `KafkaDbContext` class
+
+The most simple example of usage can be found in [KEFCore usage](usage.md). By default, `KafkaDbContext` automatically manages `OnConfiguring` method of `DbContext`:
+- checks for mandatory opions like **BootstrapServers** and **DbName**
+- setup the options to use an Apache Kafka cluster
+
+
+
+

src/net/KEFCore/Design/Internal/KafkaCSharpRuntimeAnnotationCodeGenerator.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -24,6 +24,12 @@
 namespace MASES.EntityFrameworkCore.KNet.Design.Internal;
 
 #pragma warning disable EF1001 // Internal EF Core API usage.
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaCSharpRuntimeAnnotationCodeGenerator : CSharpRuntimeAnnotationCodeGenerator
 {
     public KafkaCSharpRuntimeAnnotationCodeGenerator(

src/net/KEFCore/Design/Internal/KafkaDesignTimeServices.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -24,7 +24,12 @@
 [assembly: DesignTimeProviderServices("MASES.EntityFrameworkCore.KNet.Design.Internal.KafkaDesignTimeServices")]
 
 namespace MASES.EntityFrameworkCore.KNet.Design.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaDesignTimeServices : IDesignTimeServices
 {
     public virtual void ConfigureDesignTimeServices(IServiceCollection serviceCollection)

src/net/KEFCore/Diagnostics/Internal/KafkaLoggerExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -22,7 +22,12 @@
 using MASES.EntityFrameworkCore.KNet.Internal;
 
 namespace MASES.EntityFrameworkCore.KNet.Diagnostics.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public static class KafkaLoggerExtensions
 {
     public static void TransactionIgnoredWarning(

src/net/KEFCore/Diagnostics/Internal/KafkaLoggingDefinitions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -20,7 +20,12 @@
 */
 
 namespace MASES.EntityFrameworkCore.KNet.Diagnostics.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaLoggingDefinitions : LoggingDefinitions
 {
     public EventDefinitionBase? LogSavedChanges;

src/net/KEFCore/Diagnostics/KafkaEventId.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Extensions/KafkaDatabaseFacadeExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Extensions/KafkaDbContextOptionsExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -31,63 +31,63 @@ namespace MASES.EntityFrameworkCore.KNet;
 public static class KafkaDbContextOptionsExtensions
 {
     /// <summary>
-    ///     Configures the context to connect to an Kafka database.
-    ///     The Kafka database is shared anywhere the same name is used, but only for a given
+    ///     Configures the context to connect to an Apache Kafka cluster.
+    ///     The Apache Kafka cluster is shared anywhere the same name is used, but only for a given
     ///     service provider.
     /// </summary>
     /// <remarks>
     ///     See <see href="https://aka.ms/efcore-docs-dbcontext-options">Using DbContextOptions</see>, and
-    ///     <see href="https://github.com/masesgroup/KEFCore">The EF Core Kafka database provider</see> for more information and examples.
+    ///     <see href="https://github.com/masesgroup/KEFCore">The EF Core Apache Kafka cluster provider</see> for more information and examples.
     /// </remarks>
     /// <typeparam name="TContext">The type of context being configured.</typeparam>
     /// <param name="optionsBuilder">The builder being used to configure the context.</param>
     /// <param name="applicationId">
-    ///     The name of the application will use <paramref name="databaseName"/>. This allows the scope of the Kafka database to be controlled
-    ///     independently of the context. The Kafka database is shared anywhere the same name is used.
+    ///     The name of the application will use <paramref name="databaseName"/>. This allows the scope of the Apache Kafka cluster to be controlled
+    ///     independently of the context. The Apache Kafka cluster is shared anywhere the same name is used.
     /// </param>
     /// <param name="databaseName">
-    ///     The name of the Kafka database. This allows the scope of the Kafka database to be controlled
-    ///     independently of the context. The Kafka database is shared anywhere the same name is used.
+    ///     The name of the Apache Kafka cluster. This allows the scope of the Apache Kafka cluster to be controlled
+    ///     independently of the context. The Apache Kafka cluster is shared anywhere the same name is used.
     /// </param>
     /// <param name="bootstrapServers">
     ///     The bootstrap servers of the Kafka cluster.
     /// </param>
-    /// <param name="kafkaOptionsAction">An optional action to allow additional Kafka specific configuration.</param>
+    /// <param name="kafkaOptionsAction">An optional action to allow additional Apache Kafka cluster specific configuration.</param>
     /// <returns>The options builder so that further configuration can be chained.</returns>
-    public static DbContextOptionsBuilder<TContext> UseKafkaDatabase<TContext>(
+    public static DbContextOptionsBuilder<TContext> UseKafkaCluster<TContext>(
         this DbContextOptionsBuilder<TContext> optionsBuilder,
         string applicationId,
         string databaseName,
         string bootstrapServers,
         Action<KafkaDbContextOptionsBuilder>? kafkaOptionsAction = null)
         where TContext : DbContext
-        => (DbContextOptionsBuilder<TContext>)UseKafkaDatabase(
+        => (DbContextOptionsBuilder<TContext>)UseKafkaCluster(
             (DbContextOptionsBuilder)optionsBuilder, applicationId, databaseName, bootstrapServers, kafkaOptionsAction);
 
     /// <summary>
-    ///     Configures the context to connect to a named Kafka database.
-    ///     The Kafka database is shared anywhere the same name is used, but only for a given
+    ///     Configures the context to connect to a named Apache Kafka cluster.
+    ///     The Apache Kafka cluster is shared anywhere the same name is used, but only for a given
     ///     service provider.
     /// </summary>
     /// <remarks>
     ///     See <see href="https://aka.ms/efcore-docs-dbcontext-options">Using DbContextOptions</see>, and
-    ///     <see href="https://github.com/masesgroup/KEFCore">The EF Core Kafka database provider</see> for more information and examples.
+    ///     <see href="https://github.com/masesgroup/KEFCore">The EF Core Apache Kafka cluster provider</see> for more information and examples.
     /// </remarks>
     /// <param name="optionsBuilder">The builder being used to configure the context.</param>
     /// <param name="applicationId">
-    ///     The name of the application will use <paramref name="databaseName"/>. This allows the scope of the Kafka database to be controlled
-    ///     independently of the context. The Kafka database is shared anywhere the same name is used.
+    ///     The name of the application will use <paramref name="databaseName"/>. This allows the scope of the Apache Kafka cluster to be controlled
+    ///     independently of the context. The Apache Kafka cluster is shared anywhere the same name is used.
     /// </param>
     /// <param name="databaseName">
-    ///     The name of the Kafka database. This allows the scope of the Kafka database to be controlled
-    ///     independently of the context. The Kafka database is shared anywhere the same name is used.
+    ///     The name of the Apache Kafka cluster. This allows the scope of the Apache Kafka cluster to be controlled
+    ///     independently of the context. The Apache Kafka cluster is shared anywhere the same name is used.
     /// </param>
     /// <param name="bootstrapServers">
     ///     The bootstrap servers of the Kafka cluster.
     /// </param>
     /// <param name="kafkaOptionsAction">An optional action to allow additional Kafka specific configuration.</param>
     /// <returns>The options builder so that further configuration can be chained.</returns>
-    public static DbContextOptionsBuilder UseKafkaDatabase(
+    public static DbContextOptionsBuilder UseKafkaCluster(
         this DbContextOptionsBuilder optionsBuilder,
         string applicationId,
         string databaseName,

src/net/KEFCore/Extensions/KafkaEntityTypeBuilderExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Extensions/KafkaEntityTypeExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Extensions/KafkaServiceCollectionExtensions.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Infrastructure/IKafkaDbContextOptionsBuilderInfrastructure.cs

@@ -2,7 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.

src/net/KEFCore/Infrastructure/Internal/IKafkaSingletonOptions.cs

@@ -1,5 +1,5 @@
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -23,7 +23,12 @@
 using MASES.KNet.Streams;
 
 namespace MASES.EntityFrameworkCore.KNet.Infrastructure.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public interface IKafkaSingletonOptions : ISingletonOptions
 {
     bool UseNameMatching { get; }

src/net/KEFCore/Infrastructure/Internal/KafkaModelValidator.cs

@@ -1,5 +1,5 @@
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -17,7 +17,12 @@
 */
 
 namespace MASES.EntityFrameworkCore.KNet.Infrastructure.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaModelValidator : ModelValidator
 {
     public KafkaModelValidator(ModelValidatorDependencies dependencies)

src/net/KEFCore/Infrastructure/Internal/KafkaOptionsExtension.cs

@@ -1,5 +1,5 @@
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -29,7 +29,12 @@
 using System.Globalization;
 
 namespace MASES.EntityFrameworkCore.KNet.Infrastructure.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaOptionsExtension : IDbContextOptionsExtension
 {
     private bool _useNameMatching = true;

src/net/KEFCore/Infrastructure/Internal/KafkaSingletonOptions.cs

@@ -1,5 +1,5 @@
 /*
-*  Copyright 2022 MASES s.r.l.
+*  Copyright 2023 MASES s.r.l.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
@@ -21,7 +21,12 @@
 using MASES.KNet.Streams;
 
 namespace MASES.EntityFrameworkCore.KNet.Infrastructure.Internal;
-
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
 public class KafkaSingletonOptions : IKafkaSingletonOptions
 {
     public virtual void Initialize(IDbContextOptions options)
@@ -55,7 +60,7 @@ public virtual void Validate(IDbContextOptions options)
         {
             throw new InvalidOperationException(
                 CoreStrings.SingletonOptionChanged(
-                    nameof(KafkaDbContextOptionsExtensions.UseKafkaDatabase),
+                    nameof(KafkaDbContextOptionsExtensions.UseKafkaCluster),
                     nameof(DbContextOptionsBuilder.UseInternalServiceProvider)));
         }
     }