Class ConfigureWebHostBuilderExtensions

Provides configuration-driven Kestrel hosting extensions.

Inheritance
object
ConfigureWebHostBuilderExtensions
Inherited Members
Namespace: Eigenverft.WebLib.Infrastructure.Hosting.Kestrel
Assembly: Eigenverft.WebLib.Infrastructure.dll
Syntax
public static class ConfigureWebHostBuilderExtensions

Methods

| Edit this page View Source

ConfigureKestrelSniFromConfiguration(ConfigureWebHostBuilder, string?, string)

Configures startup-fixed Kestrel listeners and reloadable SNI certificate mappings.

Declaration
public static void ConfigureKestrelSniFromConfiguration(this ConfigureWebHostBuilder configureWebHostBuilder, string? certDirOverride = null, string kestrelSettingsSectionPath = "KestrelSettings")
Parameters
Type Name Description
ConfigureWebHostBuilder configureWebHostBuilder

The web-host builder to configure.
string certDirOverride

An optional certificate-directory override. Relative paths are resolved against the content root.
string kestrelSettingsSectionPath

The configuration section containing startup-fixed Kestrel settings.
Remarks

Add the configuration sources before building the application, then call this method once. For example, reset the implicit appsettings*.json sources and load startup-fixed Kestrel settings separately from reloadable certificate mappings: 

builder.ResetToMinimalConfigurationSources(includeCommandLineArguments: true);

builder.Configuration.AddJsonFile(
Path.Combine(settingsDirectory, "KestrelSettings.json"),
optional: false, reloadOnChange: false);


// Generate a different stable factor for each application.
byte[] applicationFactor =
{
0x23, 0x52, 0x66, 0x37, 0x5A, 0x39, 0x27, 0x27,
0x5E, 0x52, 0x6C, 0x2E, 0x36, 0x49, 0x45, 0x4E,
0x79, 0x4A, 0x52, 0x43, 0x4E, 0x4D, 0x3F, 0x5E,
0x50, 0x5A, 0x6A, 0x5F, 0x4E, 0x32, 0x28, 0x4E,
};


string configurationProtectionSecret =
Environment.GetEnvironmentVariable("APP_CONFIGURATION_PROTECTION_SECRET")
?? throw new InvalidOperationException(
"APP_CONFIGURATION_PROTECTION_SECRET is required.");


ConfigurationValueCodec certificatePasswordCodec =
ConfigurationValueCodecs.Compose(
ConfigurationValueCodecs.AesPassword(applicationFactor),
ConfigurationValueCodecs.AesPassword(configurationProtectionSecret),
ConfigurationValueCodecs.PhysicalMachineBoundAes(),
AspNetDataProtectionConfigurationValueCodecs.DataProtection(
directories, nameof(certificatePasswordCodec)));


var certificateSourceOptions = new SwitchableJsonRegistrationOptions
{
ReloadOnChange = true,
ValueProtection = JsonConfigurationValueProtection.ForPaths(
certificatePasswordCodec, "CertificatesMappingSettings:*:Password"),
};


builder.AddSwitchableJsonFile(
"KestrelCertificateMappings",
Path.Combine(settingsDirectory, "CertificatesMappingSettings.json"),
certificateSourceOptions);


builder.WebHost.ConfigureKestrelSniFromConfiguration(
certDirOverride: directories[DefaultDirectory.ApplicationCerts]);

Minimal KestrelSettings.json:

{
  "KestrelSettings": {
    "HTTP_PORT": 8080,
    "HTTPS_PORT": 8443,
    "ListenScope": "Localhost",
    "AddServerHeader": false,
    "Protocols": "Http1AndHttp2",
    "PreferLongestSuffixMatch": true,
    "TlsProtocolPolicy": "Default"
  }
}

Minimal CertificatesMappingSettings.json:

{
  "CertificatesMappingSettings": [
    {
      "SNI": "localhost",
      "FileName": "localhost.pfx",
      "Password": "change-me"
    }
  ]
}

The certificate-directory override takes precedence over the top-level CertificatesDirectory setting. When neither is supplied, certs below the content root is used.

CertificatesMappingSettings is the only hot-reload boundary. Ports, bind scope, protocols, TLS policy, matching strategy, and certificate directory require a host restart. A failed reload keeps the last-known-good certificate generation active.

Certificate recovery is opt-in. When CertificateRecoveryMode is omitted or invalid, the default None mode performs classic PFX loading: the file must exist, import successfully, contain a private key, and be currently valid. Startup fails when that initial certificate cannot be loaded; a failed hot reload keeps the last-known-good generation active. PreserveExisting enables self-signed recovery only in memory and never creates or replaces the configured PFX path. ReplaceExpired creates a missing managed PFX and replaces an expired one, while ReplaceAnyUnusable is intended only for fully application-managed, replaceable files. Additional self-signed DNS names and IP addresses are used only when a recovery mode generates a self-signed certificate.