Skip to content
Merged
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
12 changes: 11 additions & 1 deletion .agents/skills/doc-pr-reviewer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ The docs site provides placeholders for current-version values:
Flag hard-coded Aspire versions as a review finding when they appear in current
copy/paste guidance that should track the active release, including:

- `Aspire.AppHost.Sdk` declarations in project files or file-based apps.
- `Aspire.Hosting.*` package references in AppHost project files.
- `#:package Aspire.*@...` file-based app package directives.
- Aspire CLI or AppHost sample output that reports the current CLI/AppHost
version.
Expand All @@ -117,6 +117,16 @@ Do **not** require placeholders for intentionally fixed versions, including:
If the intent is ambiguous, leave a `COMMENT` asking whether the version should
track the current release instead of requesting changes outright.

## Legacy .NET project API review

Flag new or edited evergreen AppHost samples that use the obsolete
`AddProject`/`addProject`, `AddCSharpApp`/`addCSharpApp`, `Projects.*` types,
`Aspire.AppHost.Sdk`, or `#:sdk` directives. Current samples use
`AddDotnetProject("name", "path")` from `Aspire.Hosting.Dotnet`, and C# AppHosts
use `Microsoft.NET.Sdk` with package references. Don't flag historical
what's-new pages, the [migration guide](/integrations/dotnet/migrate-dotnet-project-resource/),
or diagnostics that describe the legacy APIs.

## Phase A artifact

When Phase A finishes, write down (in memory) a frozen Phase A result containing:
Expand Down
22 changes: 15 additions & 7 deletions .agents/skills/doc-writer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ Always include a descriptive title:
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api");
var api = builder.AddDotnetProject("api", "../Api/Api.csproj");

// After adding all resources, run the app...
builder.Build().Run();
Expand All @@ -423,7 +423,7 @@ import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const api = await builder.addProject("api", "../Api/Api.csproj");
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");

await builder.build().run();
```
Expand Down Expand Up @@ -484,7 +484,7 @@ const builder = await createBuilder();

const cache = await builder.addRedis("cache");

const api = await builder.addProject("api", "../Api/Api.csproj");
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");
await api.withReference(cache);

await builder.build().run();
Expand All @@ -498,7 +498,7 @@ var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
builder.AddDotnetProject("api", "../Api/Api.csproj")
.WithReference(cache);

builder.Build().Run();
Expand All @@ -523,7 +523,7 @@ func main() {
}

cache := builder.AddRedis("cache")
api := builder.AddDotnetProject("api", "../Api/Api.csproj").
builder.AddDotnetProject("api", "../Api/Api.csproj").
WithReference(cache)

app, err := builder.Build()
Expand Down Expand Up @@ -558,6 +558,15 @@ If a section heading should appear in the **On this page** table of contents, ke
| Async pattern | `await` each builder call | Synchronous fluent calls | Synchronous fluent calls; errors surface at `Build()` |
| Build & run | `await builder.build().run()` | `builder.Build().Run()` | `app, err := builder.Build()` then `app.Run()` |

### .NET projects in AppHost samples

Add .NET projects with `AddDotnetProject("name", "path")` (`addDotnetProject` in TypeScript and `AddDotnetProject` in Go) from the `Aspire.Hosting.Dotnet` integration. The path can be a `.csproj` file, a directory containing one project, or a file-based `.cs` app.

- Do **not** use the obsolete `AddProject<Projects.X>()`, `AddProject("name", "path")`, `addProject`, `AddCSharpApp`, or `addCSharpApp` APIs in new or updated evergreen docs. They return the legacy `ProjectResource`.
- Do **not** show `Aspire.AppHost.Sdk` in project files or `#:sdk` in file-based apps. C# AppHosts use `Microsoft.NET.Sdk` with `Aspire.Hosting.AppHost` and `Aspire.Hosting.Dotnet` package references (`#:package` directives in file-based apps).
- When a page needs to mention the legacy APIs, keep it to a short `:::note[Upgrading to Aspire 17?]` that links to [Migrate to the new DotnetProjectResource](/integrations/dotnet/migrate-dotnet-project-resource/). Don't add history to evergreen pages.
- Historical what's-new pages and diagnostics about the legacy APIs (such as `ASPIRE012` and `ASPIRECSHARPAPPS001`) are the exceptions.

### Prose Guidelines

When writing narrative text around AppHost examples:
Expand Down Expand Up @@ -739,8 +748,7 @@ the active Aspire release:
| `%ASPIRE_VERSION%` | Full current stable version, including patch |
| `%ASPIRE_VERSION_MAJOR_MINOR%` | Current major/minor display or installer version |

