From 5738ba0e6fddafd3872cafdc23ff7c8dead73bd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Chalet?= <kevinchalet@gmail.com>
Date: Tue, 23 Jun 2020 14:49:07 +0200
Subject: [PATCH] Update the documentation to indicate the default OpenIddict
 entities must be replaced using ReplaceDefaultEntities()

---
 samples/Mvc.Server/Startup.cs                 |  1 +
 .../OpenIddictEntityFrameworkHelpers.cs       |  7 +++++--
 .../OpenIddictEntityFrameworkCoreHelpers.cs   | 20 ++++++++++++++++++-
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/samples/Mvc.Server/Startup.cs b/samples/Mvc.Server/Startup.cs
index 182334fd..79df37e6 100644
--- a/samples/Mvc.Server/Startup.cs
+++ b/samples/Mvc.Server/Startup.cs
@@ -52,6 +52,7 @@ namespace Mvc.Server
                 .AddCore(options =>
                 {
                     // Configure OpenIddict to use the Entity Framework Core stores and models.
+                    // Note: call ReplaceDefaultEntities() to replace the default OpenIddict entities.
                     options.UseEntityFrameworkCore()
                            .UseDbContext<ApplicationDbContext>();
                 })
diff --git a/src/OpenIddict.EntityFramework/OpenIddictEntityFrameworkHelpers.cs b/src/OpenIddict.EntityFramework/OpenIddictEntityFrameworkHelpers.cs
index 8829a9ea..5f7d7dab 100644
--- a/src/OpenIddict.EntityFramework/OpenIddictEntityFrameworkHelpers.cs
+++ b/src/OpenIddict.EntityFramework/OpenIddictEntityFrameworkHelpers.cs
@@ -9,6 +9,7 @@ using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Threading;
 using JetBrains.Annotations;
+using Microsoft.Extensions.DependencyInjection;
 using OpenIddict.EntityFramework;
 using OpenIddict.EntityFramework.Models;
 
@@ -34,9 +35,11 @@ namespace System.Data.Entity
         /// <summary>
         /// Registers the OpenIddict entity sets in the Entity Framework 6.x
         /// context using the specified entities and the specified key type.
-        /// Note: using this method requires creating non-generic derived classes
-        /// for all the OpenIddict entities (application, authorization, scope, token).
         /// </summary>
+        /// <remarks>
+        /// Note: when using custom entities, the new entities MUST be registered by calling
+        /// <see cref="OpenIddictEntityFrameworkBuilder.ReplaceDefaultEntities{TApplication, TAuthorization, TScope, TToken, TKey}"/>.
+        /// </remarks>
         /// <param name="builder">The builder used to configure the Entity Framework context.</param>
         /// <returns>The Entity Framework context builder.</returns>
         public static DbModelBuilder UseOpenIddict<TApplication, TAuthorization, TScope, TToken, TKey>([NotNull] this DbModelBuilder builder)
diff --git a/src/OpenIddict.EntityFrameworkCore/OpenIddictEntityFrameworkCoreHelpers.cs b/src/OpenIddict.EntityFrameworkCore/OpenIddictEntityFrameworkCoreHelpers.cs
index e9a7deb0..b8675ee5 100644
--- a/src/OpenIddict.EntityFrameworkCore/OpenIddictEntityFrameworkCoreHelpers.cs
+++ b/src/OpenIddict.EntityFrameworkCore/OpenIddictEntityFrameworkCoreHelpers.cs
@@ -11,6 +11,7 @@ using System.Runtime.CompilerServices;
 using System.Threading;
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.Extensions.DependencyInjection;
 using OpenIddict.EntityFrameworkCore;
 using OpenIddict.EntityFrameworkCore.Models;
 
@@ -37,6 +38,10 @@ namespace Microsoft.EntityFrameworkCore
         /// Registers the OpenIddict entity sets in the Entity Framework Core 
         /// context using the default OpenIddict models and the specified key type.
         /// </summary>
+        /// <remarks>
+        /// Note: when using a custom key type, the new key type MUST be registered by calling
+        /// <see cref="OpenIddictEntityFrameworkCoreBuilder.ReplaceDefaultEntities{TKey}"/>.
+        /// </remarks>
         /// <param name="builder">The builder used to configure the Entity Framework context.</param>
         /// <returns>The Entity Framework context builder.</returns>
         public static DbContextOptionsBuilder UseOpenIddict<TKey>([NotNull] this DbContextOptionsBuilder builder)
@@ -50,9 +55,14 @@ namespace Microsoft.EntityFrameworkCore
         /// Registers the OpenIddict entity sets in the Entity Framework Core
         /// context using the specified entities and the specified key type.
         /// </summary>
+        /// <remarks>
+        /// Note: when using custom entities, the new entities MUST be registered by calling
+        /// <see cref="OpenIddictEntityFrameworkCoreBuilder.ReplaceDefaultEntities{TApplication, TAuthorization, TScope, TToken, TKey}"/>.
+        /// </remarks>
         /// <param name="builder">The builder used to configure the Entity Framework context.</param>
         /// <returns>The Entity Framework context builder.</returns>
-        public static DbContextOptionsBuilder UseOpenIddict<TApplication, TAuthorization, TScope, TToken, TKey>([NotNull] this DbContextOptionsBuilder builder)
+        public static DbContextOptionsBuilder UseOpenIddict<TApplication, TAuthorization, TScope, TToken, TKey>(
+            [NotNull] this DbContextOptionsBuilder builder)
             where TApplication : OpenIddictEntityFrameworkCoreApplication<TKey, TAuthorization, TToken>
             where TAuthorization : OpenIddictEntityFrameworkCoreAuthorization<TKey, TApplication, TToken>
             where TScope : OpenIddictEntityFrameworkCoreScope<TKey>
@@ -84,6 +94,10 @@ namespace Microsoft.EntityFrameworkCore
         /// Registers the OpenIddict entity sets in the Entity Framework Core
         /// context using the default OpenIddict models and the specified key type.
         /// </summary>
+        /// <remarks>
+        /// Note: when using a custom key type, the new key type MUST be registered by calling
+        /// <see cref="OpenIddictEntityFrameworkCoreBuilder.ReplaceDefaultEntities{TKey}"/>.
+        /// </remarks>
         /// <param name="builder">The builder used to configure the Entity Framework context.</param>
         /// <returns>The Entity Framework context builder.</returns>
         public static ModelBuilder UseOpenIddict<TKey>([NotNull] this ModelBuilder builder) where TKey : IEquatable<TKey>
@@ -96,6 +110,10 @@ namespace Microsoft.EntityFrameworkCore
         /// Registers the OpenIddict entity sets in the Entity Framework Core
         /// context using the specified entities and the specified key type.
         /// </summary>
+        /// <remarks>
+        /// Note: when using custom entities, the new entities MUST be registered by calling
+        /// <see cref="OpenIddictEntityFrameworkCoreBuilder.ReplaceDefaultEntities{TApplication, TAuthorization, TScope, TToken, TKey}"/>.
+        /// </remarks>
         /// <param name="builder">The builder used to configure the Entity Framework context.</param>
         /// <returns>The Entity Framework context builder.</returns>
         public static ModelBuilder UseOpenIddict<TApplication, TAuthorization, TScope, TToken, TKey>([NotNull] this ModelBuilder builder)