Configuration and options
Purview.Aspire.ResourceKit can generate host and resource options types so you can control names and
enablement without changing code.
Generated options shape
Section titled “Generated options shape”A host options type contains one nested options object per resource.
public class ShopHostKitOptions{ public const string SectionName = "ShopHostKit";
public ResourceKitMode Mode { get; set; } = ResourceKitMode.All;
public APIKitOptions Api { get; set; } = new(); public RedisKitOptions Redis { get; set; } = new();}
public class APIKitOptions{ public string Name { get; set; } = "api";
public bool IsEnabled { get; set; } = true;
public ResourceKitMode Mode { get; set; } = ResourceKitMode.All;}
...The generated host options type exposes a SectionName constant that is used to bind configuration:
public const string SectionName = "ShopHostKit";Child resource kits
Section titled “Child resource kits”When a kit declares Parent = typeof(TParentKit), only roots are top-level host options. Children nest under
the parent’s options, so the configuration path mirrors the ownership hierarchy:
{ "ShopHostKit": { "Postgres": { "IsEnabled": true, "Database": { "IsEnabled": true, "Name": "db" } } }}public sealed partial class PostgresKitOptions{ public bool IsEnabled { get; set; } = true;
public PostgresDatabaseKit.PostgresDatabaseKitOptions Database { get; init; } = new();}OptionsHelper resolves the nested path (ShopHostKit:Postgres:Database:IsEnabled). Existing root paths are
unchanged. See Parent and child resource kits.
Generated options are emitted as nested sealed partial classes. You can extend both host and resource
option types with custom properties.
Extend host and resource typed options
Section titled “Extend host and resource typed options”Extend host options
Section titled “Extend host options”[HostKit]partial class ShopHostKit{ public sealed partial class ShopHostKitOptions { public bool EnablePreviewResources { get; set; } }}Extend resource options
Section titled “Extend resource options”[ResourceDefinition<ProjectResource>("api")]sealed partial class APIKit{ partial class APIKitOptions { public string PublishEnvironmentVariableName { get; set; } = "PUBLISH_MARKER"; }}Tip: keep custom option members
publicwithget; set;so configuration binding can populate them. Data annotations such as[Required]are honored by the generatedValidateOnStart()registration.
Use extended options at runtime
Section titled “Use extended options at runtime”- Access host-level values through
HostKit.Options. - Access resource-level values through
Optionsin each resource kit.
Example:
protected override void ConfigureResource(){ if (HostKit.Options.EnablePreviewResources) { ResourceBuilder.WithEnvironment(Options.PublishEnvironmentVariableName, "true"); }}Common configuration keys
Section titled “Common configuration keys”Typical keys (example):
ShopHostKit:API:NameShopHostKit:API:IsEnabledShopHostKit:API:ModeShopHostKit:API:Urls:Health:IsEnabled(a declared[ResourceUrl("Health", ...)])ShopHostKit:Postgres:Database:IsEnabled(a child resource kit)ShopHostKit:ModeShopHostKit:Groups:Data:IsEnabled,:Mode,:ShowInDashboard(a[ResourceGroup])
Configuration is bound by the generated extension method:
- Host options bind to
ShopHostKitOptions.SectionName(for exampleShopHostKit) andValidateOnStart()is called. - Resource options are nested by generated resource property name.
- Group options are nested under
Groups, by group property name. See Groups and URLs.
Disable a resource
Section titled “Disable a resource”Set IsEnabled=false for that resource’s options section.
{ "ShopHostKit": { "Redis": { "IsEnabled": false } }}Select a run mode
Section titled “Select a run mode”Resource kits (and their host kit) expose a Mode option that selects which AppHost execution they
participate in. It defaults to All, so nothing changes unless you opt in.
| Mode | Participates when |
|---|---|
All (default) |
always |
LocalDevelopment |
run mode and the Development environment |
Run |
run mode, any environment |
Publish |
publish mode (aspire publish / azd) |
The attribute sets the default, and configuration can override it:
[ResourceDefinition<AzureKeyVaultResource>("kv", ResourceKitMode.Publish)]sealed partial class KeyVaultKit;{ "ShopHostKit": { "Mode": "All", "KeyVault": { "Mode": "Publish" }, "DocsSite": { "Mode": "LocalDevelopment" } }}The host Mode gates every resource in the host kit; a resource Mode gates only that resource.
See Enablement for the evaluation order.
IsEnabled vs IsResourceEnabled(...)
Section titled “IsEnabled vs IsResourceEnabled(...)”Use both together for flexible control:
IsEnabled: static/configured toggle (usually generated options), and the only member consumers need to check.IsResourceEnabled(builder): runtime decision hook.
At runtime, Build evaluates the configured Mode first, then calls IsResourceEnabled(builder) when
IsEnabled is already true. If either gate excludes the kit, ResourceKit skips both BuildResource(...)
and ConfigureResource() for that resource. A kit disabled via IsEnabled=false is never re-enabled by
the hook.
See Enablement for details.
OptionsHelper for tests and overrides
Section titled “OptionsHelper for tests and overrides”For tests and scenario toggles, OptionsHelper converts typed assignments into command-line arguments
or environment variables. It can also flatten a populated options object into ASP.NET Core binder-style
environment variables:
var args = OptionsHelper.Assign<ShopHostKit.ShopHostKitOptions>( c => c.API.IsEnabled = false, c => c.API.Name = "api-test").Build();See OptionsHelper for the complete API, including PathFor, SectionNameFor, and
the SG0020 single-property-path rule.
For resource wiring, IResourceBuilder.WithEnvironment(options) now accepts a populated options object
and emits environment variables using the same binder-style key convention.
Section-name resolution
Section titled “Section-name resolution”Generated options types carry a SectionName constant (for example "ShopHostKit"). When you do not
pass a section name explicitly, OptionsHelper resolves it as follows:
const string SectionNameon the options type- Type name trimmed by one suffix:
Options,Settings,Configuration,Config - Original type name
You can look up the resolved section name with
OptionsHelper.SectionNameFor.
Prefer resource-level toggles over conditional host code. It keeps the composition model declarative and testable.