Enablement: mode, IsEnabled and IsResourceEnabled
ResourceKit decides participation in three ordered steps: the configured mode, the configured
IsEnabled flag, and an optional runtime hook.
Run modes
Section titled “Run modes”ResourceKitMode selects which AppHost execution a host kit or resource kit participates in. It is a
kit option, so participation is selected from configuration instead of coded into an
IsResourceEnabled override.
| Mode | Participates when | Typical use |
|---|---|---|
All (default) |
always | most resources |
LocalDevelopment |
run mode and the Development environment |
a documentation site, a diagram site |
Run |
run mode, any environment | tooling that must not be published |
Publish |
publish mode (aspire publish / azd) |
Azure Application Insights, a container apps environment, Key Vault, publish parameters |
The mode can be declared on the attribute, which sets the default for the generated options:
[HostKit]sealed partial class ShopHostKit;
// Constructor argument.[ResourceDefinition<AzureKeyVaultResource>("kv", ResourceKitMode.Publish)]sealed partial class KeyVaultKit;
// Named property.[ResourceDefinition<ParameterResource>(Mode = ResourceKitMode.Publish)]sealed partial class PublishMarkerKit;Because it is an option, configuration can override either the host-wide mode or a single resource:
{ "ShopHostKit": { "Mode": "All", "KeyVault": { "Mode": "Publish" }, "DocsSite": { "Mode": "LocalDevelopment" } }}- The host
Modegates the whole host kit: every resource is disabled before it is built. - A resource
Modegates that resource only. - A resource group’s
IsEnabledandModegate every kit in the group and in its child groups, in the same step as the hostMode. See Groups and URLs.
An excluded kit never runs BuildResource(...) or ConfigureResource(). Its host property is still
constructed (so HostKit.KeyVault is non-null), but IsEnabled is false and any ResourceBuilder
access throws InvalidOperationException — always check IsEnabled first, exactly as for a kit
disabled through options.
Manual (non-generated) kits express the same behaviour by overriding the Mode property:
sealed partial class KeyVaultKit(ShopHostKit hostKit) : ResourceKitBase<ShopHostKit, AzureKeyVaultResource>(hostKit, "kv"){ protected override ResourceKitMode Mode => ResourceKitMode.Publish;}The two toggles
Section titled “The two toggles”IsEnabled— the current enablement flag, usually sourced from generated options. This is the persisted/configured toggle, and the only member consumers need to check.IsResourceEnabled(builder)— a runtime decision hook. Its default implementation returnsIsEnabled, and you override it when enablement should react to runtime conditions that are not a mode (for example a feature flag read from configuration).
How they interact
Section titled “How they interact”At runtime, Build evaluates enablement before resource construction:
- The configured
Modeis checked first. If it does not participate in this run,IsEnabledbecomesfalseand the hook is never invoked. - If
IsEnabledis stilltrue, ResourceKit callsIsResourceEnabled(builder)and assigns the result back toIsEnabled. - If the resulting
IsEnabledisfalse, bothBuildResource(...)andConfigureResource()are skipped for that resource.
Two important consequences:
- The hook is only invoked when
IsEnabledis alreadytrueand the mode participates. A kit disabled viaIsEnabled=false(for example from options) is never re-enabled by the hook. ResourceBuildercannot be accessed while the resource is disabled — doing so throws anInvalidOperationException(the property guards itself).
When to override IsResourceEnabled
Section titled “When to override IsResourceEnabled”Use the hook when enablement depends on runtime state that is not an execution mode. Common examples are environment-specific feature flags or dynamic configuration checks.
protected override bool IsResourceEnabled(IDistributedApplicationBuilder builder){ // Example: allow config + feature flag based behavior. var isEnabledInConfig = IsEnabled; var isFeatureEnabled = builder.Configuration["Features:KeyVault"] == "true";
return isEnabledInConfig && isFeatureEnabled;}Publish-only resources no longer need a hook; declare the mode instead:
[ResourceDefinition<AzureKeyVaultResource>("kv", ResourceKitMode.Publish)]sealed partial class KeyVaultKit;Parent and child kits
Section titled “Parent and child kits”A child kit is enabled only when every ancestor is enabled as well as its own gates:
EffectiveEnabled(child) = EffectiveEnabled(parent) AND ChildConfiguredEnabled AND ChildModeEnabled AND ChildResourceEnabled- Disabling a parent disables every descendant, even when the child’s options say
IsEnabled = true. - A parent excluded by its
Modeexcludes descendants. - A child excluded by its own mode or hook leaves the parent and eligible siblings unaffected.
- An ancestor-disabled kit never invokes a descendant’s
IsResourceEnabledhook. - Siblings are independent.
IsEnabled remains the configured value before Build and the effective value afterwards. Use
ConfiguredIsEnabled and EffectiveIsEnabled when code needs both explicitly. Accessing ResourceBuilder
of a disabled, unbuilt or failed kit throws InvalidOperationException.
See Parent and child resource kits for the complete rules.
Disabling a resource from options
Section titled “Disabling a resource from options”Because IsEnabled is bound from generated options, a resource can be disabled without code changes
by setting the options section in configuration:
{ "ShopHostKit": { "Redis": { "IsEnabled": false } }}See Configuration and Options for the generated options shape.