Configuration and options

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

A host options type contains one nested options object per resource.

public class ShopHostKitOptions
{
    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;
}

...

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

Extend host options

[HostKit]
partial class ShopHostKit
{
    public sealed partial class ShopHostKitOptions
    {
        public bool EnablePreviewResources { get; set; }
    }
}

Extend resource options

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

Use extended options at runtime

• 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");
    }
}

Tip: use public + get; set; for bindable properties, and give defaults to keep local/test runs resilient.

Common configuration keys

Typical keys (example):

• ShopHostKit:API:Name
• ShopHostKit:API:IsEnabled

Disable a resource

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

IsEnabled vs IsResourceEnabled(...)

Use both together for flexible control:

• IsEnabled: static/configured toggle (usually generated options).
• IsResourceEnabled(builder): runtime decision hook.

At runtime, Build sets IsEnabled = IsResourceEnabled(builder) first. If the result is false, ResourceKit skips both BuildResource(...) and ConfigureResource() for that resource.

Use this hook to react to runtime state, for example environment-specific availability, publish mode, or dynamic configuration checks.

OptionsHelper for tests and overrides

Use OptionsHelper to generate command-line configuration arguments from strongly typed assignments.

var args = OptionsHelper.Assign<ShopHostKit.ShopHostKitOptions>(
    c => c.API.IsEnabled = false,
    c => c.API.Name = "api-test"
).Build();

Each assignment action must set exactly one property path. To set multiple properties, pass one assignment per property (as above). The compiler reports SG0020 if an action assigns more than one property path, and offers a code fix that splits it into separate assignments.

If you need a property path as a plain string (for example, to build keys or log config), use PathFor with a member selector:

var path = OptionsHelper.PathFor<ShopHostKit.ShopHostKitOptions>(f => f.API.Name);
// "API.Name"

Resulting args are in this form:

• --ShopHostKit:API:IsEnabled=false
• --ShopHostKit:API:Name=api-test

To produce environment variables instead, call AsEnvironmentVariables() before Build():

var envVars = OptionsHelper.Assign<ShopHostKit.ShopHostKitOptions>(
    c => c.API.IsEnabled = false,
    c => c.API.Name = "api-test"
).AsEnvironmentVariables().Build();

This returns a dictionary such as {"ShopHostKit__API__IsEnabled": "false", "ShopHostKit__API__Name": "api-test"}.

Note

This can be useful when using TUnit.Aspire, and passing in Args, e.g.

protected override string[] Args =>
[
   .. base.Args,
   .. OptionsHelper.Assign<ShopHostKit.ShopHostKitOptions>(
     c => c.API.IsEnabled = false,
     c => c.API.Name = "api-test"
   ).Build(),
];

Section-name resolution order

If 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

Tip

Prefer resource-level toggles over conditional host code. It keeps the composition model declarative and testable.