feat: add an Aspire sample host for local testing and as a setup demo

.aspire/settings.json

@@ -1,3 +1,3 @@
 {
-  "appHostPath": "../AndreGoepel.MembersArea/AndreGoepel.MembersArea.AppHost/AndreGoepel.MembersArea.AppHost.csproj"
-}
+  "appHostPath": "samples/AndreGoepel.AppFoundation.AppHost/AndreGoepel.AppFoundation.AppHost.csproj"
+}

AndreGoepel.AppFoundation.slnx

@@ -14,4 +14,8 @@
     <Project Path="tests/AndreGoepel.AppFoundation.Tests/AndreGoepel.AppFoundation.Tests.csproj" />
     <Project Path="tests/AndreGoepel.AppFoundation.MailService.Tests/AndreGoepel.AppFoundation.MailService.Tests.csproj" />
   </Folder>
+  <Folder Name="/samples/">
+    <Project Path="samples/AndreGoepel.AppFoundation.AppHost/AndreGoepel.AppFoundation.AppHost.csproj" />
+    <Project Path="samples/AndreGoepel.AppFoundation.Sample/AndreGoepel.AppFoundation.Sample.csproj" />
+  </Folder>
 </Solution>

Directory.Packages.props

@@ -4,8 +4,8 @@
   </PropertyGroup>
 
   <ItemGroup Label="Aspire">
-    <PackageVersion Include="Aspire.Hosting.Docker" Version="13.3.5" />
-    <PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="13.3.5" />
+    <PackageVersion Include="Aspire.Hosting.Docker" Version="13.4.6" />
+    <PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="13.4.6" />
   </ItemGroup>
 
   <ItemGroup Label="Marten">

README.md

@@ -94,6 +94,30 @@ for a complete, working example.
 
 ---
 
