Purview.Aspire.ResourceKit
2.2.2
dotnet add package Purview.Aspire.ResourceKit --version 2.2.2
NuGet\Install-Package Purview.Aspire.ResourceKit -Version 2.2.2
<PackageReference Include="Purview.Aspire.ResourceKit" Version="2.2.2" />
<PackageVersion Include="Purview.Aspire.ResourceKit" Version="2.2.2" />
<PackageReference Include="Purview.Aspire.ResourceKit" />
paket add Purview.Aspire.ResourceKit --version 2.2.2
#r "nuget: Purview.Aspire.ResourceKit, 2.2.2"
#:package Purview.Aspire.ResourceKit@2.2.2
#addin nuget:?package=Purview.Aspire.ResourceKit&version=2.2.2
#tool nuget:?package=Purview.Aspire.ResourceKit&version=2.2.2
Purview.Aspire.ResourceKit (NuGet package)
This package contains the runtime abstractions and source-generator contracts for building Aspire AppHost resources using strongly typed classes.
Use this README when integrating the Purview.Aspire.ResourceKit NuGet package into your host project.
Requires .NET 10. The package ships lib/net10.0 and lib/net11.0 assets — there is no
net8.0 or net9.0 target to fall back to. A .NET 10 AppHost resolves the net10.0 asset; a
.NET 11 AppHost resolves the net11.0 asset.
Package goals
- Keep AppHost resource composition explicit and testable.
- Generate repetitive registration/configuration code from attributes.
- Provide strongly typed options for host and resource toggles.
Public attributes
HostKitAttribute ([HostKit])
Marks the single host kit class per compilation.
[HostKit]
sealed partial class ShopHostKit;
Optional named arguments:
Name— controls generated naming.ExtensionMethodName— overrides generated builder extension name.GenerateOptions— enables/disables generated host options.
ResourceDefinitionAttribute ([ResourceDefinition])
Marks a resource kit class that participates in generation.
[ResourceDefinition<ProjectResource>("api", PropertyName = "API")]
partial class APIResourceKit;
Options:
Name— logical Aspire resource name.PropertyName— generated host or parent property name.Parent—typeof(TParentKit)when this kit is owned by another resource kit.ProjectPath— the path added withAddDotnetProject(Aspire 17+,DotnetProjectResourceonly).ResourcePath— the path added by a path-based method:AddDotnetProject,AddViteApp,AddNextJsApp,AddNodeApp,AddBunApp,AddDenoApporAddJavaScriptApp. SG0042 reports a conflictingProjectPath, and SG0043 reports a resource type that is not added by path.
With a declared path and no BuildResource override, a DotnetProjectResource, ViteAppResource or
NextJsAppResource kit gets BuildResource generated, so the path is stated once. When you write the
override yourself, SG0018 checks that it adds the declared path, and SG0044 reports one that only
repeats the generated call.
ResourceDefinition vs ResourceDefinition<TResource>
ResourceKit supports two declaration styles, with different base-type behavior:
Generic attribute (recommended)
Use [ResourceDefinition<TResource>] when you want the resource type declared directly on the attribute.
[ResourceDefinition<ProjectResource>("api")]
partial class APIResourceKit
{
protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder)
=> builder.AddProject<Projects.Example_Service>(Name);
}
- Do not declare an explicit base type on the class.
- The generator supplies the host-specific base in generated partial code.
Non-generic attribute
Use [ResourceDefinition] when you prefer (or need) to specify the resource type through an explicit base type.
[ResourceDefinition("api")]
partial class APIResourceKit : ResourceKitBase<ProjectResource>
{
protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder)
=> builder.AddProject<Projects.Example_Service>(Name);
}
- You must declare an explicit valid base type.
- Typically this is the generated host-specific base (
ResourceKitBase<TResource>, unlike theResourceKitBase<THostKit, TResource>that takes the explicit Host Kit as a construction parameter).
Do not mix both attribute styles on the same class.
Parent and child kits
Parent = typeof(TParentKit) gives the child a typed Parent property and the parent a typed child
property. Parents are constructed and built before children, so Parent is available inside
the child's BuildResource:
[ResourceDefinition<AzurePostgresFlexibleServerDatabaseResource>(
"db", PropertyName = "Database", Parent = typeof(PostgresKit))]
sealed partial class PostgresDatabaseKit
{
protected override IResourceBuilder<AzurePostgresFlexibleServerDatabaseResource>
BuildResource(IDistributedApplicationBuilder builder) =>
Parent.AddDatabase(Name);
}
Child options nest under the parent (<HostKit>:<Parent>:<Child>). Disabling a parent disables every
descendant, and a child with no [InGroup] inherits its parent's primary group. This is composition
ownership, not a general dependency or an automatic Aspire visual parent relationship.
Resource groups and dashboard URLs
[ResourceGroup] marks a partial class as a named, nestable group ([ResourceGroup<TParent>] or
Parent = typeof(TParent)), and
[InGroup<TGroup>] adds a resource kit to it. A group can be switched off or given a Mode from
<HostKit>:Groups:<Group>, which applies to every kit in it. In run mode each group appears as a
dashboard node with its kits nested underneath.
[ResourceUrl(name, url)] adds a named dashboard URL: absolute, or relative to an endpoint.
[EndpointUrl(endpoint)] renames an endpoint's own URL. Each URL becomes a ResourceKitUrl option under
<HostKit>:<Kit>:Urls:<Name>.
[ResourceGroup("data")]
sealed partial class DataGroup;
[ResourceDefinition<ProjectResource>("api")]
[InGroup<DataGroup>]
[ResourceUrl("Health", "/health", DisplayText = "Health")]
[EndpointUrl("https", DisplayText = "API")]
partial class APIResourceKit { /* ... */ }
Typed project and app paths
Aspire's Projects.* metadata only covers projects referenced with <ProjectReference>, and a
Project V2 AppHost adds its services by path instead. Non-.NET apps (AddViteApp, AddNpmApp) never
had a typed reference at all. Declare them once and let the package generate AppHostProjects:
<ItemGroup>
<ResourceKitProject Include="..\..\dotnet-project" Name="api" />
<ResourceKitProject Include="..\..\..\web\packages\vite-app" Name="web" />
<ResourceKitPath Include="..\..\deploy\Dockerfile" Name="dockerfile" Kind="File" />
</ItemGroup>
// Both BuildResource overrides are generated from the declared path.
[ResourceDefinition<DotnetProjectResource>(AppHostProjects.Api.Name, ProjectPath = AppHostProjects.Api.Path)]
partial class ApiResourceKit;
[ResourceDefinition<ViteAppResource>(AppHostProjects.Web.Name, ResourcePath = AppHostProjects.Web.Path)]
partial class WebResourceKit;
Pathis emitted relative and with/separators, because Aspire resolves it from the AppHost project directory.Namedefaults to the leaf file/directory name;ClassNameoverrides the nested type name (PascalCase by default). Two items must not produce the same name (RKP0004).ResourceKitProjectis for a .NET project or JavaScript app directory;ResourceKitPathis for any other file or directory.Kind="File"/Kind="Directory"asserts the path's kind (RKP0005, andRKP0006for an invalid value).- A missing path fails the build with
RKP0001; setOptional="true"for a path that may be absent. - The class is generated into
$(RootNamespace)asinternalby default. OverrideResourceKitAppHostProjectsNamespace,ResourceKitAppHostProjectsClassNameorResourceKitAppHostProjectsVisibilitywhen needed.
The class comes from a buildTransitive MSBuild target, not the source generator, so it is available
even when DisablePurviewAspireResourceKitSourceGenerator is set. It is a C# AppHost feature: F#/VB
projects fail with RKP0007, and TypeScript (apphost.mts) and Go (apphost.go) AppHosts are served
by the Aspire CLI's generated SDK modules instead.
Minimal package usage
using Aspire.Hosting;
using Aspire.Hosting.ApplicationModel;
using Purview.Aspire.ResourceKit;
[HostKit]
partial class ShopHostKit;
[ResourceDefinition<ProjectResource>("api")]
partial class APIResourceKit
{
protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder)
=> builder.AddProject<Projects.Example_Service>(Name);
}
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAspireResourceKit();
Generated output (high level)
From your attributed partial classes, the generator emits:
- a resource kit base type (
ResourceKitBase<TResource>), - host members for each resource definition,
- generated options types (when enabled),
- a builder extension method for registration and lifecycle execution.
Runtime lifecycle
When the generated extension is invoked, ResourceKit performs:
- Resource kit instantiation from options.
Buildfor each enabled resource.Configurefor each enabled resource.
This happens before DistributedApplication.Build() completes.
Build/BuildResource vs Configure/ConfigureResource
Buildcalls yourBuildResource(IDistributedApplicationBuilder)override to construct the resource.Configurecalls yourConfigureResource()override to attach resources to each other after construction.
This separation keeps creation and cross-resource wiring explicit and deterministic.
How Mode, IsEnabled and IsResourceEnabled(...) interact
Modeselects which AppHost execution the kit participates in:All(default),LocalDevelopment,Run, orPublish. It is bound from the generated options (Mode) and declared on the attribute.IsEnabledis the current enablement flag (usually sourced from generated options) and the single member consumers need to check.- During
Build, ResourceKit evaluates theModefirst, thenIsResourceEnabled(builder), and assigns the combined result toIsEnabled. - If disabled, both
BuildResource(...)andConfigureResource()are skipped for that resource.
Use Mode for publish-only or local-development-only resources. Override IsResourceEnabled(builder)
when enablement should react to runtime state beyond an execution mode.
Options and configuration
When options are generated:
- Host options root section is the generated host options type name (or configured section).
- Resource options are nested by generated resource property name.
IsEnabledcan be used to skip a resource at runtime.Modecan be used to restrict a resource (or the whole host) toLocalDevelopment,Run, orPublish.
See detailed configuration and options patterns.
Extending generated typed options
Generated host and resource options are sealed partial nested classes. You can safely extend them by adding matching partial declarations in your own code.
Host options extension example:
[HostKit]
partial class ExampleHostKit
{
public sealed partial class ExampleHostKitOptions
{
public bool EnablePreviewResources { get; set; }
}
}
Resource options extension example:
[ResourceDefinition<ProjectResource>("api")]
sealed partial class ExampleAPIKit
{
partial class ExampleAPIKitOptions
{
public string PublishEnvironmentVariableName { get; set; } = "PUBLISH_MARKER";
}
}
Use these values through generated properties:
HostKit.Optionsfor host-level values.Optionsfor each resource kit instance.
OptionsHelper (tests and CLI args)
OptionsHelper converts typed assignment expressions into command-line configuration args:
var args = OptionsHelper.Assign<ExampleHostKit.ExampleHostKitOptions>(
c => c.Redis.IsEnabled = false,
c => c.Redis.Name = "dev-redis"
).Build();
Each assignment action must set exactly one property path. If you need a property path as a plain string (for example, for logging or string building), use PathFor with a member selector:
var path = OptionsHelper.PathFor<ExampleHostKit.ExampleHostKitOptions>(f => f.Redis.Name);
// "Redis.Name"
Produces values like:
--ExampleHostKit:Redis:IsEnabled=false--ExampleHostKit:Redis:Name=dev-redis
Switch to environment variables with AsEnvironmentVariables():
var envVars = OptionsHelper.Assign<ExampleHostKit.ExampleHostKitOptions>(
c => c.Redis.IsEnabled = false
).AsEnvironmentVariables().Build();
Useful for integration-test fixtures and scenario toggles.
If you already have a populated options object, use OptionsHelper.Environment(...) and optional
Override(...) / Ignore(...) calls to flatten it into ASP.NET Core binder-style environment
variables.
Diagnostics
| ID | Severity | Description |
|---|---|---|
| SG0001 | Error | Class must be partial |
| SG0002 | Info | No resources defined for the host kit |
| SG0003 | Warning | No host kit defined (but resources exist) |
| SG0004 | Error | Multiple [HostKit] classes defined |
| SG0005 | Error | Duplicate resource property name |
| SG0006 | Error | Resource must derive from expected generated base |
| SG0007 | Error | Resource name could not be derived and no Name was specified |
| SG0008 | Error | Explicit PropertyName is not a valid C# identifier |
| SG0009 | Error | Missing IServiceCollection type dependency |
| SG0010 | Error | Missing configuration binder dependency |
| SG0011 | Error | Missing options configuration extensions dependency |
| SG0012 | Error | Non-empty constructors are not supported on attributed classes |
| SG0013 | Error | Mixed ResourceDefinition and ResourceDefinition<TResource> on the same class is not supported |
| SG0014 | Error | Non-generic ResourceDefinition requires an explicit compatible base type |
| SG0015 | Error | Generic ResourceDefinition<TResource> must not declare an explicit base type |
| SG0016 | Error | No Aspire resource type could be inferred/found |
| SG0017 | Warning | IResourceBuilder<T> property never assigned in BuildResource/ConfigureResource (execution-only) |
| SG0018 | Warning | Project resource kit does not add the declared project via AddProject<T>() (execution-only) |
| SG0019 | Warning | Project resource kit explicit base does not use ProjectResource (execution-only) |
| SG0020 | Error | OptionsHelper.Assign action sets more than one property path |
| SG0021 | Error | [InGroup<TGroup>] type or group Parent is not a [ResourceGroup] class |
| SG0022 | Error | Resource group parent cycle |
| SG0023 | Error | Duplicate resource group name |
| SG0024 | Warning | More than one primary group on a resource kit (execution-only) |
| SG0025 | Error | Resource group declares a base type |
| SG0026 | Error | Duplicate URL name on a resource kit or group |
| SG0027 | Error | Endpoint URL on a resource or group without endpoints |
| SG0028 | Warning | Relative URL on a resource or group without endpoints (execution-only) |
| SG0029 | Error | Resource group declares its parent more than once |
| SG0030 | Error | Resource group is generic |
| SG0031 | Error | Resource group is also a resource kit or a group member |
| SG0032 | Error | A resource kit declares itself as its parent |
| SG0033 | Error | Resource kit parent cycle; the message prints the path |
| SG0034 | Error | Parent type is not a resource kit |
| SG0035 | Error | Parent is not part of this host kit composition |
| SG0036 | Error | Generated child property collides with a member on the parent |
| SG0037 | Error | Duplicate child property name under one parent |
| SG0038 | Error | Generated Parent member collides with a user-authored member |
| SG0039 | Warning | Child primary group differs from its parent's; visual placement follows the child's group |
| SG0040 | Info | A resource kit is already an IResourceBuilder<TResource>; .ResourceBuilder is redundant |
| SG0041 | Warning | ProjectPath is set on a resource that is not a DotnetProjectResource |
| SG0042 | Warning | ProjectPath and ResourcePath declare different paths; ResourcePath is used |
| SG0043 | Warning | ResourcePath is set on a resource that is not added by path |
| SG0044 | Info | BuildResource only repeats the registration ResourceKit generates; the code fix removes it |
| RKP0001 | Error | A ResourceKitProject/ResourceKitPath path does not exist relative to the AppHost project directory |
| RKP0002 | Error | A ResourceKitProject/ResourceKitPath class name is not a valid C# identifier |
| RKP0003 | Error | A ResourceKitProject/ResourceKitPath resource name contains an unsupported character |
| RKP0004 | Error | Two items generate the same AppHostProjects nested class name |
| RKP0005 | Error | Kind="File" resolves to a directory, or Kind="Directory" resolves to a file |
| RKP0006 | Error | Kind is set to a value other than File or Directory |
| RKP0007 | Error | ResourceKitProject/ResourceKitPath are declared in a project that is not a C# AppHost |
RKP errors are MSBuild errors raised when AppHostProjects is generated; they are not SG analyzer
diagnostics and fire before compilation.
SG0017–SG0019, SG0024, SG0028, SG0042 and SG0043 are execution-only warnings: they indicate the resource will fail at runtime but never
block generation, so a resource kit with incomplete wiring (for example a project not yet added via
AddProject<T>()) is still generated and the host kit output is still emitted.
For troubleshooting guidance, see the diagnostics reference.
Documentation
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Aspire.Hosting (>= 13.6.5)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Options (>= 10.0.15)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.15)
- Microsoft.Extensions.Telemetry.Abstractions (>= 10.11.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.20.1)
- OpenTelemetry.Extensions.Hosting (>= 1.20.1)
-
net11.0
- Aspire.Hosting (>= 13.6.5)
- Microsoft.Extensions.DependencyInjection (>= 10.0.15)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.15)
- Microsoft.Extensions.Telemetry.Abstractions (>= 10.11.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.20.1)
- OpenTelemetry.Extensions.Hosting (>= 1.20.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.2.2 | 0 | 11/20/2026 |
| 2.2.1 | 0 | 11/20/2026 |
| 2.2.0 | 14 | 11/19/2026 |
| 2.1.0 | 45 | 11/19/2026 |
| 2.0.0 | 67 | 11/16/2026 |
| 2.0.0-prerelease.1 | 71 | 11/12/2026 |
| 1.1.0 | 170 | 11/8/2026 |
| 1.0.3 | 174 | 10/27/2026 |
| 1.0.2 | 149 | 10/22/2026 |
| 1.0.1 | 120 | 10/16/2026 |
| 1.0.0.1 | 123 | 10/7/2026 |
| 1.0.0 | 117 | 9/29/2026 |
| 1.0.0-prerelease.41 | 99 | 9/28/2026 |
| 1.0.0-prerelease.40 | 103 | 9/27/2026 |
| 1.0.0-prerelease.39 | 81 | 9/25/2026 |
| 1.0.0-prerelease.38 | 76 | 9/25/2026 |
| 1.0.0-prerelease.37 | 76 | 9/24/2026 |
| 1.0.0-prerelease.36 | 81 | 9/23/2026 |
| 1.0.0-prerelease.35 | 93 | 9/23/2026 |
| 1.0.0-prerelease.34 | 72 | 9/23/2026 |