Skip to content
Purview Dev logo

Enablement: mode, IsEnabled and IsResourceEnabled

ResourceKit decides participation in three ordered steps: the configured mode, the configured IsEnabled flag, and an optional runtime hook.

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 Mode gates the whole host kit: every resource is disabled before it is built.
  • A resource Mode gates that resource only.
  • A resource group’s IsEnabled and Mode gate every kit in the group and in its child groups, in the same step as the host Mode. 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;
}
  • 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 returns IsEnabled, and you override it when enablement should react to runtime conditions that are not a mode (for example a feature flag read from configuration).

At runtime, Build evaluates enablement before resource construction:

  1. The configured Mode is checked first. If it does not participate in this run, IsEnabled becomes false and the hook is never invoked.
  2. If IsEnabled is still true, ResourceKit calls IsResourceEnabled(builder) and assigns the result back to IsEnabled.
  3. If the resulting IsEnabled is false, both BuildResource(...) and ConfigureResource() are skipped for that resource.

Two important consequences:

  • The hook is only invoked when IsEnabled is already true and the mode participates. A kit disabled via IsEnabled=false (for example from options) is never re-enabled by the hook.
  • ResourceBuilder cannot be accessed while the resource is disabled — doing so throws an InvalidOperationException (the property guards itself).

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;

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 Mode excludes 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 IsResourceEnabled hook.
  • 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.

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.