Documentation section: Concepts
Project resources
ResourceKit supports both Aspire project resource models, with generator and analyzer validation to catch wiring mistakes:
| Aspire | Registration | Declaration |
|---|---|---|
| 17+ (Project V2) | AddDotnetProject(name, path), generated from ProjectPath |
[ResourceDefinition<DotnetProjectResource>(ProjectPath = "...")] |
| 13.6 (legacy) | AddProject<TProject>() |
[ResourceDefinition<Projects.MyService>] |
The V2 form is the one to use for an Aspire 17 AppHost. The package declares the 13.6 floor, so a 13.6
consumer never has to reference Aspire.Hosting.Dotnet.
Aspire 17 Project V2
Section titled “Aspire 17 Project V2”Declare the project path on the attribute. That is the only place it needs to be stated:
using Aspire.Hosting.Dotnet;using Purview.Aspire.ResourceKit;
[ResourceDefinition<DotnetProjectResource>("api", ProjectPath = "../Example.Service/Example.Service.csproj")]partial class ApiResourceKit;The generator emits ResourceKitBase<THostKit, DotnetProjectResource> and, because the kit writes no
BuildResource, the registration as well:
protected override IResourceBuilder<DotnetProjectResource> BuildResource(IDistributedApplicationBuilder builder) => global::Aspire.Hosting.DotnetProjectHostingExtensions.AddDotnetProject(builder, Name, "../Example.Service/Example.Service.csproj");DotnetProjectResource implements IResourceWithEndpoints and IResourceWithEnvironment, so URLs,
references and WithEnvironment work as they do for any other resource. Put that configuration in
ConfigureResource, which leaves the generated BuildResource in place.
Writing BuildResource yourself
Section titled “Writing BuildResource yourself”Write the override when registration needs more than the name and path, such as the configure
callback of AddDotnetProject or a fluent call on the result. ResourceKit then generates nothing, and
SG0018 checks that your override adds the declared path:
[ResourceDefinition<DotnetProjectResource>("api", ProjectPath = "../Example.Service/Example.Service.csproj")]partial class ApiResourceKit{ protected override IResourceBuilder<DotnetProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddDotnetProject(Name, "../Example.Service/Example.Service.csproj").WithHttpEndpoint();}An override that only repeats the generated call, builder.AddDotnetProject(Name, path), reports
SG0044 (info). Its code fix deletes the override. If the attribute doesn’t declare the path yet,
the fix first moves the path argument into ProjectPath, so the attribute becomes the one place the
path is stated. A literal moves as written. A constant such as AppHostProjects.Api.Path moves as a
reference to that constant.
The override is never generated when a base class already implements BuildResource, or for the
legacy Projects.* form, which has no path.
ProjectPath is a named argument on both [ResourceDefinition] and
[ResourceDefinition<TResource>]. It is a build-time declaration, not a bindable option.
ResourcePath is the general form and also covers JavaScript app resources; see
JavaScript app paths.
The declared path must be added (SG0018)
Section titled “The declared path must be added (SG0018)”A hand-written BuildResource must call AddDotnetProject with the declared path. A generated one
always does, so SG0018 only applies when you write the override. The comparison normalises \ and
/, so either separator is accepted. A computed (non-constant) path is accepted because it can’t be
compared at compile time.
// OKbuilder.AddDotnetProject(Name, "../Example.Service/Example.Service.csproj");
// SG0018 (warning): the declared path is never added.builder.AddDotnetProject(Name, "../Other.Service/Other.Service.csproj");Without ProjectPath, ResourceKit still checks that BuildResource calls AddDotnetProject at all,
but it has no path to compare.
ProjectPath is V2-only (SG0041)
Section titled “ProjectPath is V2-only (SG0041)”ProjectPath is ignored by any resource that is not a DotnetProjectResource, including the legacy
Projects.* form. SG0041 reports the contradiction so a path that is never used cannot look
validated. Use ResourcePath for an Aspire JavaScript app; it reports SG0043 on any other resource.
Both paths must agree (SG0042)
Section titled “Both paths must agree (SG0042)”ResourcePath wins when both are set. If they declare different paths, SG0042 reports the conflict
so a stale ProjectPath cannot look like the validated value.
Explicit base must use DotnetProjectResource (SG0019)
Section titled “Explicit base must use DotnetProjectResource (SG0019)”When a V2 project kit declares an explicit base class (non-generic attribute style), the base must
resolve to DotnetProjectResource. SG0019 is an execution-only warning.
[ResourceDefinition("api", ProjectPath = "../Example.Service/Example.Service.csproj")]partial class ApiResourceKit : ResourceKitBase<DotnetProjectResource>{ protected override IResourceBuilder<DotnetProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddDotnetProject(Name, "../Example.Service/Example.Service.csproj");}Aspire 13.6 legacy project resources
Section titled “Aspire 13.6 legacy project resources”Use the Aspire-generated project reference type directly in the attribute. The generator maps it to
ProjectResource for the generated base class:
using Aspire.Hosting;using Aspire.Hosting.ApplicationModel;using Purview.Aspire.ResourceKit;
[ResourceDefinition<Projects.Example_Service>("api")]partial class ApiResourceKit{ protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddProject<Projects.Example_Service>(Name);}Projects.Example_Service is the type generated by the Aspire SDK into the AppHost. It implements
IProjectMetadata (the type accepted by AddProject<TProject>()). When the type argument implements
IProjectMetadata, ResourceKit:
- validates the resource type (rather than rejecting it),
- maps it to
ProjectResourcefor the generated base class, - enables the two project-specific execution-only rules below.
The declared project must be added (SG0018)
Section titled “The declared project must be added (SG0018)”BuildResource must register the same project it declares via AddProject<T>().
// OKprotected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddProject<Projects.Example_Service>(Name);// SG0018 (warning): the declared project is never registered at runtime.[ResourceDefinition<Projects.Example_Service>("api")]partial class ApiResourceKit{ protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddContainer("api", "my-image");}SG0018 is an execution-only warning: generation still proceeds so you can complete the override without losing the host kit output. At runtime the declared project is not registered, so the resource fails.
Explicit base must use ProjectResource (SG0019)
Section titled “Explicit base must use ProjectResource (SG0019)”When a legacy project resource kit declares an explicit base class (non-generic attribute style), the
base must resolve to ProjectResource.
[ResourceDefinition("api")]partial class ApiResourceKit : ResourceKitBase<ProjectResource>{ protected override IResourceBuilder<ProjectResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddProject<Projects.Example_Service>(Name);}If the explicit base resolves to a different resource type, SG0019 is reported (execution-only warning) because that base cannot build the declared project.
JavaScript app paths (ResourcePath)
Section titled “JavaScript app paths (ResourcePath)”Aspire.Hosting.JavaScript adds Vite, Next.js, Node, Bun and Deno apps by directory. ResourcePath
declares that directory on the kit and SG0018 validates the matching Add*App call, using the same
separator normalisation and computed-path allowance as AddDotnetProject:
using Aspire.Hosting.JavaScript;
// Generates BuildResource as AddViteApp(builder, Name, "../../../web/packages/vite-app").[ResourceDefinition<ViteAppResource>("web", ResourcePath = "../../../web/packages/vite-app")]partial class WebResourceKit;
// AddNodeApp also needs a script path, so the override is written by hand and SG0018 validates it.[ResourceDefinition<NodeAppResource>("worker", ResourcePath = "../../../web/packages/worker")]partial class WorkerResourceKit{ protected override IResourceBuilder<NodeAppResource> BuildResource(IDistributedApplicationBuilder builder) => builder.AddNodeApp(Name, "../../../web/packages/worker", "server.js");}-
BuildResourceis generated forViteAppResource(AddViteApp) andNextJsAppResource(AddNextJsApp), leaving the run script at its"dev"default. Pass a different script, and the override is yours to write. SG0044 reports an override that only repeats the generated call, including one that passes"dev"explicitly. -
Node, Bun and Deno apps, and a kit declared against the
JavaScriptAppResourcebase type, always need a hand-written override. -
Supported methods:
AddViteApp,AddNextJsApp,AddNodeApp,AddBunApp,AddDenoApp,AddJavaScriptApp. The path is read from theappDirectoryparameter (orpath/workingDirectorywhen named). -
The resource type is recognised through
JavaScriptAppResource, resolved by metadata name: a consumer that does not referenceAspire.Hosting.JavaScriptis unaffected, and aResourcePathon any other resource reports SG0043. -
AddProject<T>(the legacy .NET form) has no path argument, so aResourcePaththere reports SG0043 rather than pretending to validate it.
Typed paths (AppHostProjects)
Section titled “Typed paths (AppHostProjects)”Declare each path once, in the AppHost project, and the package’s build target emits a typed class.
ResourceKitProject declares a .NET project or app directory; ResourceKitPath declares any other
file or directory:
<ItemGroup> <ResourceKitProject Include="..\..\dotnet-project" Name="api" /> <ResourceKitProject Include="..\..\..\web\packages\vite-app" Name="web" /> <ResourceKitPath Include="..\..\deploy\Dockerfile" Name="dockerfile" Kind="File" /> <ResourceKitPath Include="..\..\certs" Name="certs" Kind="Directory" Optional="true" /></ItemGroup>// Generated into the AppHost's root namespace.internal static class AppHostProjects{ internal static class Api { public const string Name = "api"; public const string Path = "../../dotnet-project"; }
internal static class Web { public const string Name = "web"; public const string Path = "../../../web/packages/vite-app"; }}// Both registrations 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;The path is declared once, in the csproj, and referenced once, on the attribute. Path is a const, so
the generator reads its value for the generated BuildResource. When you write the override yourself,
SG0018 validates the constant just as it validates a literal.
- The item’s
Nameis the logical Aspire resource name and defaults to the leaf file/directory name. Only letters, digits,.,_and-are allowed (RKP0003). ClassNameoverrides the generated nested type name, which otherwise defaults to PascalCase ofName(dotnet-project→DotnetProject). It must be a valid C# identifier (RKP0002), and two items may not resolve to the same one (RKP0004).Kind="File"orKind="Directory"asserts the path resolves to that kind (RKP0005); any other value isRKP0006.- A relative path is emitted exactly as declared, with
/separators, because Aspire resolves it from the AppHost project directory. It is not made absolute: generated source must not depend on the machine. - A declared path that does not exist fails the build (
RKP0001). SetOptional="true"on the item for a submodule or generated folder that may be absent, orResourceKitAppHostProjectsValidatePaths=falseto skip every check. - The class defaults to
internalin the AppHost’s root namespace. SetResourceKitAppHostProjectsNamespaceto change the namespace (for exampleProjects),ResourceKitAppHostProjectsClassNameto rename the class, andResourceKitAppHostProjectsVisibilityto make itpublic.
Generic vs non-generic styles
Section titled “Generic vs non-generic styles”- Generic style (
[ResourceDefinition<TResource>(...)]) is recommended for project resources: the type is declared on the attribute and the base is supplied by the generator. - Non-generic style (
[ResourceDefinition(...)]+ explicit base) requires the base to use the declared project resource type (SG0019).
See Attributes Reference for the base-type rules shared by all resources,
and Diagnostics for the RKP build errors reported by ResourceKitProject and
ResourceKitPath items.