AnthoDingo.Setup 2.1.1

AnthoDingo.Setup

English version

Middleware d'installation « premier démarrage » pour ASP.NET Core.

Tant que l'application n'est pas configurée, toute requête est redirigée vers une page /setup fournie par la bibliothèque (formulaire base de données + compte administrateur). À la validation : test de connexion → migrations/seed → création de l'admin → écriture d'un appsettings.local.json → redémarrage.

• 4 types de base pris en charge : SQL Server, MySQL/MariaDB, PostgreSQL et SQLite (fichier local). L'assistant propose un sélecteur avec les champs adaptés à chaque type ; l'application hôte peut restreindre la liste proposée.
• Détection file-based : aucun appel base de données sur chaque requête.
• Page intégrée hors-ligne : Bootstrap + Bootstrap Icons sont embarqués dans l'assembly et servis sous /setup/_assets/ — aucune dépendance à un CDN ni au wwwroot de l'application.
• Agnostique du DbContext et du modèle utilisateur via l'interface ISetupInitializer.

Cible : net8.0 et net10.0.

Pilotes utilisés

Ces pilotes ne servent qu'à tester la connexion pendant l'installation. Côté application, utilisez le provider EF Core (ou autre ORM) de votre choix — voir le projet d'exemple, qui utilise Microsoft.EntityFrameworkCore.SqlServer, Pomelo.EntityFrameworkCore.MySql (construit sur MySqlConnector), Npgsql.EntityFrameworkCore.PostgreSQL et Microsoft.EntityFrameworkCore.Sqlite.

Utilisation

1. Implémenter ISetupInitializer

public sealed class AppSetupInitializer : ISetupInitializer
{
    public async Task InitializeDatabaseAsync(DbProvider provider, string cs, CancellationToken ct = default)
    {
        await using AppDbContext db = AppDbContext.Create(provider, cs);
        await db.Database.MigrateAsync(ct);
        // … seed des rôles / données de référence
    }

    public async Task CreateAdminAsync(DbProvider provider, string cs, AdminAccount admin, CancellationToken ct = default)
    {
        await using AppDbContext db = AppDbContext.Create(provider, cs);
        // … créer l'utilisateur (Identity PasswordHasher, BCrypt, etc.)
    }
}

// Le DbContext choisit le provider EF Core adapté à la base sélectionnée
// dans l'assistant.
public static class AppDbContextFactory
{
    public static AppDbContext Create(DbProvider provider, string cs)
    {
        var builder = new DbContextOptionsBuilder<AppDbContext>();
        switch (provider)
        {
            case DbProvider.SqlServer: builder.UseSqlServer(cs); break;
            case DbProvider.MySql:     builder.UseMySql(cs, ServerVersion.AutoDetect(cs)); break;
            case DbProvider.Postgres:  builder.UseNpgsql(cs); break;
            case DbProvider.Sqlite:    builder.UseSqlite(cs); break;
        }
        return new AppDbContext(builder.Options);
    }
}

2. Enregistrer et brancher

using AnthoDingo.Setup;

builder.Configuration.AddJsonFile("appsettings.local.json", optional: true);
builder.Services.AddFileBasedSetup<AppSetupInitializer>();

// Pour restreindre les types de base proposés par l'assistant (par défaut : les 4) :
// builder.Services.AddFileBasedSetup<AppSetupInitializer>(o =>
//     o.AllowedProviders = [DbProvider.Postgres, DbProvider.Sqlite]);

var app = builder.Build();

app.UseSetupMiddleware("Mon Application");   // page /setup intégrée

var setup = app.Services.GetRequiredService<SetupService>();
if (setup.IsSetupComplete())
{
    // setup.GetConfiguredProvider() renvoie le DbProvider choisi à l'installation
    // — utile pour reconstruire le bon DbContextOptionsBuilder à chaque démarrage.
}

Pour fournir votre propre page d'installation à la place de la page intégrée, utilisez app.UseSetupGate() (garde seule, sans page).

3. (optionnel) Ajouter des étapes supplémentaires

Une application hôte peut étendre le premier paramétrage en ajoutant ses propres étapes, insérées dans le wizard entre la création du compte administrateur et le redémarrage final (préférences, licence, configuration métier…).

public sealed class CompanySetupStep : ISetupExtraStep
{
    public string Id => "company";
    public string Label => "Societe";

    public Task<string> RenderAsync(SetupExtraStepContext ctx, CancellationToken ct) =>
        Task.FromResult($"""
          <form method="post" action="/setup">
            <input type="hidden" name="step" value="{Id}" />
            <input type="hidden" name="pendingState" value="{ctx.PendingStateToken}" />
            <input type="text" class="form-control" name="companyName" required />
            <button type="submit" class="btn btn-primary w-100">Continuer</button>
          </form>
          """);

    public async Task<SetupExtraStepResult> HandleAsync(SetupExtraStepContext ctx, IFormCollection form, CancellationToken ct)
    {
        string name = form["companyName"].ToString().Trim();
        if (string.IsNullOrWhiteSpace(name))
            return SetupExtraStepResult.Failure("Le nom de la societe est obligatoire.");

        await using AppDbContext db = AppDbContext.Create(ctx.Provider, ctx.ConnectionString);
        db.Settings.Add(new AppSettings { CompanyName = name });
        await db.SaveChangesAsync(ct);
        return SetupExtraStepResult.Success();
    }
}

builder.Services.AddSetupStep<CompanySetupStep>();
// Plusieurs appels s'enchainent dans leur ordre d'enregistrement.

L'étape fournit elle-même son <form> complet (champs + bouton) ; la bibliothèque se charge uniquement de l'habillage (logo, stepper, message d'erreur) et insère automatiquement le libellé (Label) dans le stepper. Comme ISetupInitializer, l'étape est résolue dans un scope dédié : elle peut donc injecter normalement un DbContext ou toute autre dépendance.

Projet d'exemple

src/AnthoDingo.Setup.Example est une application ASP.NET Core minimale (API + EF Core) qui montre l'intégration complète : implémentation d'ISetupInitializer, AppDbContext qui bascule entre les 4 providers EF Core, et branchement du middleware dans Program.cs.

dotnet run --project src/AnthoDingo.Setup.Example

Puis ouvrir /setup : choisir un type de base, tester la connexion, initialiser le schéma, créer le compte administrateur, renseigner le nom de la société (étape supplémentaire de démonstration, voir CompanySetupStep).

API

Breaking change (v2.0.0)

ISetupInitializer.InitializeDatabaseAsync et CreateAdminAsync reçoivent désormais un premier paramètre DbProvider provider, nécessaire pour construire le bon DbContextOptionsBuilder (UseSqlServer/UseMySql/UseNpgsql/UseSqlite) côté application. SetupService.CompleteSetup prend également le provider en paramètre.

Licence

MIT