+## Try it locally (sample host)
+
+The repo ships a runnable example under `samples/`: a .NET Aspire AppHost that starts
+PostgreSQL in a container plus a minimal Blazor Server host that wires the packages exactly
+as [Using it in a host app](#using-it-in-a-host-app) describes. It doubles as a manual smoke
+test for the foundation.
+
+**Prerequisites:** the .NET 10 SDK and a container runtime (Docker / Podman) for the database.
+
+```bash
+dotnet run --project samples/AndreGoepel.AppFoundation.AppHost
+```
+
+Open the Aspire dashboard URL printed to the console, start the **web** resource, and open it.
+The first visit funnels you to **/Setup** to create the administrator; after that you can sign
+in and explore the dashboard and the Administration area.
+
+| Project | Role |
+|---|---|
+| `samples/AndreGoepel.AppFoundation.AppHost` | Aspire orchestrator — starts Postgres and the web app, wiring the `appfoundation-database` connection string |
+| `samples/AndreGoepel.AppFoundation.Sample` | Minimal Blazor Server host consuming the packages — the reference `Program.cs`, `App.razor`, and `Routes.razor` |
+
+---
+
 ## Configuration
 
 A PostgreSQL connection string is required, by default under

samples/AndreGoepel.AppFoundation.AppHost/AndreGoepel.AppFoundation.AppHost.csproj

@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <Sdk Name="Aspire.AppHost.Sdk" Version="13.4.6" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <!-- The Aspire.AppHost.Sdk injects RID-specific orchestration/dashboard packages that
+         don't fit central package management, so manage this project's versions locally. -->
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+    <!-- Those injected packages are RID-specific, so a committed lock file would be
+         win-x64/linux-x64 dependent and break CI's locked-mode restore across OSes.
+         The AppHost is a dev-only sample, so opt it out of lock files. -->
+    <RestorePackagesWithLockFile>false</RestorePackagesWithLockFile>
+    <UserSecretsId>appfoundation-sample-apphost</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="13.4.6" />
+    <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="13.4.6" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\AndreGoepel.AppFoundation.Sample\AndreGoepel.AppFoundation.Sample.csproj" />
+  </ItemGroup>
+</Project>

samples/AndreGoepel.AppFoundation.AppHost/AppHost.cs

@@ -0,0 +1,16 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+// A PostgreSQL container with a persistent volume so setup and accounts survive restarts.
+var postgres = builder.AddPostgres("postgres").WithDataVolume();
+
+// The database resource name is the connection-string name the foundation reads by default
+// (AppFoundationOptions.DatabaseConnectionName == "appfoundation-database").
+var database = postgres.AddDatabase("appfoundation-database", "appfoundation");
+
+// The sample web app, wired to the database and started only once it is ready.
+builder
+    .AddProject<Projects.AndreGoepel_AppFoundation_Sample>("web")
+    .WithReference(database)
+    .WaitFor(database);
+
+builder.Build().Run();

samples/AndreGoepel.AppFoundation.AppHost/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17010;http://localhost:15010",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15010",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

samples/AndreGoepel.AppFoundation.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

samples/AndreGoepel.AppFoundation.Sample/AndreGoepel.AppFoundation.Sample.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <!-- The Web SDK pulls Microsoft.AspNetCore.App.Internal.Assets, whose version tracks
+         the installed ASP.NET Core runtime patch, so a committed lock file drifts whenever
+         local and CI SDK patch levels differ and breaks locked-mode restore. This is a
+         dev-only sample, so opt it out of lock files (as the AppHost does). -->
+    <RestorePackagesWithLockFile>false</RestorePackagesWithLockFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AndreGoepel.Marten.Identity.Blazor" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\AndreGoepel.AppFoundation.Hosting\AndreGoepel.AppFoundation.Hosting.csproj" />
+    <ProjectReference Include="..\..\src\AndreGoepel.AppFoundation\AndreGoepel.AppFoundation.csproj" />
+  </ItemGroup>
+</Project>

samples/AndreGoepel.AppFoundation.Sample/Components/App.razor

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <base href="/" />
+    <link rel="stylesheet" href="_content/Radzen.Blazor/css/material-base.css" />
+    <link rel="stylesheet" href="@Assets["app.css"]" />
+    <link rel="stylesheet" href="@Assets["AndreGoepel.AppFoundation.Sample.styles.css"]" />
+    <ImportMap />
+    <HeadOutlet @rendermode="InteractiveServer" />
+</head>
+
+<body>
+    <Routes @rendermode="InteractiveServer" />
+    <script src="_content/Radzen.Blazor/Radzen.Blazor.js"></script>
+    <script src="_framework/blazor.web.js"></script>
+</body>
+
+</html>

samples/AndreGoepel.AppFoundation.Sample/Components/Pages/Home.razor

@@ -0,0 +1,48 @@
+@page "/"
+@rendermode InteractiveServer
+
+@using AndreGoepel.Marten.Identity
+@using global::Marten
+
+@inject IQuerySession QuerySession
+@inject NavigationManager NavigationManager
+
+<PageTitle>AppFoundation Sample</PageTitle>
+
+<div class="rz-p-4 rz-p-md-8">
+    <RadzenStack Gap="1.5rem" Style="max-width: 40rem; margin: 0 auto;">
+
+        <RadzenText TextStyle="TextStyle.H3" TagName="TagName.H1">AppFoundation Sample</RadzenText>
+
+        <RadzenText TextStyle="TextStyle.Body1">
+            A minimal host that wires the AppFoundation packages. Use it to exercise the setup,
+            sign-in, and administration flows against a real PostgreSQL started by .NET Aspire.
+        </RadzenText>
+
+        <RadzenStack Orientation="Orientation.Horizontal" Gap="1rem" Wrap="FlexWrap.Wrap">
+            @if (setupComplete)
+            {
+                <RadzenButton Text="Dashboard"
+                              Icon="dashboard"
+                              Click="@(() => NavigationManager.NavigateTo("/dashboard"))" />
+                <RadzenButton Text="Sign in"
+                              ButtonStyle="ButtonStyle.Secondary"
+                              Click="@(() => NavigationManager.NavigateTo("/Account/Login"))" />
+            }
+            else
+            {
+                <RadzenButton Text="Run initial setup"
+                              Icon="install_desktop"
+                              Click="@(() => NavigationManager.NavigateTo("/Setup"))" />
+            }
+        </RadzenStack>
+
+    </RadzenStack>
+</div>
+
+@code {
+    private bool setupComplete;
+
+    protected override async Task OnInitializedAsync() =>
+        setupComplete = await SetupCompletion.IsCompleteAsync(QuerySession);
+}

samples/AndreGoepel.AppFoundation.Sample/Components/Routes.razor

@@ -0,0 +1,23 @@
+@using AndreGoepel.AppFoundation.Components.Layout
+@using AndreGoepel.Marten.Identity.Blazor.Components.Account.Shared
+
+<Router AppAssembly="typeof(Program).Assembly" AdditionalAssemblies="_additionalAssemblies">
+    <Found Context="routeData">
+        <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)">
+            <NotAuthorized>
+                <RedirectToLogin />
+            </NotAuthorized>
+        </AuthorizeRouteView>
+        <FocusOnNavigate RouteData="routeData" Selector="h1" />
+    </Found>
+</Router>
+
+@code {
+    // The routable pages live in the AppFoundation UI and the Marten.Identity account
+    // packages, so the router must scan those assemblies in addition to this host.
+    private readonly System.Reflection.Assembly[] _additionalAssemblies =
+    [
+        typeof(AppFoundationLayoutOptions).Assembly,
+        typeof(AndreGoepel.Marten.Identity.Blazor.Initialization).Assembly,
+    ];
+}