Use these placeholders in package references, `Aspire.AppHost.Sdk`
declarations, file-based app directives, CLI/AppHost output, and generic
Use these placeholders in package references, file-based app directives, CLI/AppHost output, and generic
installation examples that should advance with the release branch. This
applies to localized documentation as well as English documentation.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ The following rules are derived from common feedback patterns in documentation P
✅ Correct:

```csharp
builder.AddProject<Projects.Api>("api")
builder.AddDotnetProject("api", "../Api/Api.csproj")
.WithReference(redis)
.WithExternalHttpEndpoints();
```

❌ Incorrect (aligned indentation):

```csharp
builder.AddProject<Projects.Api>("api")
builder.AddDotnetProject("api", "../Api/Api.csproj")
.WithReference(redis)
.WithExternalHttpEndpoints();
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ const builder = await createBuilder();

const tech = await builder.addTechnology("tech");

const api = await builder.addProject("api", "../Api/Api.csproj");
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");
await api.withReference(tech);

await builder.build().run();
Expand All @@ -154,7 +154,7 @@ var builder = DistributedApplication.CreateBuilder(args);

var tech = builder.AddTechnology("tech");

builder.AddProject<Projects.Api>("api")
builder.AddDotnetProject("api", "../Api/Api.csproj")
.WithReference(tech);

builder.Build().Run();
Expand All @@ -179,7 +179,7 @@ func main() {
}

tech := builder.AddTechnology("tech")
api := builder.AddDotnetProject("api", "../Api/Api.csproj").
builder.AddDotnetProject("api", "../Api/Api.csproj").
WithReference(tech)

app, err := builder.Build()
Expand Down
4 changes: 2 additions & 2 deletions .github/agents/release-verifier.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,10 +210,10 @@ grep -rnE '%ASPIRE_VERSION%-(preview|alpha|beta|rc)(\.[0-9A-Za-z-]+)+' src/front
--exclude-dir="whats-new"
```

Also search for stale SDK version references:
Also search for stale AppHost package and legacy SDK version references:

```bash
grep -rn 'Aspire.AppHost.Sdk.*Version="{PRIOR_NUGET_VERSION}"' src/frontend/src/content/docs/ \
grep -rnE '(Aspire\.Hosting\.AppHost|Aspire\.AppHost\.Sdk).*Version="{PRIOR_NUGET_VERSION}"' src/frontend/src/content/docs/ \
--include="*.md" \
--include="*.mdx"
```
Expand Down
2 changes: 1 addition & 1 deletion src/frontend/config/sidebar/docs.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1016,7 +1016,7 @@ export const docsTopics = {
collapsed: false,
items: [
{
label: 'Aspire SDK',
label: 'AppHost project configuration',
slug: 'get-started/aspire-sdk',
},
{
Expand Down
6 changes: 5 additions & 1 deletion src/frontend/config/sidebar/integrations.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1516,9 +1516,13 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = {
label: 'Set up C# apps by path in the AppHost',
slug: 'integrations/frameworks/dotnet/dotnet-host',
},
{ label: 'Project resources', slug: 'integrations/dotnet/project-resources' },
{ label: 'C# file-based apps', slug: 'integrations/dotnet/csharp-file-based-apps' },
{ label: 'Launch profiles', slug: 'integrations/dotnet/launch-profiles' },
{
label: 'Migrate to DotnetProjectResource',
slug: 'integrations/dotnet/migrate-dotnet-project-resource',
},
{ label: 'Legacy project resources', slug: 'integrations/dotnet/project-resources' },
{ label: '.NET tool resources', slug: 'integrations/dotnet/dotnet-tool-resources' },
{
label: 'Blazor',
Expand Down
1 change: 1 addition & 0 deletions src/frontend/config/sidebar/reference.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -711,6 +711,7 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
{ label: 'ASPIRE003', link: '/diagnostics/aspire003' },
{ label: 'ASPIRE004', link: '/diagnostics/aspire004' },
{ label: 'ASPIRE010', link: '/diagnostics/aspire010' },
{ label: 'ASPIRE012', link: '/diagnostics/aspire012' },
{
label: 'ASPIREEXPORT005',
link: '/diagnostics/aspireexport005',
Expand Down
32 changes: 16 additions & 16 deletions src/frontend/src/components/AppHostBuilder.astro
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ builder.Build().Run();`,
apiFrontend: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj");
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj");

// Add frontend service and reference the API
var frontend = builder.AddViteApp("frontend", "../frontend")
Expand All @@ -87,7 +87,7 @@ builder.Build().Run();`,
apiFrontendContainer: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj");
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj");

// Add frontend service and reference the API
var frontend = builder.AddViteApp("frontend", "../frontend")
Expand All @@ -107,7 +107,7 @@ var postgres = builder.AddPostgres("db")
.AddDatabase("appdata");

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres);

// Add frontend service and reference the API
Expand All @@ -124,7 +124,7 @@ var postgres = builder.AddPostgres("db")
.AddDatabase("appdata");

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres);

// Add frontend service and reference the API
Expand Down Expand Up @@ -162,14 +162,14 @@ builder.Build().Run();`,
api: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj");
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj");

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

apiContainer: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj");
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj");

// Add custom container
var customContainer = builder.AddContainer("mycustomcontainer", "myregistry/myapp", "latest")
Expand All @@ -184,7 +184,7 @@ var postgres = builder.AddPostgres("db")
.AddDatabase("appdata");

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres);

builder.Build().Run();`,
Expand All @@ -196,7 +196,7 @@ var postgres = builder.AddPostgres("db")
.AddDatabase("appdata");

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres);

// Add custom container
Expand Down Expand Up @@ -275,7 +275,7 @@ builder.Build().Run();`,
apiFrontendDeployment: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.PublishAsAzureContainerApp();

// Add frontend service and reference the API
Expand All @@ -289,7 +289,7 @@ builder.Build().Run();`,
apiFrontendContainerDeployment: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.PublishAsAzureContainerApp();

// Add frontend service and reference the API
Expand All @@ -314,7 +314,7 @@ var postgres = builder.AddAzurePostgresFlexibleServer("db")
.RunAsContainer();

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres)
.WaitFor(postgres)
.PublishAsAzureContainerApp();
Expand All @@ -336,7 +336,7 @@ var postgres = builder.AddAzurePostgresFlexibleServer("db")
.RunAsContainer();

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres)
.WaitFor(postgres)
.PublishAsAzureContainerApp();
Expand Down Expand Up @@ -383,15 +383,15 @@ builder.Build().Run();`,
apiDeployment: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.PublishAsAzureContainerApp();

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

apiContainerDeployment: `var builder = DistributedApplication.CreateBuilder(args);

