Skip to content
Purview Dev logo

Purview.Aspire.ResourceKit can generate host and resource options types so you can control names and enablement without changing code.

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";

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.

[HostKit]
partial class ShopHostKit
{
public sealed partial class ShopHostKitOptions
{
public bool EnablePreviewResources { get; set; }
}
}
[ResourceDefinition<ProjectResource>("api")]
sealed partial class APIKit
{
partial class APIKitOptions
{
public string PublishEnvironmentVariableName { get; set; } = "PUBLISH_MARKER";
}
}

Tip: keep custom option members public with get; set; so configuration binding can populate them. Data annotations such as [Required] are honored by the generated ValidateOnStart() registration.

  • Access host-level values through HostKit.Options.
  • Access resource-level values through Options in each resource kit.

Example:

protected override void ConfigureResource()
{
if (HostKit.Options.EnablePreviewResources)
{
ResourceBuilder.WithEnvironment(Options.PublishEnvironmentVariableName, "true");
}
}

Typical keys (example):

  • ShopHostKit:API:Name
  • ShopHostKit:API:IsEnabled
  • ShopHostKit:API:Mode
  • ShopHostKit:API:Urls:Health:IsEnabled (a declared [ResourceUrl("Health", ...)])
  • ShopHostKit:Postgres:Database:IsEnabled (a child resource kit)
  • ShopHostKit:Mode
  • ShopHostKit:Groups:Data:IsEnabled, :Mode, :ShowInDashboard (a [ResourceGroup])

Configuration is bound by the generated extension method:

  • Host options bind to ShopHostKitOptions.SectionName (for example ShopHostKit) and ValidateOnStart() 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.

Set IsEnabled=false for that resource’s options section.

{
"ShopHostKit": {
"Redis": {
"IsEnabled": false
}
}
}

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.

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.

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.

Generated options types carry a SectionName constant (for example "ShopHostKit"). When you do not pass a section name explicitly, OptionsHelper resolves it as follows:

  1. const string SectionName on the options type
  2. Type name trimmed by one suffix: Options, Settings, Configuration, Config
  3. 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.