Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 19 additions & 43 deletions src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Compiler Warning ASPIRECOMMAND001
seoTitle: 'ASPIRECOMMAND001: Required command validation types and members'
description: Learn what causes the Aspire compiler warning ASPIRECOMMAND001 and how to fix it so your AppHost builds cleanly.
title: Retired compiler warning ASPIRECOMMAND001
seoTitle: "ASPIRECOMMAND001 retired in Aspire 17.0"
description: ASPIRECOMMAND001 was removed in Aspire 17.0 when custom required-command validation became stable. Learn what to do if you still see this warning.
---

import { Badge } from '@astrojs/starlight/components';
Expand All @@ -14,62 +14,38 @@ import ApiReference from '@components/ApiReference.astro';
class:list={'mb-1'}
/>

> Required command validation types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
<Badge
text="Retired in: 17.0"
variant="tip"
size="large"
class:list={'mb-1'}
/>

This diagnostic warning is reported when using the experimental required-command validation APIs. These APIs let an AppHost run custom validation against a resource's required command or executable before the resource starts.
`ASPIRECOMMAND001` was emitted by Aspire 13.2 and later releases when code used the required-command validation APIs while they were experimental. This diagnostic no longer applies in Aspire 17.0 and later because custom required-command validation is stable.

The following APIs are protected by this diagnostic:
The following APIs are no longer experimental:

- The <ApiReference name="Aspire.Hosting.RequiredCommandResourceExtensions.WithRequiredCommand" /> overload that accepts a validation callback (`Func<RequiredCommandValidationContext, Task<RequiredCommandValidationResult>>`)
- `RequiredCommandAnnotation`
- `IRequiredCommandValidator`
- `RequiredCommandValidationContext` and `RequiredCommandValidationResult`

The simpler `WithRequiredCommand(command, helpLink)` overload isn't experimental and doesn't raise this diagnostic.

## Example
## Validation is advisory

The following code generates `ASPIRECOMMAND001`:
Required-command validation is annotation-driven and runs at run time against the app model. Validation is advisory: when a command is missing, or a validation callback returns a failure, Aspire logs a warning and the resource still attempts to start. Validation doesn't block startup.

```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("db", "postgres")
.WithRequiredCommand(
"psql",
context => Task.FromResult(context.Success()));
builder.AddExecutable("worker", "my-tool", ".")
.WithRequiredCommand("my-tool", context =>
Task.FromResult(context.Success()));

builder.Build().Run();
```

The diagnostic is triggered because the `WithRequiredCommand` validation-callback overload and the `RequiredCommandValidationContext` type are marked with the `[Experimental("ASPIRECOMMAND001")]` attribute.

## To correct this warning

Suppress the warning with one of the following methods:

- Set the severity of the rule in the _.editorconfig_ file.

```ini title=".editorconfig"
[*.{cs,vb}]
dotnet_diagnostic.ASPIRECOMMAND001.severity = none
```

For more information about editor config files, see [Configuration files for code analysis rules](/diagnostics/overview/#suppress-in-the-editorconfig-file).

- Add the following `PropertyGroup` to your project file:

```xml title="C# project file"
<PropertyGroup>
<NoWarn>$(NoWarn);ASPIRECOMMAND001</NoWarn>
</PropertyGroup>
```
A callback can return `context.Failure("Install a supported tool version.")` to report a warning with a custom message.

- Suppress in code with the `#pragma warning disable ASPIRECOMMAND001` directive:
## If you still see this warning

```csharp title="Suppressing the warning"
#pragma warning disable ASPIRECOMMAND001
builder.AddContainer("db", "postgres")
.WithRequiredCommand("psql", context => Task.FromResult(context.Success()));
#pragma warning restore ASPIRECOMMAND001
```
Upgrade the Aspire CLI, AppHost SDK, and hosting integration packages to Aspire 17.0 or later. After upgrading, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` blocks.
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/diagnostics/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [ASPIREBLAZOR001](/diagnostics/aspireblazor001/) | (Experimental) Warning | Blazor WebAssembly hosting types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREBROWSERLOGS001](/diagnostics/aspirebrowserlogs001/) | (Experimental) Error | Browser logs types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECERTIFICATES001](/diagnostics/aspirecertificates001/) | (Experimental) Warning | Certificate configuration types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECOMMAND001](/diagnostics/aspirecommand001/) | (Experimental) Warning | Required command validation types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIRECOMMAND001](/diagnostics/aspirecommand001/) | Retired | Retired in Aspire 17.0. Custom required-command validation is now stable and no longer reports this diagnostic. |
| [ASPIRECOMPUTE001](/diagnostics/aspirecompute001/) | (Experimental) Error | Compute related types and members are for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE002](/diagnostics/aspirecompute002/) | (Experimental) Warning | The GetHostAddressExpression method is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE003](/diagnostics/aspirecompute003/) | (Experimental) Warning | The ContainerRegistryResource type is for evaluation purposes only and is subject to change or removal in future updates. |
Expand Down
Loading