// Add API service
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.PublishAsAzureContainerApp();

// Add custom container
Expand All @@ -410,7 +410,7 @@ var postgres = builder.AddAzurePostgresFlexibleServer("db")
.RunAsContainer();

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres)
.WaitFor(postgres)
.PublishAsAzureContainerApp();
Expand All @@ -426,7 +426,7 @@ var postgres = builder.AddAzurePostgresFlexibleServer("db")
.RunAsContainer();

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres)
.WaitFor(postgres)
.PublishAsAzureContainerApp();
Expand Down
4 changes: 2 additions & 2 deletions src/frontend/src/components/SimpleAppHostCode.shared.ts
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ var postgres = builder.AddPostgres("db")
.WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject<Projects.Api>("api")
var api = builder.AddDotnetProject("api", "../api/Api.csproj")
.WithReference(postgres)
.WaitFor(postgres);

Expand Down Expand Up @@ -196,7 +196,7 @@ const postgres = await builder.addPostgres("db")
.withDataVolume();

// Add API service and reference the database
const api = await builder.addProject("api", "../api/Api.csproj", "https")
const api = await builder.addDotnetProject("api", "../api/Api.csproj")
.withReference(postgres)
.waitFor(postgres);

Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/components/ThreeTierAspire.astro
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ var postgres = builder.AddPostgres("db")
.WithDataVolume();

// Add API service and reference the database
var api = builder.AddProject("api", "../api/ApiService.csproj")
var api = builder.AddDotnetProject("api", "../api/ApiService.csproj")
.WithReference(postgres)
.WaitFor(postgres);

Expand Down
4 changes: 2 additions & 2 deletions src/frontend/src/components/home/HomePage.astro
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,10 @@ var postgres = builder.AddPostgres("postgres")
var cache = builder.AddRedis("basketcache");

var catalog = builder
.AddProject<Projects.CatalogService>("catalogservice")
.AddDotnetProject("catalogservice", "./catalog/CatalogService.csproj")
.WithReference(postgres);

builder.AddProject<Projects.Frontend>("frontend")
builder.AddDotnetProject("frontend", "./frontend/Frontend.csproj")
.WithReference(catalog)
.WithReference(cache);

Expand Down
Loading
Loading