Configo.Design 1.1.3

Configo.Design

Design-time support for Configo.

This package enables the configo schema generate dotnet tool to introspect your application's DI container and produce an appsettings.schema.json file with accurate JSON schema definitions for all your configuration sections.

How it works

Configo.Design registers a hosted service that is a no-op during normal application startups. It only activates when the application is launched by the configo schema generate tool (i.e., when the CONFIGO_GENERATING_SCHEMA=true environment variable is set).

When activated, the service discovers all bound configuration sections and writes a lightweight bindings manifest (a temp JSON file) that tells the tool which CLR types are bound to which configuration section names. It then stops the application. The tool generates a throwaway project that runs on your application's own runtime (referencing your compiled output, the ASP.NET Core shared framework, and the Configo.Design.Generation package) and produces the full JSON schema using NJsonSchema there. The application itself never references NJsonSchema.

Descriptions come from XML documentation. Enable <GenerateDocumentationFile>true</GenerateDocumentationFile> in your project so your <summary> comments become schema descriptions — this is most of a schema's value.

Supported runtimes. Schema generation currently supports net10.0 applications; support for more runtimes is planned.

Installation

<PackageReference Include="Configo.Design">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Why PrivateAssets=all? This is a design-time dependency — it is only needed when running the configo schema generate tool, not during normal application execution. Using PrivateAssets=all prevents Configo.Design from flowing transitively to any project that references yours as a library.

Usage

In your Program.cs, register the schema generator alongside your other services:

// This is a no-op unless run under `configo schema generate`.
builder.Services.AddConfigoDesign();

Then run the tool from your project directory:

dotnet configo schema generate
dotnet configo schema generate --output ./appsettings.schema.json

Configuration options

AddConfigoDesign() accepts an optional callback to configure ConfigoDesignOptions:

builder.Services.AddConfigoDesign(options =>
{
    // Customize the description generated for each connection string in the schema.
    // The {name} placeholder is replaced with the connection string name.
    options.ConnectionStringDescriptionTemplate =
        "A valid connection string to the {name} database.";

    // Map connection string names that arrive via environment variables in upper case
    // back to a preferred casing in the schema (matched case-insensitively).
    options.ConnectionStringCanonicalCasings = new Dictionary<string, string>
    {
        ["MINIPROFILER"] = "MiniProfiler",
    };

    // Exclude noisy / unhelpful property types from the generated schema by full type name.
    options.AdditionalTypesToIgnore = new HashSet<string>
    {
        "MyApp.Security.RawCertificateBytes",
    };

    // X509Certificate2 and X509Certificate2Collection are ignored by default.
    // Set this to false to include them in the generated schema.
    options.IgnoreCertificateTypesByDefault = false;
});

Skipping database migrations during schema generation

When running under the tool, you may want to skip startup work (like EF Core migrations) that requires a live database. Use ConfigoDesignEnvironment.IsActive to guard it:

if (!ConfigoDesignEnvironment.IsActive)
{
    await app.Services.MigrateAsync();
}

Exiting cleanly under the tool

When the tool runs your app, Configo.Design writes the bindings manifest and then calls StopApplication() to stop the host mid-startup. Most apps shut down cleanly at this point. However, some hosts surface this early shutdown as a non-zero process exit code — for example, Kestrel can rethrow a cancellation from BindAsync, or a custom "fatal error" wrapper might rethrow on cancellation.

The tool prefers the manifest over the exit code: if a manifest was freshly written by the current run, schema generation proceeds even when the app exited non-zero (a warning is printed). A stale manifest left over from a previous run is never reused.

If your host treats the design-time shutdown as a hard failure, guard it so the cancellation is non-fatal while generating the schema:

try
{
    await app.RunAsync();
}
catch (OperationCanceledException) when (ConfigoDesignEnvironment.IsActive)
{
    // Expected: Configo.Design stopped the host mid-startup to collect bindings.
}