BFF upgrade guides - add EF Core migrations

Author: maartenba

src/content/docs/bff/fundamentals/session/server-side-sessions.mdx

@@ -34,7 +34,7 @@ The default implementation stores the session in-memory. This is useful for test
 
 ## Using Entity Framework for the Server-side Session Store
 
-To use the EF session store, install the *Duende.BFF.EntityFramework* NuGet package and register it by calling *AddEntityFrameworkServerSideSessions*, like this:
+To use the EF session store, install the `Duende.BFF.EntityFramework` NuGet package and register it by calling `AddEntityFrameworkServerSideSessions`, like this:
 
 ```csharp
 var cn = _configuration.GetConnectionString("db");
@@ -67,14 +67,14 @@ Note, you'll still need to let the server side session store know about the `Ses
 
 ### Entity Framework Migrations
 
-Most data stores that you might use with Entity Framework use a schema to define the structure of their data. *Duende.BFF.EntityFramework* doesn't make any assumptions about the underlying datastore, how (or indeed even if) it defines its schema, or how schema changes are managed by your organization. For these reasons, Duende does not directly support database creation, schema changes, or data migration by publishing database scripts.
+Most data stores that you might use with Entity Framework use a schema to define the structure of their data. `Duende.BFF.EntityFramework` doesn't make any assumptions about the underlying datastore, how (or indeed even if) it defines its schema, or how schema changes are managed by your organization. For these reasons, Duende does not directly support database creation, schema changes, or data migration by publishing database scripts.
 
-You are expected to manage your database in the way your organization sees fit. Using EF migrations is one possible approach to that, which Duende facilitates by publishing entity classes in each version of *Duende.BFF.EntityFramework*. An example project that uses those entities to create migrations is [here](https://github.com/DuendeSoftware/products/tree/main/bff/migrations/UserSessionDb).
+You are expected to manage your database in the way your organization sees fit. Using EF migrations is one possible approach to that, which Duende facilitates by publishing entity classes in each version of `Duende.BFF.EntityFramework`. An example project that uses those entities to create migrations is [here](https://github.com/DuendeSoftware/products/tree/main/bff/migrations/UserSessionDb).
 
 To quickly create Entity Framework migrations, run the following command in the project directory that has access to Entity Framework Core's tools:
 
 ```bash
-dotnet ef migrations add UserSessions -o Migrations
+dotnet ef migrations add UserSessions -o Migrations -c SessionDbContext
 ```
 
 The project must also reference the `Duende.BFF.EntityFramework` NuGet package and the `Microsoft.EntityFrameworkCore.Design` NuGet package, along with a specific database provider and its corresponding configuration, including the connection string.
@@ -89,7 +89,7 @@ Abandoned sessions will remain in the store unless something removes the stale e
   {/* prettier-ignore */}
   <TabItem label="V4">
 
-    If you wish to have such sessions cleaned up periodically, then you can add the session cleanup host and configure the *SessionCleanupInterval* options:
+    If you wish to have such sessions cleaned up periodically, then you can add the session cleanup host and configure the `SessionCleanupInterval` options:
 
       <Code
           lang="csharp"
@@ -99,9 +99,9 @@ Abandoned sessions will remain in the store unless something removes the stale e
     })
     .AddServerSideSessions();`}/>
 
-    This requires an implementation of [*IUserSessionStoreCleanup*](/bff/extensibility/sessions#user-session-store-cleanup) in the ASP.NET Core service provider.
+    This requires an implementation of [`IUserSessionStoreCleanup`](/bff/extensibility/sessions#user-session-store-cleanup) in the ASP.NET Core service provider.
 
-    If using Entity Framework Core, then the *IUserSessionStoreCleanup* implementation is provided for you when you use *AddEntityFrameworkServerSideSessions*.
+    If using Entity Framework Core, then the `IUserSessionStoreCleanup` implementation is provided for you when you use `AddEntityFrameworkServerSideSessions`.
     You can then add the `SessionCleanupBackgroundProcess`:
 
       <Code
@@ -125,7 +125,7 @@ builder.Services.AddBff()
   </TabItem>
   <TabItem label="V3">
 
-    If you wish to have such sessions cleaned up periodically, then you can configure the *EnableSessionCleanup* and *SessionCleanupInterval* options:
+    If you wish to have such sessions cleaned up periodically, then you can configure the `EnableSessionCleanup` and `SessionCleanupInterval` options:
 
       <Code
           lang="csharp"
@@ -136,9 +136,9 @@ builder.Services.AddBff()
     })
     .AddServerSideSessions();`}/>
 
