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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Purview.Aspire.ResourceKit" Version="2.2.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Purview.Aspire.ResourceKit" Version="2.2.2" />
                    
Directory.Packages.props
<PackageReference Include="Purview.Aspire.ResourceKit" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Purview.Aspire.ResourceKit --version 2.2.2
                    
#r "nuget: Purview.Aspire.ResourceKit, 2.2.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Purview.Aspire.ResourceKit@2.2.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Purview.Aspire.ResourceKit&version=2.2.2
                    
Install as a Cake Addin
#tool nuget:?package=Purview.Aspire.ResourceKit&version=2.2.2
                    
Install as a Cake Tool

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 with AddDotnetProject (Aspire 17+, DotnetProjectResource only).
  • ResourcePath — the path added by a path-based method: AddDotnetProject, AddViteApp, AddNextJsApp, AddNodeApp, AddBunApp, AddDenoApp or AddJavaScriptApp. SG0042 reports a conflicting ProjectPath, 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:

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 the ResourceKitBase<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;
  • Path is emitted relative and with / separators, because Aspire resolves it from the AppHost project directory.
  • Name defaults to the leaf file/directory name; ClassName overrides the nested type name (PascalCase by default). Two items must not produce the same name (RKP0004).
  • ResourceKitProject is for a .NET project or JavaScript app directory; ResourceKitPath is for any other file or directory. Kind="File"/Kind="Directory" asserts the path's kind (RKP0005, and RKP0006 for an invalid value).
  • A missing path fails the build with RKP0001; set Optional="true" for a path that may be absent.
  • The class is generated into $(RootNamespace) as internal by default. Override ResourceKitAppHostProjectsNamespace, ResourceKitAppHostProjectsClassName or ResourceKitAppHostProjectsVisibility when 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:

  1. Resource kit instantiation from options.
  2. Build for each enabled resource.
  3. Configure for each enabled resource.

This happens before DistributedApplication.Build() completes.

Build/BuildResource vs Configure/ConfigureResource

  • Build calls your BuildResource(IDistributedApplicationBuilder) override to construct the resource.
  • Configure calls your ConfigureResource() 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

  • Mode selects which AppHost execution the kit participates in: All (default), LocalDevelopment, Run, or Publish. It is bound from the generated options (Mode) and declared on the attribute.
  • IsEnabled is the current enablement flag (usually sourced from generated options) and the single member consumers need to check.
  • During Build, ResourceKit evaluates the Mode first, then IsResourceEnabled(builder), and assigns the combined result to IsEnabled.
  • If disabled, both BuildResource(...) and ConfigureResource() 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.
  • IsEnabled can be used to skip a resource at runtime.
  • Mode can be used to restrict a resource (or the whole host) to LocalDevelopment, Run, or Publish.

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.Options for host-level values.
  • Options for 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed