Documentation section: Reference
Diagnostics
ResourceKit reports diagnostics with SGxxxx IDs to help you fix model issues quickly. The rules are
evaluated by the bundled ResourceKitDiagnosticAnalyzer (and the source generator uses the same shared
rule set to decide what can be generated).
ResourceKit also ships ResourceKitDiagnosticSuppressor, which automatically suppresses CS8618 for
non-nullable IResourceBuilder<T> properties declared on resource kits — these are populated at runtime
during the BuildResource/ConfigureResource lifecycle, so the “must contain a non-null value when
exiting the constructor” warning does not apply.
Diagnostic reference
Section titled “Diagnostic reference”| ID | Severity | What it means |
|---|---|---|
| SG0001 | Error | A participating class must be partial |
| SG0002 | Info | Host kit exists but no resources were defined |
| SG0003 | Warning | Resources exist but no host kit was defined |
| SG0004 | Error | More than one [HostKit] class was found |
| SG0005 | Error | Two resources map to the same generated property name |
| SG0006 | Error | A resource does not derive from the expected generated base |
| SG0007 | Error | Resource name could not be inferred and Name was not set |
| SG0008 | Error | Explicit PropertyName is not a valid C# identifier |
| SG0009 | Error | Missing IServiceCollection 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> usage on one class |
| SG0014 | Error | Non-generic ResourceDefinition requires explicit compatible base type |
| SG0015 | Error | Generic ResourceDefinition<TResource> cannot declare explicit base type |
| SG0016 | Error | No Aspire resource type could be inferred/found |
| SG0017 | Warning | An IResourceBuilder<T> property is never assigned in BuildResource or ConfigureResource |
| SG0018 | Warning | A resource kit does not add its declared project or app path via the matching Add method |
| SG0019 | Warning | A project resource kit’s explicit base does not use ProjectResource or DotnetProjectResource |
| SG0020 | Error | An OptionsHelper.Assign action sets more than one property path |
| SG0021 | Error | An [InGroup<TGroup>] type argument, or a group’s Parent, is not a [ResourceGroup] class |
| SG0022 | Error | A resource group is its own ancestor |
| SG0023 | Error | Two resource groups share a name (case-insensitive) or a property name |
| SG0024 | Warning | A resource kit marks more than one group as Primary |
| SG0025 | Error | A resource group declares a base type |
| SG0026 | Error | Two URLs on one resource kit or group share a name |
| SG0027 | Error | An endpoint URL is declared on a resource, or group, without endpoints |
| SG0028 | Warning | A relative URL is declared on a resource, or group, without endpoints |
| SG0029 | Error | A resource group declares its parent more than once |
| SG0030 | Error | A resource group is generic, or nested in a generic type |
| SG0031 | Error | A resource group is also a resource kit, or carries [InGroup] |
| SG0032 | Error | A resource kit declares itself as its parent |
| SG0033 | Error | The parent chain contains a cycle; the message prints the path |
| SG0034 | Error | The declared parent type is not a resource kit |
| SG0035 | Error | The declared parent is not part of this host kit composition |
| SG0036 | Error | The generated child property collides with a member on the parent |
| SG0037 | Error | Two children of the same parent use the same generated property name |
| SG0038 | Error | The generated Parent member collides with a user-authored member |
| SG0039 | Warning | A child uses an explicit primary group different 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, so it is ignored |
| 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, so it is ignored |
| SG0044 | Info | A BuildResource override only repeats the registration ResourceKit generates from the declared path; the code fix removes it, moving the path into the attribute first when needed |
See Attributes Reference for the rules tied to attribute styles, Project Resources for SG0018/SG0019/SG0041–SG0044 specifics, Groups and URLs for SG0021–SG0031, and Parent and child resource kits for SG0032–SG0040.
A parent cycle is reported on one kit in the cycle and includes the full path, for example
PostgresKit -> DatabaseKit -> MigrationKit -> PostgresKit. Invalid hierarchies block generation; manual
graphs are validated at runtime before any Aspire resource is created.
Execution-only vs generation-blocking rules
Section titled “Execution-only vs generation-blocking rules”SG0017, SG0018, SG0019, SG0024, SG0028, SG0042 and SG0043 are execution-only rules. They report problems that break the resource at
runtime (an unset builder property, a project that is never registered, or a base class that cannot build
a project) but they do not prevent source generation. They are reported as warnings so generation
always proceeds — for example, a resource kit whose BuildResource does not yet register its declared
project via AddProject<T>() or AddDotnetProject(...) is still generated (and the host kit is still emitted) so the user can
complete the override instead of losing the whole output. Only Error-severity rules block generation.
SG0024 keeps the first primary group, and SG0028’s URL is skipped at runtime.
SG0041 is a declaration advisory rather than an execution-only rule: the resource still builds and
runs, but the ProjectPath it declares is not used by its resource type, so the path cannot protect
against a wiring mistake. SG0042 and SG0043 cover the same ground for ResourcePath and are tracked as
execution-only, so generation proceeds: SG0042 means ResourcePath is the validated value and the
conflicting ProjectPath is stale, and SG0043 means the declared ResourcePath is ignored entirely.
Build-time path errors (RKP)
Section titled “Build-time path errors (RKP)”These are MSBuild errors from the ResourceKitProject items, not SG analyzer diagnostics. They fire
before compilation, when the typed AppHostProjects class is generated:
| ID | What it means |
|---|---|
| RKP0001 | A ResourceKitProject or ResourceKitPath path does not exist relative to the AppHost project directory |
| RKP0002 | The declared or derived nested class name is not a valid C# identifier |
| RKP0003 | The resource name contains a character Aspire or the generated literal cannot represent |
| RKP0004 | Two items generate the same nested class name under AppHostProjects |
| RKP0005 | Kind="File" resolves to a directory, or Kind="Directory" resolves to a file |
| RKP0006 | Kind is set to a value other than File or Directory |
| RKP0007 | ResourceKitProject/ResourceKitPath items are declared in a project that is not a C# AppHost |
<!-- Fails with RKP0001 if the relative depth is wrong. --><ResourceKitProject Include="..\..\dotnet-project" Name="api" />
<!-- Any other path works too; Kind proves it is a file. --><ResourceKitPath Include="..\..\deploy\Dockerfile" Name="dockerfile" Kind="File" />
<!-- Allowed to be absent (submodule, generated folder). --><ResourceKitPath Include="..\..\generated" Name="generated" Optional="true" />See Project resources.
OptionsHelper.Assign action with multiple property paths (SG0020)
Section titled “OptionsHelper.Assign action with multiple property paths (SG0020)”Each OptionsHelper.Assign<TOptions>(...) action must set exactly one property path. A block-bodied lambda
such as the following is rejected at compile time:
OptionsHelper.Assign<ShopHostKitOptions>(o =>{ o.API.IsEnabled = false; o.API.Name = "api-test";});Split each property into its own assignment argument instead:
OptionsHelper.Assign<ShopHostKitOptions>( o => o.API.IsEnabled = false, o => o.API.Name = "api-test");Visual Studio offers a “Split into separate assignments” code fix that performs this conversion for you. See OptionsHelper and Source Generator Behaviors.
Redundant ResourceBuilder access (SG0040)
Section titled “Redundant ResourceBuilder access (SG0040)”A resource kit derives from ResourceKitBase<THostKit, TResource>, which implements
IResourceBuilder<TResource>. When the kit is the receiver of the next call, the .ResourceBuilder hop is
redundant:
// Before (SG0040, Info)Parent.ResourceBuilder.AddDatabase(Name);
// After — "Use the resource kit directly"Parent.AddDatabase(Name);The code fix only fires when the hop is the receiver of a following member access/invocation. It deliberately
does not fire in argument position, where the expected parameter type might be IResourceBuilder<IResource>
and the kit’s own IResourceBuilder<TResource> would not satisfy it.
Fast troubleshooting checklist
Section titled “Fast troubleshooting checklist”- Ensure host/resource classes are marked
partial. - Ensure exactly one
[HostKit]class exists in the compilation. - Ensure root property names are unique, and child property names are unique within each parent
(explicit
PropertyNamecan help). - Ensure each resource uses a compatible base and definition attribute style.
- Set explicit
Namewhen inference cannot determine resource name. - If the kit declares
Parent = typeof(...), ensure that type is a resource kit in the same composition; a child in a different primary group than its parent gets SG0039, and a redundantParent.ResourceBuildergets SG0040.
Common fixes
Section titled “Common fixes”Duplicate generated property names (SG0005)
Section titled “Duplicate generated property names (SG0005)”Use unique PropertyName values:
[ResourceDefinition<ProjectResource>("api", PropertyName = "Api")][ResourceDefinition<ProjectResource>("admin", PropertyName = "AdminApi")]Invalid PropertyName (SG0008)
Section titled “Invalid PropertyName (SG0008)”Use valid C# identifiers only (Api, RedisCache, OrderDb, etc.).
Multiple host kits (SG0004)
Section titled “Multiple host kits (SG0004)”Keep one [HostKit] per compilation; split scenarios into separate projects if needed.
Mixed attribute styles (SG0013)
Section titled “Mixed attribute styles (SG0013)”Use exactly one style per class:
[ResourceDefinition("name")]- or
[ResourceDefinition<TResource>("name")]
Do not apply both to the same class.
Base-type mismatch by style (SG0014 / SG0015)
Section titled “Base-type mismatch by style (SG0014 / SG0015)”- If you use non-generic
[ResourceDefinition("name")], declare an explicit compatible base. - If you use generic
[ResourceDefinition<TResource>("name")], do not declare an explicit base.
Unassigned IResourceBuilder<T> property (SG0017)
Section titled “Unassigned IResourceBuilder<T> property (SG0017)”Every IResourceBuilder<T> property on a resource kit (nullable or not) must be assigned in either
BuildResource or ConfigureResource. CS8618 is automatically suppressed for these properties because
they are populated at runtime, so SG0017 is the signal that a property is never set:
[ResourceDefinition<AzureSqlServerResource>("sql")]sealed partial class SqlServerKit{ public IResourceBuilder<AzureSqlDatabaseResource> Database { get; private set; }
protected override void ConfigureResource() { Database = ResourceBuilder.AddDatabase("changeops-db", "ChangeOps"); base.ConfigureResource(); }}