-    This requires an implementation of [*IUserSessionStoreCleanup*](/bff/extensibility/sessions#user-session-store-cleanup) in the ASP.NET Core service provider.
+    This requires an implementation of [`IUserSessionStoreCleanup`](/bff/extensibility/sessions#user-session-store-cleanup) in the ASP.NET Core service provider.
 
-    If using Entity Framework Core, then the *IUserSessionStoreCleanup* implementation is provided for you when you use *AddEntityFrameworkServerSideSessions*.
+    If using Entity Framework Core, then the `IUserSessionStoreCleanup` implementation is provided for you when you use `AddEntityFrameworkServerSideSessions`.
     Just enable session cleanup:
 
       <Code

src/content/docs/bff/upgrading/bff-v2-to-v3.md

@@ -137,4 +137,31 @@ If you used `BffBlazorOptions.StateProviderPollingInterval` or `BffBlazorOptions
 different polling settings, you should now consider if this same setting applies to either Server, WASM or both. Set the
 appropriate properties accordingly.
 
+### Server Side Sessions Database Migrations
 
+No [Entity Framework database migrations](/bff/fundamentals/session/server-side-sessions.mdx#entity-framework-migrations) are required for the server side sessions feature when using the `Duende.BFF.EntityFramework` package.
+
+The database structure remains the same:
+
+```sqlite
+// serversidesessions.sql
+CREATE TABLE "UserSessions" (
+    "Id" INTEGER NOT NULL CONSTRAINT "PK_UserSessions" PRIMARY KEY AUTOINCREMENT,
+    "ApplicationName" TEXT NULL,
+    "SubjectId" TEXT NOT NULL,
+    "SessionId" TEXT NULL,
+    "Created" TEXT NOT NULL,
+    "Renewed" TEXT NOT NULL,
+    "Expires" TEXT NULL,
+    "Ticket" TEXT NOT NULL,
+    "Key" TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX "IX_UserSessions_ApplicationName_Key" ON "UserSessions" ("ApplicationName", "Key");
+
+CREATE UNIQUE INDEX "IX_UserSessions_ApplicationName_SessionId" ON "UserSessions" ("ApplicationName", "SessionId");
+
+CREATE UNIQUE INDEX "IX_UserSessions_ApplicationName_SubjectId_SessionId" ON "UserSessions" ("ApplicationName", "SubjectId", "SessionId");
+
+CREATE INDEX "IX_UserSessions_Expires" ON "UserSessions" ("Expires");
+```

src/content/docs/bff/upgrading/bff-v3-to-v4.md

@@ -129,4 +129,30 @@ You can configure the location of your `index.html` by specifying:
 
 ```csharp
 .WithIndexHtmlUrl(new Uri("https://localhost:5005/static/index.html"))
+```
+
+### Server Side Sessions Database Migrations
+
+When using the server side sessions feature backed by the `Duende.BFF.EntityFramework` package, you will need to script [Entity Framework database migrations](/bff/fundamentals/session/server-side-sessions.mdx#entity-framework-migrations) and apply these changes to your database.
+
+```shell
+dotnet ef migrations add BFFUserSessionsV4 -o Migrations -c SessionDbContext
+```
+
+In the `UserSessions` table, a number of changes were introduced:
+* The `ApplicationName` column was renamed to `PartitionKey`.
+* Related indexes were updated.
+
+```sqlite
+// serversidesessions.sql
+ALTER TABLE "UserSessions" RENAME COLUMN "ApplicationName" TO "PartitionKey";
+
+DROP INDEX "IX_UserSessions_ApplicationName_SubjectId_SessionId";
+CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_SubjectId_SessionId" ON "UserSessions" ("PartitionKey", "SubjectId", "SessionId");
+
+DROP INDEX "IX_UserSessions_ApplicationName_SessionId";
+CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_SessionId" ON "UserSessions" ("PartitionKey", "SessionId");
+
+DROP INDEX "IX_UserSessions_ApplicationName_Key";
+CREATE UNIQUE INDEX "IX_UserSessions_PartitionKey_Key" ON "UserSessions" ("PartitionKey", "Key");
 ```