samples/AndreGoepel.AppFoundation.Sample/Components/_Imports.razor

@@ -0,0 +1,16 @@
+@using System.Net.Http
+@using Microsoft.AspNetCore.Components.Authorization
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using static Microsoft.AspNetCore.Components.Web.RenderMode
+@using Microsoft.AspNetCore.Components.Web.Virtualization
+@using Microsoft.JSInterop
+@using AndreGoepel.AppFoundation
+@using AndreGoepel.AppFoundation.Components.Layout
+@using AndreGoepel.AppFoundation.Components.Shared
+@using AndreGoepel.Marten.Identity.Blazor.Components.Account.Shared
+@using AndreGoepel.AppFoundation.Sample
+@using AndreGoepel.AppFoundation.Sample.Components
+@using Radzen
+@using Radzen.Blazor

samples/AndreGoepel.AppFoundation.Sample/Program.cs

@@ -0,0 +1,47 @@
+using AndreGoepel.AppFoundation;
+using AndreGoepel.AppFoundation.Hosting;
+using AndreGoepel.AppFoundation.Sample.Components;
+using AndreGoepel.Marten.Identity.Blazor.Components.Account;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// One call wires the data store, identity, messaging, email, data protection, and the
+// shared request pipeline. The connection string named "appfoundation-database" is
+// supplied by the Aspire AppHost (or Docker secrets in production).
+builder.AddAppFoundation();
+
+builder.Services.AddRazorComponents().AddInteractiveServerComponents();
+
+// Brand the management shell. A real host would also set LogoPath and, optionally, an
+// AdminMenu component to contribute its own administration entries.
+builder.Services.Configure<AppFoundationLayoutOptions>(options =>
+{
+    options.BrandName = "AppFoundation Sample";
+    options.Copyright = $"© {DateTime.UtcNow:yyyy} AppFoundation";
+    // A self-contained placeholder logo so the sample needs no binary asset. A real host
+    // points LogoPath at its own image under wwwroot.
+    options.LogoPath =
+        "data:image/svg+xml;utf8,"
+        + "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'>"
+        + "<rect width='48' height='48' rx='10' fill='%234f46e5'/>"
+        + "<text x='24' y='33' font-size='26' text-anchor='middle' fill='white' "
+        + "font-family='sans-serif'>A</text></svg>";
+});
+
+var app = builder.Build();
+
+app.UseAppFoundation();
+
+app.MapStaticAssets();
+app.MapRazorComponents<App>()
+    .AddInteractiveServerRenderMode()
+    .AddAdditionalAssemblies(
+        // The AppFoundation management UI (layout, setup, dashboard, admin pages) …
+        typeof(AppFoundationLayoutOptions).Assembly,
+        // … and the Marten.Identity account pages (login, register, account management).
+        typeof(AndreGoepel.Marten.Identity.Blazor.Initialization).Assembly
+    );
+
+app.MapAdditionalIdentityEndpoints();
+
+app.Run();

samples/AndreGoepel.AppFoundation.Sample/Properties/launchSettings.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7080;http://localhost:5080",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5080",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

samples/AndreGoepel.AppFoundation.Sample/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

samples/AndreGoepel.AppFoundation.Sample/wwwroot/app.css

@@ -0,0 +1,22 @@
+html, body {
+    margin: 0;
+    font-family: var(--rz-text-font-family, system-ui, sans-serif);
+}
+
+#blazor-error-ui {
+    display: none;
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    padding: 0.75rem 1.25rem;
+    background: #ffe4e4;
+    color: #7a0000;
+    box-shadow: 0 -1px 4px rgba(0, 0, 0, 0.15);
+    z-index: 1000;
+}
+
+#blazor-error-ui .dismiss {
+    cursor: pointer;
+    float: right;
+}