diff --git a/.agents/skills/doc-pr-reviewer/SKILL.md b/.agents/skills/doc-pr-reviewer/SKILL.md index ff1c4d8c8b..f3e2ff93dc 100644 --- a/.agents/skills/doc-pr-reviewer/SKILL.md +++ b/.agents/skills/doc-pr-reviewer/SKILL.md @@ -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. @@ -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: diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 5900108197..3701341183 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -410,7 +410,7 @@ Always include a descriptive title: ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var api = builder.AddProject("api"); +var api = builder.AddDotnetProject("api", "../Api/Api.csproj"); // After adding all resources, run the app... builder.Build().Run(); @@ -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(); ``` @@ -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(); @@ -498,7 +498,7 @@ var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); -builder.AddProject("api") +builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(cache); builder.Build().Run(); @@ -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() @@ -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()`, `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: @@ -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. diff --git a/.agents/skills/doc-writer/references/common-documentation-issues.md b/.agents/skills/doc-writer/references/common-documentation-issues.md index 64901034a7..86a155eb46 100644 --- a/.agents/skills/doc-writer/references/common-documentation-issues.md +++ b/.agents/skills/doc-writer/references/common-documentation-issues.md @@ -19,7 +19,7 @@ The following rules are derived from common feedback patterns in documentation P ✅ Correct: ```csharp - builder.AddProject("api") + builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(redis) .WithExternalHttpEndpoints(); ``` @@ -27,7 +27,7 @@ The following rules are derived from common feedback patterns in documentation P ❌ Incorrect (aligned indentation): ```csharp - builder.AddProject("api") + builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(redis) .WithExternalHttpEndpoints(); ``` diff --git a/.agents/skills/doc-writer/references/integration-documentation.md b/.agents/skills/doc-writer/references/integration-documentation.md index 9cb7d9988b..c29e4918d0 100644 --- a/.agents/skills/doc-writer/references/integration-documentation.md +++ b/.agents/skills/doc-writer/references/integration-documentation.md @@ -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(); @@ -154,7 +154,7 @@ var builder = DistributedApplication.CreateBuilder(args); var tech = builder.AddTechnology("tech"); -builder.AddProject("api") +builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(tech); builder.Build().Run(); @@ -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() diff --git a/.github/agents/release-verifier.agent.md b/.github/agents/release-verifier.agent.md index 4350052b67..65a62108c5 100644 --- a/.github/agents/release-verifier.agent.md +++ b/.github/agents/release-verifier.agent.md @@ -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" ``` diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index aadb057d41..2af25b4f42 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -1016,7 +1016,7 @@ export const docsTopics = { collapsed: false, items: [ { - label: 'Aspire SDK', + label: 'AppHost project configuration', slug: 'get-started/aspire-sdk', }, { diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 6661fe9b55..a1e9480952 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -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', diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts index 5d8b5dd960..24e995e794 100644 --- a/src/frontend/config/sidebar/reference.topics.ts +++ b/src/frontend/config/sidebar/reference.topics.ts @@ -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', diff --git a/src/frontend/src/components/AppHostBuilder.astro b/src/frontend/src/components/AppHostBuilder.astro index ef6d98d6fb..79ea53c5ee 100644 --- a/src/frontend/src/components/AppHostBuilder.astro +++ b/src/frontend/src/components/AppHostBuilder.astro @@ -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") @@ -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") @@ -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 @@ -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 @@ -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") @@ -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();`, @@ -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 @@ -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 @@ -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 @@ -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(); @@ -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(); @@ -383,7 +383,7 @@ 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();`, @@ -391,7 +391,7 @@ 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 @@ -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(); @@ -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(); diff --git a/src/frontend/src/components/SimpleAppHostCode.shared.ts b/src/frontend/src/components/SimpleAppHostCode.shared.ts index 6adb5e7ae8..4d5a033abe 100644 --- a/src/frontend/src/components/SimpleAppHostCode.shared.ts +++ b/src/frontend/src/components/SimpleAppHostCode.shared.ts @@ -86,7 +86,7 @@ var postgres = builder.AddPostgres("db") .WithDataVolume(); // Add API service and reference the database -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../api/Api.csproj") .WithReference(postgres) .WaitFor(postgres); @@ -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); diff --git a/src/frontend/src/components/ThreeTierAspire.astro b/src/frontend/src/components/ThreeTierAspire.astro index f59e4c77a8..ef4f581e61 100644 --- a/src/frontend/src/components/ThreeTierAspire.astro +++ b/src/frontend/src/components/ThreeTierAspire.astro @@ -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); diff --git a/src/frontend/src/components/home/HomePage.astro b/src/frontend/src/components/home/HomePage.astro index cee67e817c..d8c53e4d4a 100644 --- a/src/frontend/src/components/home/HomePage.astro +++ b/src/frontend/src/components/home/HomePage.astro @@ -70,10 +70,10 @@ var postgres = builder.AddPostgres("postgres") var cache = builder.AddRedis("basketcache"); var catalog = builder - .AddProject("catalogservice") + .AddDotnetProject("catalogservice", "./catalog/CatalogService.csproj") .WithReference(postgres); -builder.AddProject("frontend") +builder.AddDotnetProject("frontend", "./frontend/Frontend.csproj") .WithReference(catalog) .WithReference(cache); diff --git a/src/frontend/src/content/docs/app-host/configuration.mdx b/src/frontend/src/content/docs/app-host/configuration.mdx index 4df8ef4f80..026f681f5f 100644 --- a/src/frontend/src/content/docs/app-host/configuration.mdx +++ b/src/frontend/src/content/docs/app-host/configuration.mdx @@ -159,7 +159,7 @@ The version check runs only when: - The check hasn't been disabled via the `ASPIRE_VERSION_CHECK_DISABLED` configuration setting. - The app is not running in publish mode. -Updates are manual. You need to edit your project file to upgrade the Aspire SDK and package versions. +Update the Aspire CLI with `aspire update --self`, then run `aspire update` to update the AppHost's Aspire package versions. You can also edit the package versions manually. ## Resource service @@ -207,7 +207,7 @@ Internal settings are used by the AppHost and integrations. Internal settings ar ## Advanced orchestration properties ### DcpCliPath @@ -216,11 +216,7 @@ The `DcpCliPath` property specifies the path to the **Developer Control Plane (D #### How it works -When you use the [Aspire SDK](/get-started/aspire-sdk/), the build system automatically: - -1. Imports the platform-specific `Aspire.Hosting.Orchestration` NuGet package (for example, `Aspire.Hosting.Orchestration.win-x64`). -2. Sets `DcpCliPath` to point to the `dcp` executable within that package. -3. Embeds this path as assembly metadata in your compiled AppHost. +The AppHost build resolves DCP from the installed [Aspire CLI bundle](/get-started/aspire-sdk/#use-the-aspire-cli-bundle-for-orchestration-dependencies), which C# AppHosts require, and embeds its path as assembly metadata in your compiled AppHost. When you start the AppHost with `aspire run` or `aspire start`, the CLI passes the bundle paths to the AppHost directly. At runtime, the AppHost reads this metadata to locate and start the DCP process, which then orchestrates your application's resources. @@ -239,9 +235,9 @@ In rare cases, you may need to override the default DCP path: You might override `DcpCliPath` in these scenarios: - **Aspire contributors**: Testing with a custom or debug build of DCP when developing Aspire itself. -- **CI/CD pipelines**: Non-standard SDK layouts where automatic discovery doesn't work. +- **CI/CD pipelines**: Nonstandard layouts where automatic discovery doesn't work. - **Troubleshooting**: Temporarily pointing to a specific DCP version to diagnose issues. diff --git a/src/frontend/src/content/docs/app-host/console-apps.mdx b/src/frontend/src/content/docs/app-host/console-apps.mdx index 692f8fe756..0a3a81af17 100644 --- a/src/frontend/src/content/docs/app-host/console-apps.mdx +++ b/src/frontend/src/content/docs/app-host/console-apps.mdx @@ -31,7 +31,7 @@ For example, to orchestrate a Node.js console app from a C# AppHost, choose any These examples assume an existing AppHost. -- **.NET:** The examples also assume a shared service defaults project. Create the named console, worker, and API projects before referencing them. In a C# AppHost, add project references so the corresponding `Projects.*` types are generated; in a TypeScript AppHost, use each project's actual path. +- **.NET:** The examples also assume a shared service defaults project. Create the named console, worker, and API projects before referencing them. Reference each project by its path relative to the AppHost directory. - **Node.js:** Create each app folder with a _package.json_ file before referencing it. The AppHost resolves the app folder path relative to the AppHost directory, and the script path relative to the app folder. For the Redis examples, install the hosting integration in your AppHost. Running Redis also requires a supported [container runtime](/get-started/prerequisites/). @@ -52,7 +52,22 @@ For the Redis examples, install the hosting integration in your AppHost. Running -Add the console app project to your AppHost: +Install the .NET hosting integration in your AppHost. It provides `AddDotnetProject` / `addDotnetProject`, which runs a .NET project or C# file-based app: + + + + + + + + + + + + + + +Then add the console app project to your AppHost: @@ -63,7 +78,7 @@ var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); // Add a console app project to the AppHost -var processor = builder.AddProject("processor") +var processor = builder.AddDotnetProject("processor", "../MyConsoleApp/MyConsoleApp.csproj") .WithReference(cache); builder.Build().Run(); @@ -81,7 +96,7 @@ const cache = await builder.addRedis('cache'); // Add a console app project to the AppHost await builder - .addProject('processor', '../MyConsoleApp/MyConsoleApp.csproj') + .addDotnetProject('processor', '../MyConsoleApp/MyConsoleApp.csproj') .withReference(cache); await builder.build().run(); @@ -258,9 +273,9 @@ Console apps using the .NET Generic Host can use the same service discovery infr ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); - var catalog = builder.AddProject("catalog"); + var catalog = builder.AddDotnetProject("catalog", "../CatalogService/CatalogService.csproj"); - var processor = builder.AddProject("processor") + var processor = builder.AddDotnetProject("processor", "../MyConsoleApp/MyConsoleApp.csproj") .WithReference(catalog) .WaitFor(catalog); @@ -275,12 +290,12 @@ Console apps using the .NET Generic Host can use the same service discovery infr const builder = await createBuilder(); - const catalog = await builder.addProject( + const catalog = await builder.addDotnetProject( 'catalog', '../CatalogService/CatalogService.csproj' ); - const processor = await builder.addProject( + const processor = await builder.addDotnetProject( 'processor', '../MyConsoleApp/MyConsoleApp.csproj' ); @@ -337,7 +352,7 @@ Node.js apps don't use the .NET service discovery resolver. Instead, they read t ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); - var catalog = builder.AddProject("catalog"); + var catalog = builder.AddDotnetProject("catalog", "../CatalogService/CatalogService.csproj"); var processor = builder.AddNodeApp("processor", "../processor", "index.js") .WithReference(catalog) @@ -354,7 +369,7 @@ Node.js apps don't use the .NET service discovery resolver. Instead, they read t const builder = await createBuilder(); - const catalog = await builder.addProject( + const catalog = await builder.addDotnetProject( 'catalog', '../CatalogService/CatalogService.csproj' ); @@ -543,7 +558,7 @@ var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); var db = builder.AddPostgres("postgres").AddDatabase("app-db"); -var worker = builder.AddProject("data-worker") +var worker = builder.AddDotnetProject("data-worker", "../DataWorker/DataWorker.csproj") .WithReference(cache) .WithReference(db) .WaitFor(db); @@ -563,7 +578,7 @@ const cache = await builder.addRedis('cache'); const postgres = await builder.addPostgres('postgres'); const db = await postgres.addDatabase('app-db'); -const worker = await builder.addProject( +const worker = await builder.addDotnetProject( 'data-worker', '../DataWorker/DataWorker.csproj' ); @@ -653,7 +668,7 @@ In your AppHost, add the console app project with `WithExplicitStart`: ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var tool = builder.AddProject("tool") +var tool = builder.AddDotnetProject("tool", "../MyInteractiveTool/MyInteractiveTool.csproj") .WithExplicitStart(); builder.Build().Run(); @@ -667,7 +682,7 @@ import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); -const tool = await builder.addProject( +const tool = await builder.addDotnetProject( 'tool', '../MyInteractiveTool/MyInteractiveTool.csproj' ); diff --git a/src/frontend/src/content/docs/app-host/container-files.mdx b/src/frontend/src/content/docs/app-host/container-files.mdx index 080ecfb63d..404dbd1f47 100644 --- a/src/frontend/src/content/docs/app-host/container-files.mdx +++ b/src/frontend/src/content/docs/app-host/container-files.mdx @@ -99,7 +99,7 @@ const builder = await createBuilder(); const frontend = await builder.addViteApp("frontend", "../frontend"); await frontend.withContainerFilesSource("/app/dist"); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.publishWithContainerFiles(frontend, "./wwwroot"); await builder.build().run(); @@ -351,7 +351,7 @@ var builder = DistributedApplication.CreateBuilder(args); var frontend = builder.AddViteApp("frontend", "../frontend"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .PublishWithContainerFiles(frontend, "./wwwroot"); builder.Build().Run(); @@ -365,7 +365,7 @@ const builder = await createBuilder(); const frontend = await builder.addViteApp("frontend", "../frontend"); -const api = await builder.addProject("api", "./Api/Api.csproj") +const api = await builder.addDotnetProject("api", "../Api/Api.csproj") .publishWithContainerFiles(frontend, "./wwwroot"); await builder.build().run(); @@ -414,7 +414,7 @@ await builder.build().run(); This produces a self-contained Nginx container that serves the frontend application, with no external volume mounts or runtime file copying needed. -`PublishWithContainerFiles` only applies in publish mode — it has no effect during `aspire run`. The destination resource must implement `IContainerFilesDestinationResource` (such as `ProjectResource`), and the source resource must implement `IResourceWithContainerFiles`. +`PublishWithContainerFiles` only applies in publish mode — it has no effect during `aspire run`. The destination resource must implement `IContainerFilesDestinationResource` (such as a .NET project added with `AddDotnetProject`), and the source resource must implement `IResourceWithContainerFiles`. ### Customize the source path @@ -426,7 +426,7 @@ By default, the source resource exports files from its container based on its co var frontend = builder.AddViteApp("frontend", "../frontend") .WithContainerFilesSource("/app/dist"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .PublishWithContainerFiles(frontend, "./wwwroot"); ``` diff --git a/src/frontend/src/content/docs/app-host/container-registry.mdx b/src/frontend/src/content/docs/app-host/container-registry.mdx index 28809f66e4..bcca6e0331 100644 --- a/src/frontend/src/content/docs/app-host/container-registry.mdx +++ b/src/frontend/src/content/docs/app-host/container-registry.mdx @@ -40,7 +40,7 @@ var builder = DistributedApplication.CreateBuilder(args); var registry = builder.AddContainerRegistry("myregistry", "registry.example.com"); // Associate the registry with a project -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); builder.Build().Run(); @@ -56,7 +56,7 @@ const builder = await createBuilder(); const registry = await builder.addContainerRegistry("myregistry", "registry.example.com"); // Associate the registry with a project -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); await builder.build().run(); @@ -81,7 +81,7 @@ var builder = DistributedApplication.CreateBuilder(args); var registry = builder.AddContainerRegistry("dockerhub", "docker.io"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); ``` @@ -93,7 +93,7 @@ const builder = await createBuilder(); const registry = await builder.addContainerRegistry("dockerhub", "docker.io"); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); ``` @@ -110,7 +110,7 @@ var builder = DistributedApplication.CreateBuilder(args); var registry = builder.AddContainerRegistry("ghcr", "ghcr.io"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); ``` @@ -122,7 +122,7 @@ const builder = await createBuilder(); const registry = await builder.addContainerRegistry("ghcr", "ghcr.io"); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); ``` @@ -141,7 +141,7 @@ var registry = builder.AddContainerRegistry( "private-registry", "registry.mycompany.com:5000"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); ``` @@ -155,7 +155,7 @@ const registry = await builder.addContainerRegistry( "private-registry", "registry.mycompany.com:5000"); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); ``` @@ -182,7 +182,7 @@ var registry = builder.AddContainerRegistry( registryEndpoint, registryRepository); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); ``` @@ -200,7 +200,7 @@ const registry = await builder.addContainerRegistry( registryEndpoint, registryRepository); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); ``` @@ -265,7 +265,7 @@ var builder = DistributedApplication.CreateBuilder(args); var environment = builder.AddAzureContainerAppEnvironment("myenv"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(environment); builder.Build().Run(); @@ -279,7 +279,7 @@ const builder = await createBuilder(); const environment = await builder.addAzureContainerAppEnvironment("myenv"); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(environment); await builder.build().run(); @@ -320,7 +320,7 @@ var acr = builder.AddAzureContainerRegistry("my-acr") builder.AddAzureContainerAppEnvironment("env") .WithAzureContainerRegistry(acr); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(acr); ``` @@ -339,7 +339,7 @@ await acr.publishAsExisting(registryName, rgName); const environment = await builder.addAzureContainerAppEnvironment("env"); await environment.withAzureContainerRegistry(acr); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(acr); ``` @@ -420,10 +420,10 @@ var privateRegistry = builder.AddContainerRegistry( "private", "registry.company.com"); -var publicApi = builder.AddProject("public-api") +var publicApi = builder.AddDotnetProject("public-api", "../PublicApi/PublicApi.csproj") .WithContainerRegistry(publicRegistry); -var internalApi = builder.AddProject("internal-api") +var internalApi = builder.AddDotnetProject("internal-api", "../InternalApi/InternalApi.csproj") .WithContainerRegistry(privateRegistry); ``` @@ -438,10 +438,10 @@ const privateRegistry = await builder.addContainerRegistry( "private", "registry.company.com"); -const publicApi = await builder.addProject("public-api", "../PublicApi/PublicApi.csproj"); +const publicApi = await builder.addDotnetProject("public-api", "../PublicApi/PublicApi.csproj"); await publicApi.withContainerRegistry(publicRegistry); -const internalApi = await builder.addProject("internal-api", "../InternalApi/InternalApi.csproj"); +const internalApi = await builder.addDotnetProject("internal-api", "../InternalApi/InternalApi.csproj"); await internalApi.withContainerRegistry(privateRegistry); ``` @@ -464,10 +464,10 @@ var registry = builder.AddContainerRegistry( registryEndpoint, registryRepository); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithContainerRegistry(registry); -var worker = builder.AddProject("worker") +var worker = builder.AddDotnetProject("worker", "../Worker/Worker.csproj") .WithContainerRegistry(registry); builder.Build().Run(); @@ -487,10 +487,10 @@ const registry = await builder.addContainerRegistry( registryEndpoint, registryRepository); -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withContainerRegistry(registry); -const worker = await builder.addProject("worker", "../Worker/Worker.csproj"); +const worker = await builder.addDotnetProject("worker", "../Worker/Worker.csproj"); await worker.withContainerRegistry(registry); await builder.build().run(); @@ -532,12 +532,12 @@ var acaEnv = builder.AddAzureContainerAppEnvironment("production"); var cache = builder.AddRedis("cache"); // Add API with registry configuration -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(cache) .WithContainerRegistry(acaEnv); // Add frontend with registry configuration -var web = builder.AddProject("web") +var web = builder.AddDotnetProject("web", "../Web/Web.csproj") .WithReference(api) .WithContainerRegistry(acaEnv); @@ -557,12 +557,12 @@ const environment = await builder.addAzureContainerAppEnvironment("production"); const cache = await builder.addRedis("cache"); // Add API with registry configuration -const api = await builder.addProject("api", "../Api/Api.csproj"); +const api = await builder.addDotnetProject("api", "../Api/Api.csproj"); await api.withReference(cache); await api.withContainerRegistry(environment); // Add frontend with registry configuration -const web = await builder.addProject("web", "../Web/Web.csproj"); +const web = await builder.addDotnetProject("web", "../Web/Web.csproj"); await web.withReference(api); await web.withContainerRegistry(environment); diff --git a/src/frontend/src/content/docs/app-host/cors-configuration.mdx b/src/frontend/src/content/docs/app-host/cors-configuration.mdx index 6309eed803..4707519fe9 100644 --- a/src/frontend/src/content/docs/app-host/cors-configuration.mdx +++ b/src/frontend/src/content/docs/app-host/cors-configuration.mdx @@ -239,7 +239,7 @@ These examples assume a JavaScript frontend in `../frontend` with a `dev` script -This example assumes an existing `Api` project. A C# AppHost also needs a project reference to `Api`. Add the frontend and the API to your AppHost: +This example assumes an existing `Api` project. Add the frontend and the API to your AppHost: @@ -250,7 +250,7 @@ var builder = DistributedApplication.CreateBuilder(args); var frontend = builder.AddJavaScriptApp("frontend", "../frontend", "dev") .WithHttpEndpoint(port: 3000, env: "PORT"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(frontend) // Injects services__frontend__http__0 into the API .WithExternalHttpEndpoints(); @@ -270,7 +270,7 @@ const frontend = await builder.addJavaScriptApp('frontend', '../frontend', { }); await frontend.withHttpEndpoint({ port: 3000, env: 'PORT' }); -const api = await builder.addProject('api', '../Api/Api.csproj'); +const api = await builder.addDotnetProject('api', '../Api/Api.csproj'); await api.withReference(frontend); // Injects services__frontend__http__0 into the API await api.withExternalHttpEndpoints(); diff --git a/src/frontend/src/content/docs/app-host/docker-compose-to-apphost-reference.mdx b/src/frontend/src/content/docs/app-host/docker-compose-to-apphost-reference.mdx index fa440161dc..cc84511171 100644 --- a/src/frontend/src/content/docs/app-host/docker-compose-to-apphost-reference.mdx +++ b/src/frontend/src/content/docs/app-host/docker-compose-to-apphost-reference.mdx @@ -49,7 +49,7 @@ Learn more about [Docker Compose pull_policy](https://docs.docker.com/reference/ | Docker Compose | Aspire | Notes | |----------------|-------------|-------| -| `build: ./MyApi` (for .NET) | `builder.AddProject("myapi")` | Direct .NET project reference | +| `build: ./MyApi` (for .NET) | `builder.AddDotnetProject("myapi", "../MyApi/MyApi.csproj")` | Direct .NET project reference | Learn more about [adding .NET projects](/get-started/app-host/). diff --git a/src/frontend/src/content/docs/app-host/eventing.mdx b/src/frontend/src/content/docs/app-host/eventing.mdx index f45685daa8..cbdc4c6a3b 100644 --- a/src/frontend/src/content/docs/app-host/eventing.mdx +++ b/src/frontend/src/content/docs/app-host/eventing.mdx @@ -220,9 +220,9 @@ cache.OnConnectionStringAvailable( return Task.CompletedTask; }); -var apiService = builder.AddProject("apiservice"); +var apiService = builder.AddDotnetProject("apiservice", "../AspireApp.ApiService/AspireApp.ApiService.csproj"); -builder.AddProject("webfrontend") +builder.AddDotnetProject("webfrontend", "../AspireApp.Web/AspireApp.Web.csproj") .WithExternalHttpEndpoints() .WithReference(cache) .WaitFor(cache) diff --git a/src/frontend/src/content/docs/app-host/executable-resources.mdx b/src/frontend/src/content/docs/app-host/executable-resources.mdx index 118f282e60..b21858ce6e 100644 --- a/src/frontend/src/content/docs/app-host/executable-resources.mdx +++ b/src/frontend/src/content/docs/app-host/executable-resources.mdx @@ -175,7 +175,7 @@ Here's a complete example using the [Vercel CLI](https://vercel.com/docs/cli) to var builder = DistributedApplication.CreateBuilder(args); // Backend API -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithExternalHttpEndpoints(); // Frontend with Vercel CLI @@ -194,7 +194,7 @@ import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); // Backend API -const api = await builder.addProject("api", "./Api/Api.csproj") +const api = await builder.addDotnetProject("api", "./Api/Api.csproj") .withExternalHttpEndpoints(); // Frontend with Vercel CLI diff --git a/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx b/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx index c69a2f18d4..fa0c15a4ec 100644 --- a/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx +++ b/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx @@ -110,14 +110,14 @@ var database = builder.AddPostgres("postgres") .AddDatabase("myapp"); // Add the API project with proper dependencies -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../MyApp.Api/MyApp.Api.csproj") .WithHttpEndpoint(port: 5000) .WithHttpHealthCheck("/health") .WithReference(database, "DefaultConnection") .WaitFor(database); // Add the frontend project with dependencies -var frontend = builder.AddProject("frontend") +var frontend = builder.AddDotnetProject("frontend", "../MyApp.Frontend/MyApp.Frontend.csproj") .WithHttpEndpoint(port: 3000) .WithReference(api) .WithEnvironment("API_URL", api.GetEndpoint("http")) @@ -139,14 +139,14 @@ const database = (await builder.addPostgres("postgres") .addDatabase("myapp"); // Add the API project with proper dependencies -const api = await builder.addProject("api", "./MyApp.Api/MyApp.Api.csproj") +const api = await builder.addDotnetProject("api", "./MyApp.Api/MyApp.Api.csproj") .withHttpEndpoint({ port: 5000 }) .withHttpHealthCheck("/health") .withReference(database, "DefaultConnection") .waitFor(database); // Add the frontend project with dependencies -const frontend = await builder.addProject("frontend", "./MyApp.Frontend/MyApp.Frontend.csproj") +const frontend = await builder.addDotnetProject("frontend", "./MyApp.Frontend/MyApp.Frontend.csproj") .withHttpEndpoint({ port: 3000 }) .withReference(api) .withEnvironment("API_URL", api.getEndpoint("http")) @@ -158,12 +158,12 @@ await builder.build().run(); **Key differences explained:** -- **Build vs. project** — Docker Compose `build:` services become `AddProject()` for .NET apps, which runs them directly instead of in containers +- **Build vs. project** — Docker Compose `build:` services become `AddDotnetProject` resources for .NET apps, which runs them directly instead of in containers - **Ports** — Both examples explicitly map ports (3000 and 5000) - **Startup order** — Docker Compose uses `depends_on` with health conditions; Aspire uses for startup ordering - **Service discovery** — only configures service discovery and connection strings; it doesn't control startup order @@ -527,7 +527,7 @@ Successfully migrating from Docker Compose to Aspire requires a systematic appro - **Add backing services** like PostgreSQL, Redis with specific versions using `WithImageTag()` - **Add persistent storage** using `WithDataVolume()` where needed - - **Convert .NET applications** to project references with `AddProject()` for better integration + - **Convert .NET applications** to `AddDotnetProject` resources for better integration - **Convert Dockerfile-built containers** using `AddDockerfile()` to match `build:` directives - **Convert pre-built images** using `AddContainer()` to match `image:` directives - **Configure dependencies** with `WithReference()` for service discovery @@ -604,14 +604,14 @@ const app = await builder.addContainer("app", "myapp:latest") ```csharp title="AppHost.cs" -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(database) // Service discovery .WaitFor(database); // Startup ordering ``` ```typescript title="apphost.mts" -const api = await builder.addProject("api", "./Api/Api.csproj", "https") +const api = await builder.addDotnetProject("api", "./Api/Api.csproj", { launchProfileName: "https" }) .withReference(database) // Service discovery .waitFor(database); // Startup ordering ``` @@ -654,13 +654,13 @@ Docker Compose health checks use shell commands. Aspire integrations (like Postg ```csharp title="AppHost.cs" -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithHttpHealthCheck("/health"); ``` ```typescript title="apphost.mts" -const api = await builder.addProject("api", "./Api/Api.csproj", "https") +const api = await builder.addDotnetProject("api", "./Api/Api.csproj", { launchProfileName: "https" }) .withHttpHealthCheck("/health"); ``` @@ -683,7 +683,7 @@ var rabbit = builder.AddContainer("rabbitmq", "rabbitmq", "4.1.4-management-alpi .WithHealthCheck("rabbitmq-health"); // WaitFor uses the registered health check to determine readiness -var app = builder.AddProject("app") +var app = builder.AddDotnetProject("app", "../App/App.csproj") .WaitFor(rabbit); ``` @@ -693,7 +693,7 @@ const rabbit = await builder.addContainer("rabbitmq", "rabbitmq", "4.1.4-managem .withHealthCheck("rabbitmq-health"); // WaitFor uses the registered health check to determine readiness -const app = await builder.addProject("app", "./App/App.csproj", "https") +const app = await builder.addDotnetProject("app", "./App/App.csproj", { launchProfileName: "https" }) .waitFor(rabbit); ``` diff --git a/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx b/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx index 22214da3de..1cb9599393 100644 --- a/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx +++ b/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx @@ -148,7 +148,7 @@ var postgres = builder.AddPostgres("postgres") var db = postgres.AddDatabase("inventorydb"); -builder.AddProject("inventory") +builder.AddDotnetProject("inventory", "../InventoryService/InventoryService.csproj") .WithReference(db); builder.Build().Run(); @@ -168,7 +168,7 @@ await postgres.withDataVolume(); const db = postgres.addDatabase('inventorydb'); -const inventory = await builder.addProject( +const inventory = await builder.addDotnetProject( 'inventory', './InventoryService/InventoryService.csproj' ); @@ -231,7 +231,7 @@ Project resources can use persistent lifetimes when you want the project process ```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../ApiService/ApiService.csproj") .WithPersistentLifetime(); builder.Build().Run(); @@ -245,7 +245,7 @@ import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); -const api = await builder.addProject('api', '../ApiService/ApiService.csproj'); +const api = await builder.addDotnetProject('api', '../ApiService/ApiService.csproj'); await api.withPersistentLifetime(); await builder.build().run(); diff --git a/src/frontend/src/content/docs/app-host/resource-naming.mdx b/src/frontend/src/content/docs/app-host/resource-naming.mdx index 37ac26f44d..acf4569f2d 100644 --- a/src/frontend/src/content/docs/app-host/resource-naming.mdx +++ b/src/frontend/src/content/docs/app-host/resource-naming.mdx @@ -42,7 +42,7 @@ const builder = await createBuilder(); const cache = await builder.addRedis('cache'); -await builder.addProject('api', '../MyApi/MyApi.csproj').withReference(cache); +await builder.addDotnetProject('api', '../MyApi/MyApi.csproj').withReference(cache); await builder.build().run(); ``` @@ -55,7 +55,7 @@ var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../MyApi/MyApi.csproj") .WithReference(cache); builder.Build().Run(); @@ -107,12 +107,12 @@ const builder = await createBuilder(); const postgres = await builder.addPostgres('postgres'); const db = await postgres.addDatabase('app-db'); -const catalog = await builder.addProject( +const catalog = await builder.addDotnetProject( 'catalog-api', '../CatalogApi/CatalogApi.csproj' ); -const worker = await builder.addProject('worker', '../Worker/Worker.csproj'); +const worker = await builder.addDotnetProject('worker', '../Worker/Worker.csproj'); await worker.withReference(db); await worker.withReference(catalog); @@ -126,9 +126,9 @@ await builder.build().run(); var builder = DistributedApplication.CreateBuilder(args); var db = builder.AddPostgres("postgres").AddDatabase("app-db"); -var catalog = builder.AddProject("catalog-api"); +var catalog = builder.AddDotnetProject("catalog-api", "../CatalogApi/CatalogApi.csproj"); -builder.AddProject("worker") +builder.AddDotnetProject("worker", "../Worker/Worker.csproj") .WithReference(db) .WithReference(catalog); @@ -203,7 +203,7 @@ const appDb = await postgres.addDatabase('app-db'); const cache = await builder.addRedis('cache'); const messageBus = await builder.addRabbitMQ('message-bus'); -const api = await builder.addProject('api', '../Api/Api.csproj'); +const api = await builder.addDotnetProject('api', '../Api/Api.csproj'); await api.withReference(appDb); await api.withReference(cache); await api.withReference(messageBus); @@ -222,7 +222,7 @@ var appDb = postgres.AddDatabase("app-db"); var cache = builder.AddRedis("cache"); var messageBus = builder.AddRabbitMQ("message-bus"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(appDb) .WithReference(cache) .WithReference(messageBus); diff --git a/src/frontend/src/content/docs/app-host/with-terminal.mdx b/src/frontend/src/content/docs/app-host/with-terminal.mdx index 23863cb695..a2a1ff6a23 100644 --- a/src/frontend/src/content/docs/app-host/with-terminal.mdx +++ b/src/frontend/src/content/docs/app-host/with-terminal.mdx @@ -182,7 +182,7 @@ import { createBuilder } from './.aspire/modules/aspire.mjs'; const builder = await createBuilder(); await builder - .addProject('agent', '../Agent/Agent.csproj') + .addDotnetProject('agent', '../Agent/Agent.csproj') .withReplicas(3) .withTerminal(); @@ -192,13 +192,11 @@ await builder.build().run(); -Add a project reference to `Agent.csproj` in your AppHost before using its generated `Projects.Agent` type. - ```csharp title="AppHost.cs" #pragma warning disable ASPIRETERMINAL001 var builder = DistributedApplication.CreateBuilder(args); -builder.AddProject("agent") +builder.AddDotnetProject("agent", "../Agent/Agent.csproj") .WithReplicas(3) .WithTerminal(); diff --git a/src/frontend/src/content/docs/architecture/resource-hierarchies.mdx b/src/frontend/src/content/docs/architecture/resource-hierarchies.mdx index 53454ef946..680bc6f845 100644 --- a/src/frontend/src/content/docs/architecture/resource-hierarchies.mdx +++ b/src/frontend/src/content/docs/architecture/resource-hierarchies.mdx @@ -73,7 +73,7 @@ Aspire represents these relationships through a **heterogeneous Directed Acyclic var builder = DistributedApplication.CreateBuilder(args); var db = builder.AddPostgres("pg"); -var api = builder.AddProject("api").WithReference(db); +var api = builder.AddDotnetProject("api", "../Api/Api.csproj").WithReference(db); var web = builder.AddJavaScriptApp("web", "../web").WithReference(api); builder.Build().Run(); @@ -276,7 +276,7 @@ These properties are dynamically resolved during the application's startup seque ### `IResourceWithEndpoints` -Resources supporting endpoints should implement `IResourceWithEndpoints`, enabling the use of `GetEndpoint(name)` to retrieve an `EndpointReference`. This is implemented on the built-in `ProjectResource`, `ContainerResource` and `ExecutableResource`. It allows endpoints to be programmatically accessed and passed between resources. +Resources supporting endpoints should implement `IResourceWithEndpoints`, enabling the use of `GetEndpoint(name)` to retrieve an `EndpointReference`. This is implemented on the built-in `ContainerResource` and `ExecutableResource` types, including `DotnetProjectResource`. It allows endpoints to be programmatically accessed and passed between resources. ```csharp title="Example — Endpoint Access and Resolution" var builder = DistributedApplication.CreateBuilder(args); @@ -380,7 +380,7 @@ var builder = DistributedApplication.CreateBuilder(args); var redis = builder.AddContainer("redis", "redis") .WithEndpoint(name: "tcp", targetPort: 6379); -builder.AddProject("worker") +builder.AddDotnetProject("worker", "../Worker/Worker.csproj") .WithReference(redis.GetEndpoint("tcp")); builder.Build().Run(); @@ -398,7 +398,7 @@ var builder = DistributedApplication.CreateBuilder(args); var redis = builder.AddContainer("redis", "redis") .WithEndpoint(name: "tcp", targetPort: 6379); -builder.AddProject("worker") +builder.AddDotnetProject("worker", "../Worker/Worker.csproj") .WithEnvironment("RedisUrl", redis.GetEndpoint("tcp")); builder.Build().Run(); @@ -423,7 +423,7 @@ In C#, call `endpoint.Property(...)` to get that field. In TypeScript AppHosts, var redis = builder.AddContainer("redis", "redis") .WithEndpoint("tcp", 6379); -builder.AddProject("worker") +builder.AddDotnetProject("worker", "../Worker/Worker.csproj") .WithEnvironment(ctx => { var ep = redis.GetEndpoint("tcp"); @@ -448,7 +448,7 @@ const redisHost = await ep.property(EndpointProperty.Host); const redisPort = await ep.property(EndpointProperty.Port); await builder - .addProject('worker', '../Worker/Worker.csproj') + .addDotnetProject('worker', '../Worker/Worker.csproj') .withEnvironment('REDIS_HOST', redisHost) .withEnvironment('REDIS_PORT', redisPort); @@ -600,7 +600,7 @@ var builder = DistributedApplication.CreateBuilder(args); var keycloak = builder.AddKeycloak("keycloak", 8080); var grafana = builder.AddContainer("grafana", "grafana/grafana"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithEnvironment(async ctx => { var keyCloakEndpoint = keycloak.GetEndpoint("http"); @@ -636,7 +636,7 @@ var builder = DistributedApplication.CreateBuilder(args); var keycloak = builder.AddKeycloak("keycloak", 8080); var grafana = builder.AddContainer("grafana", "grafana/grafana"); -var api = builder.AddProject("api") +var api = builder.AddDotnetProject("api", "../Api/Api.csproj") .WithEnvironment(ctx => { var keyCloakEndpoint = keycloak.GetEndpoint("http"); diff --git a/src/frontend/src/content/docs/architecture/resource-model.mdx b/src/frontend/src/content/docs/architecture/resource-model.mdx index 668300b39c..ef2263506c 100644 --- a/src/frontend/src/content/docs/architecture/resource-model.mdx +++ b/src/frontend/src/content/docs/architecture/resource-model.mdx @@ -19,7 +19,7 @@ A quick example that shows the basic usage: var builder = DistributedApplication.CreateBuilder(args); var db = builder.AddPostgres("pg").AddDatabase("appdata"); -var api = builder.AddProject("api").WithReference(db); +var api = builder.AddDotnetProject("api", "../Api/Api.csproj").WithReference(db); var web = builder.AddJavaScriptApp("web", "../web").WithReference(api); builder.Build().Run(); @@ -40,7 +40,7 @@ architecture-beta -1. Use `.AddXyz(...)` helper methods to add and declare resources (e.g., `.AddPostgres(...)`, `.AddProject(...)`). +1. Use `.AddXyz(...)` helper methods to add and declare resources (e.g., `.AddPostgres(...)`, `.AddDotnetProject(...)`). 1. Use `.WithReference(...)` (or similar) to represent explicit dependencies between resources. 1. Call `Build().Run()` - Aspire builds the application model (graph) and executes it handling: @@ -83,7 +83,7 @@ Annotations allow attaching additional structured information to a resource with ### Fluent extension methods -Resources are typically added using fluent **extension methods** such as `.AddRedis(...)`, `.AddProject(...)`, or `.AddPostgres(...)`. Extension methods encapsulate: +Resources are typically added using fluent **extension methods** such as `.AddRedis(...)`, `.AddDotnetProject(...)`, or `.AddPostgres(...)`. Extension methods encapsulate: - **Construction** of the resource object. - **Attachment of annotations** that describe defaults, discovery hints, or runtime behavior. @@ -107,7 +107,7 @@ To continue from the previous example, here's how you can add resources and wire var builder = DistributedApplication.CreateBuilder(args); var db = builder.AddPostgres("pg").AddDatabase("appdata"); -var api = builder.AddProject("api").WithReference(db); +var api = builder.AddDotnetProject("api", "../Api/Api.csproj").WithReference(db); var web = builder.AddJavaScriptApp("web", "../web").WithReference(api); builder.Build().Run(); @@ -172,10 +172,9 @@ Aspire provides a set of fundamental built-in resource types that serve as the f |----------------------|---------------------------------------------------------| | `ContainerResource` | Runs Docker containers as resources. | | `ExecutableResource` | Launches arbitrary executables or scripts as resources. | -| `ProjectResource` | Runs a .NET project directly (build + launch workflow). | | `ParameterResource` | Represents a parameter or configuration value. | -These types are **infrastructure-oriented primitives**. They model how code and applications are packaged and executed. +These types are **infrastructure-oriented primitives**. They model how code and applications are packaged and executed. Language integrations build on them; for example, `DotnetProjectResource` from `Aspire.Hosting.Dotnet` is an `ExecutableResource` that builds and launches a .NET project.