From 4fb15f669f4dbe0a600e5eb2c6aa813644945a72 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 07:11:39 +0000 Subject: [PATCH] docs: update aspire init and add-to-existing-app for skill-driven aspirification Document the new two-phase aspire init behavior introduced in microsoft/aspire#15918: - aspire init now drops a skeleton AppHost + aspire.config.json and installs the aspireify agent skill instead of performing full project wiring itself - The --source and --version options are deprecated - Update aspire-init.mdx: new description, aspireify skill section, updated examples - Update add-aspire-existing-app.mdx: explain the two-phase init flow for both C# and TypeScript AppHosts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../get-started/add-aspire-existing-app.mdx | 441 +++++++++--------- .../reference/cli/commands/aspire-init.mdx | 57 ++- 2 files changed, 253 insertions(+), 245 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx b/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx index cf6676ff8..b1240a342 100644 --- a/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx +++ b/src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx @@ -1,6 +1,6 @@ --- title: "Add Aspire to an existing app" -description: "Add Aspire to an existing application by choosing an AppHost, modeling your existing resources, and running everything locally." +description: "Add Aspire to an existing application using aspire init and an AI coding agent, or by manually wiring resources in your AppHost." next: false --- @@ -8,7 +8,7 @@ import { FileTree, Steps, TabItem, Tabs } from '@astrojs/starlight/components'; import { Kbd } from 'starlight-kbd/components'; import LearnMore from '@components/LearnMore.astro'; -Add Aspire to the app you already have instead of rebuilding your solution around a new template. Start by choosing the AppHost style that fits your repo, then register the services, containers, shared infrastructure, and, when needed, custom executables you already run today, regardless of whether those workloads are written in C#, Node.js, Python, Go, Rust, Java, or something else. +Add Aspire to the app you already have instead of rebuilding your solution around a new template. The fastest path is `aspire init` paired with an AI coding agent that automatically discovers your services and wires them into an AppHost. If you prefer full control, manual steps are provided below. ## Why add Aspire to an existing app? @@ -16,42 +16,90 @@ As distributed applications grow, local development often turns into a collectio You can also adopt Aspire incrementally. Start by modeling the parts that are hardest to keep aligned by hand, such as containers, databases, caches, queues, background workers, and local dev commands. Add telemetry when you're ready, then deepen the model as your app grows. -## Start with your scenario +## Prerequisites + +Before you begin, make sure you have: + +- [Aspire CLI installed](/get-started/install-cli/) +- An existing application or workspace to add Aspire to +- The runtimes and tools your existing services already need + +### AppHost-specific requirements + + + + +- [.NET SDK 10.0 or later](/get-started/prerequisites/) +- Visual Studio 2022 17.13 or later, Visual Studio Code, or JetBrains Rider (optional) + + + + +- [Node.js 22 or later](https://nodejs.org/) +- npm, yarn, or pnpm + + + + +## Recommended: Use an AI coding agent with the "aspireify" skill + +The fastest way to add Aspire to an existing app is to let `aspire init` scaffold the skeleton, then hand off wiring to the **`aspireify` agent skill**. The skill handles resource discovery, dependency wiring, OpenTelemetry setup, and validation automatically. + + + +1. Run `aspire init` in your repo root: -This guide is organized around the kinds of resources you already manage rather than around a preferred service language. Aspire is multi-language by design, so one AppHost can orchestrate a system that spans C#, Node.js, Python, Go, Rust, Java, and other supported workloads. + ```bash title="Initialize Aspire" + aspire init + ``` + + Choose your AppHost language (C# or TypeScript) when prompted, or pass `--language csharp` / `--language typescript`. The command creates a minimal AppHost file, an `aspire.config.json`, and installs the `aspireify` skill into your agent's skill directory. -- **Existing services with hosting integrations**: You already have C# services, Node.js apps, Vite frontends, Python apps, or ASGI apps such as FastAPI and want to use Aspire's dedicated hosting APIs. -- **Existing containers and shared infrastructure**: You already have images, Docker Compose files, databases, caches, queues, or reverse proxies that you want Aspire to coordinate. -- **Existing C# services**: You already have C# projects or file-based C# apps and want the C# AppHost to orchestrate them directly. + :::note[The AppHost language doesn't limit what you can orchestrate] + Whether you choose a C# or TypeScript AppHost, Aspire can orchestrate services written in any language — C#, JavaScript, Python, Go, Rust, Java, containers, and more. The AppHost language is just how you express the orchestration, not a constraint on the workloads. + ::: -In every scenario, you can choose either AppHost style and mix resource types in the same application model. +2. Ask your AI coding agent to run the `aspireify` skill. The agent will: -When a dedicated hosting API exists for a workload, prefer it over `AddExecutable` or `addExecutable`. Executable resources are the fallback for custom tools, one-off commands, or workloads that do not yet have a dedicated hosting integration. + - Scan your repo and discover existing projects, services, containers, and infrastructure + - Ask you to confirm the resources it found, which ones you want included, and other clarifying questions before starting + - Wire resources into the AppHost with `WithReference`, `WaitFor`, endpoints, and volumes + - Add ServiceDefaults and configure OpenTelemetry for each service + - Validate the setup by running `aspire start` + +3. Once the agent reports success, run `aspire start` yourself and open the dashboard to verify everything looks correct. Something not right? Tell the agent-it has plenty of tools from Aspire to troubleshoot! + + -## Choose your AppHost + + +For more details on the `aspire init` command and the aspireify skill, see the [CLI reference: `aspire init`](/reference/cli/commands/aspire-init/). + + +:::tip[Works with any AI coding agent] +The aspireify skill works with GitHub Copilot, Claude Code, or any MCP-compatible assistant. It reads your repo structure and applies the same wiring patterns described in the manual sections below. +::: + +--- + +## Wire your AppHost manually + +If you prefer full control over the wiring, or want to understand what the aspireify skill does under the hood, follow the manual steps below. This is also the reference for anyone extending or customizing an AppHost after the initial setup. + +### Choose your AppHost The AppHost is the orchestration layer. Your choice here changes how you express orchestration, not what Aspire can orchestrate. -Use a C# AppHost when your repo already centers on C# or when you want a single-file orchestrator that still fits naturally into .NET SDK and IDE workflows. +Aspire offers two C# AppHost styles: + +**File-based AppHost** — a single `apphost.cs` file that uses `#:sdk` and `#:package` directives. No `.csproj`, no solution integration required. Best for polyglot repos or quick setups. -- Lives in a single `apphost.cs` file that uses `#:sdk` and `#:package` directives -- Common APIs include: +**Project-based AppHost** — a traditional `AppHost.csproj` that lives inside a `.sln` alongside your other C# projects. Uses `ProjectReference` items and the generated `Projects` namespace for strongly-typed `AddProject()` calls. Best when your repo is already a .NET solution and you want IDE-integrated orchestration. - | API | Description | - | --- | --- | - | `AddContainer()` | Run a prebuilt container image that already exists in your current workflow. | - | `AddCSharpApp()` | Point a file-based AppHost at an existing C# app or `.csproj` without creating a separate AppHost project graph. | - | `AddDockerfile()` | Build and run a container from an existing Dockerfile in your repo. | - | `AddExecutable()` | Fall back to a custom command when a dedicated hosting API does not exist yet. | - | `AddJavaScriptApp()`, `AddNodeApp()`, `AddViteApp()` | Model JavaScript and TypeScript workloads, from general package-script apps to Node entrypoints and Vite frontends. | - | `AddParameter()` | Define reusable config values and secrets for the resources in your model. | - | `AddPostgres()`, `AddRedis()` | Add shared infrastructure with first-class integrations and connection wiring. | - | `AddPythonApp()`, `AddUvicornApp()` | Model Python scripts, workers, and ASGI apps such as FastAPI. | - | `WaitFor()`, `WithHttpEndpoint()`, `WithReference()` | Wire service discovery, startup ordering, and HTTP endpoints between resources. | -- Fits naturally into existing .NET SDK, IDE, and repo workflows +Both styles use the same `Aspire.AppHost.Sdk` and the same hosting APIs. @@ -59,204 +107,223 @@ Use a C# AppHost when your repo already centers on C# or when you want a single- Use a TypeScript AppHost when your repo already centers on a Node.js workspace or when you prefer path-based orchestration in TypeScript. - Lives in `apphost.ts` -- Common APIs include: - - | API | Description | - | --- | --- | - | `addContainer()` | Run a prebuilt container image that you already publish or pull today. | - | `addCSharpApp()` | Point at an existing C# app, `.csproj`, or directory directly from a TypeScript AppHost without relying only on `addProject()`. | - | `addDockerfile()` | Build and run a container directly from a Dockerfile in the repo. | - | `addExecutable()` | Fall back to a custom command for unsupported runtimes or one-off tools. | - | `addNodeApp()`, `addViteApp()` | Model Node.js services and Vite frontends with JavaScript-aware defaults. | - | `addParameter()` | Define reusable config values and secrets that multiple resources can consume. | - | `addPostgres()`, `addRedis()` | Add shared infrastructure with first-class integrations and references. | - | `addProject()` | Add an existing project by path, such as a `.csproj`, into a TypeScript AppHost. | - | `addPythonApp()`, `addUvicornApp()` | Model Python scripts, workers, and ASGI apps such as FastAPI. | - | `waitFor()`, `withHttpEndpoint()`, `withReference()` | Wire service discovery, startup ordering, and HTTP endpoints between resources. | +- Runs under popular package managers including npm, pnpm, yarn, and Bun - Fits naturally into existing package-manager and monorepo workflows :::tip[No runtime lock-in] -Both AppHost styles can orchestrate multi-language systems. You can mix C#, Node.js, Python, Go, Rust, Java, containers, and supported integrations in the same application model, and use executable resources when you truly need a custom command path. Pick the AppHost that best fits your repo and team, not the one that matches a single workload. +Both AppHost styles can orchestrate multi-language systems. You can mix C#, Node.js, Python, Go, Rust, Java, containers, and supported integrations in the same application model. Pick the AppHost that best fits your repo and team, not the one that matches a single workload. ::: -## Prerequisites - -Before you begin, make sure you have: - -- [Aspire CLI installed](/get-started/install-cli/) -- An existing application or workspace to add Aspire to -- The runtimes and tools your existing services already need - -### AppHost-specific requirements +### Set up your AppHost -- [.NET SDK 10.0 or later](/get-started/prerequisites/) -- Visual Studio 2022 17.13 or later, Visual Studio Code, or JetBrains Rider (optional) +#### File-based AppHost (default) - - +Use a file-based AppHost when you want a lightweight single-file orchestrator without adding a project to your solution. This is the default style created by `aspire init` when no `.sln` is detected. -- [Node.js 22 or later](https://nodejs.org/) -- npm, yarn, or pnpm + - - +1. Run `aspire init` from your repo root. Without a `.sln` present, it creates a file-based `apphost.cs`: -### Scenario-specific requirements + ```bash title="Initialize Aspire with a file-based AppHost" + aspire init + ``` -**For workloads with hosting integrations:** +2. Add hosting integrations: -- Service directories and standard project metadata for the workloads you plan to model, such as `package.json`, `pyproject.toml`, or `requirements.txt` -- The runtimes and package managers those services already need + ```bash title="Add hosting integrations" + aspire add redis + ``` -**For custom executables as a fallback:** +3. Wire the resources in `apphost.cs`: -- Working start commands for each service you plan to model -- Any repo-local config files or working directories those commands rely on + ```csharp title="apphost.cs" + #:sdk Aspire.AppHost.Sdk@13.2.0 + #:package Aspire.Hosting.Redis@13.2.0 -**For containers and shared infrastructure:** + #pragma warning disable ASPIRECSHARPAPPS001 -- Existing image names, Dockerfiles, or Compose knowledge for the services you want to model -- The databases, caches, queues, or reverse proxies you want Aspire to own or connect to + var builder = DistributedApplication.CreateBuilder(args); -**For C# services:** + var cache = builder.AddRedis("cache"); -- One or more C# projects or file-based C# apps if you plan to use `AddCSharpApp` -- A solution file is optional and not required for a file-based C# AppHost + var api = builder.AddCSharpApp("api", "./src/Api/MyApp.Api.csproj") + .WithReference(cache) + .WithHttpHealthCheck("/health"); -## Overview of the process + var worker = builder.AddCSharpApp("worker", "./src/Worker/MyApp.Worker.csproj") + .WithReference(cache); -Adding Aspire to an existing app usually follows these steps: + builder.Build().Run(); + ``` - + -1. **Choose an AppHost** that fits your repo and workflow. -2. **Initialize Aspire support** with `aspire init`. -3. **Register your existing processes, containers, and shared resources** in the AppHost. -4. **Add telemetry and integrations** where they add value. -5. **Run and verify** the full system with Aspire orchestration. +After setup, a typical repo layout looks like this: - + + - apphost.cs (new) + - aspire.config.json (new) + - src/ + - Api/ + - MyApp.Api.csproj + - Worker/ + - MyApp.Worker.csproj + -## Initialize Aspire support +:::caution[AddCSharpApp is experimental] +`AddCSharpApp` is currently experimental. If you want details on limitations or diagnostic suppression, see [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/). +::: -The `aspire init` command creates the orchestration layer and helps wire the first set of resources into it. +#### Project-based AppHost (with a .sln) - - +Use this approach when your repo is already a .NET solution (`.sln` or `.slnx`) with multiple projects. The project-based AppHost uses `ProjectReference` items and the generated `Projects` namespace for strongly-typed `AddProject()` calls, giving you full IDE support including IntelliSense, refactoring, and build-order awareness. -1. Navigate to the root of your existing repo: +1. Run `aspire init` from your solution root. It detects the `.sln` and creates a project-based AppHost automatically: - ```bash title="Navigate to your repo" - cd /path/to/your-repo + ```bash title="Initialize Aspire in a .NET solution" + aspire init ``` -2. Run `aspire init`: +2. Add project references from the AppHost to each service you want to orchestrate: - ```bash title="Initialize Aspire with a C# AppHost" - aspire init + ```bash title="Add project references" + dotnet add MyApp.AppHost reference src/Api/MyApp.Api.csproj + dotnet add MyApp.AppHost reference src/Web/MyApp.Web.csproj + dotnet add MyApp.AppHost reference src/Worker/MyApp.Worker.csproj ``` - The command runs in interactive mode by default. It can detect existing C# projects, create a single-file AppHost, and add the initial package directives and configuration it needs. +3. Add hosting integrations: - + ```bash title="Add hosting integrations" + aspire add redis + aspire add postgres + ``` - -For more details on the `aspire init` command and its options, see the [CLI reference: `aspire init`](/reference/cli/commands/aspire-init/). - +4. Wire the resources in the AppHost's `Program.cs`: -After initialization, a typical C#-centric repo might look like this: + ```csharp title="MyApp.AppHost/Program.cs" + var builder = DistributedApplication.CreateBuilder(args); - - - apphost.cs (new) - - apphost.run.json (new) - - services/ - - Api/ - - ExampleEcommerce.Api.csproj - - Web/ - - package.json - - src/ - - workers/ - - inventory-sync/ - - worker.py - + var cache = builder.AddRedis("cache") + .WithLifetime(ContainerLifetime.Persistent); -Starter AppHost: + var db = builder.AddPostgres("postgres") + .WithLifetime(ContainerLifetime.Persistent) + .AddDatabase("mydb"); -```csharp title="apphost.cs — Initial state" -#:sdk Aspire.AppHost.Sdk@13.3.0 + var api = builder.AddProject("api") + .WithReference(db) + .WithReference(cache) + .WaitFor(db); -var builder = DistributedApplication.CreateBuilder(args); + builder.AddProject("web") + .WithReference(api) + .WaitFor(api); -// TODO: Add resources here + builder.AddProject("worker") + .WithReference(cache) + .WithReference(db); -builder.Build().Run(); -``` + builder.Build().Run(); + ``` + + -Add `#:package` directives in `apphost.cs` for the hosting integrations you use, such as `Aspire.Hosting.Redis`, `Aspire.Hosting.Python`, `Aspire.Hosting.JavaScript`, and `Aspire.Hosting.PostgreSQL`. +After setup, a typical solution layout looks like this: + + + - MyApp.sln + - MyApp.AppHost/ + - MyApp.AppHost.csproj + - Program.cs + - MyApp.ServiceDefaults/ + - MyApp.ServiceDefaults.csproj + - Extensions.cs + - src/ + - Api/ + - MyApp.Api.csproj + - Web/ + - MyApp.Web.csproj + - Worker/ + - MyApp.Worker.csproj + + +:::note[ProjectReference wiring] +Each `ProjectReference` in the AppHost triggers a source generator that creates a class in the `Projects` namespace. When you call `AddProject("api")`, Aspire knows the project path and how to build and launch it. See [Aspire SDK](/get-started/aspire-sdk/) for details on how project references and metadata generation work. +::: + + +For the full `AddProject` workflow including custom type names, multi-project solutions, and launch profiles, see [Project resources](/integrations/dotnet/project-resources/). + -1. Navigate to the root of your existing workspace or repo: +1. Run `aspire init` from your workspace root with the TypeScript language option: - ```bash title="Navigate to your workspace or repo" - cd /path/to/your-workspace + ```bash title="Initialize Aspire with a TypeScript AppHost" + aspire init --language typescript ``` -2. Run `aspire init` with the TypeScript AppHost option: +2. Add hosting integrations: - ```bash title="Initialize Aspire with a TypeScript AppHost" - aspire init --language typescript + ```bash title="Add hosting integrations" + aspire add redis + aspire add postgres ``` - If you omit `--language typescript`, choose **TypeScript** when the CLI prompts for the AppHost language. +3. Wire the resources in `apphost.ts`: - + ```typescript title="apphost.ts" twoslash + import { createBuilder } from './.modules/aspire.js'; - -For more details on the `aspire init` command and its options, see the [CLI reference: `aspire init`](/reference/cli/commands/aspire-init/). - + const builder = await createBuilder(); -After initialization, a typical workspace might look like this: + const cache = await builder.addRedis('cache'); - - - my-store/ - - **apphost.ts** (new) - - **.modules/** (new) - - **aspire.config.json** (new) - - **package.json** (new or updated) - - services/ - - api/ - - Dockerfile - - web/ - - package.json - - src/ - - workers/ - - inventory-sync/ - - worker.py - + const db = (await builder.addPostgres('postgres')).addDatabase('mydb'); -Starter AppHost: + const api = await builder + .addProject('api', './src/Api/MyApp.Api.csproj') + .withReference(db) + .withReference(cache) + .waitFor(db); -```typescript title="apphost.ts — Initial state" twoslash -import { createBuilder } from './.modules/aspire.js'; + await builder + .addViteApp('web', './services/web') + .withReference(api) + .waitFor(api); -const builder = await createBuilder(); + await builder.build().run(); + ``` -// Add your resources here + -await builder.build().run(); -``` +After setup, a typical workspace layout looks like this: + + + - apphost.ts (new) + - .modules/ (new) + - aspire.config.json (new) + - package.json (new or updated) + - services/ + - web/ + - package.json + - src/ + - src/ + - Api/ + - MyApp.Api.csproj + :::note[The .modules folder is generated] Let the Aspire CLI manage `.modules/` rather than editing generated SDK files manually. @@ -265,17 +332,6 @@ Let the Aspire CLI manage `.modules/` rather than editing generated SDK files ma -## Model your existing apps in the AppHost - -Once you have an AppHost, use it to model the parts of your system that matter during local development: workloads, supporting infrastructure, and the connections between them. A resource does not need to mirror every repo boundary or implementation detail; it should represent something Aspire needs to start, observe, or connect. - -Think first about relationships: which workloads consume which backing services, which endpoints need to be reachable, and which resources must be ready before others can do useful work. - -The same patterns apply across AppHost styles: - -- Use `WithReference` or `withReference` to express that one resource depends on another and to flow connection information through the model. -- Use `WaitFor` or `waitFor` when readiness matters and one resource should not start until another is available. - ### Scenario: Existing services with hosting integrations Use this approach when Aspire already has a first-class resource type for the workload you want to run. That keeps the application model focused on what the service is and what it depends on, instead of reducing it to a generic shell command. @@ -418,63 +474,6 @@ await builder.build().run(); -### Scenario: Existing C# services - -Use this approach when your repo already contains .NET services that should stay where they are. The goal is to register those services as resources by pointing at their existing paths, then connect the infrastructure, endpoints, and health checks they already need as part of the larger application model. - -In a file-based C# AppHost, `AddCSharpApp` is the direct way to point at an existing C# service path. This works with single-file C# apps, directories, or existing `.csproj` files. - -:::caution[AddCSharpApp is experimental] -`AddCSharpApp` is currently experimental. If you want details on limitations or diagnostic suppression, see [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/). -::: - - - - -```csharp title="apphost.cs — Existing C# services" -#:sdk Aspire.AppHost.Sdk@13.3.0 -#:package Aspire.Hosting.Redis@13.3.0 - -#pragma warning disable ASPIRECSHARPAPPS001 - -var builder = DistributedApplication.CreateBuilder(args); - -var cache = builder.AddRedis("cache"); - -var api = builder.AddCSharpApp("api", "./src/Api/Store.Api.csproj") - .WithReference(cache) - .WithHttpHealthCheck("/health"); - -var worker = builder.AddCSharpApp("worker", "./src/Worker/Store.Worker.csproj") - .WithReference(cache); - -builder.Build().Run(); -``` - - - - -```typescript title="apphost.ts — Existing C# services" twoslash -import { createBuilder } from './.modules/aspire.js'; - -const builder = await createBuilder(); - -const cache = await builder.addRedis('cache'); - -const api = await builder - .addProject('api', './src/Api/Store.Api.csproj') - .withReference(cache) - .withHttpHealthCheck({ path: '/health' }); - -await builder - .addProject('worker', './src/Worker/Store.Worker.csproj') - .withReference(cache); - -await builder.build().run(); -``` - - - ### Scenario: Docker Compose @@ -562,7 +561,7 @@ await builder.build().run(); These scenarios are starting points, not mutually exclusive modes. Most real apps mix workload-specific resources, containers, shared infrastructure, project-path references, and occasional custom commands in a single application model. The key is that dependencies, endpoints, configuration, and startup behavior become explicit. -For more examples, see [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/), [Executable resources](/app-host/executable-resources/), and [Migrate from Docker Compose](/app-host/migrate-from-docker-compose/). +For more examples, see [Project resources](/integrations/dotnet/project-resources/), [C# file-based apps](/integrations/dotnet/csharp-file-based-apps/), [Executable resources](/app-host/executable-resources/), and [Migrate from Docker Compose](/app-host/migrate-from-docker-compose/). ## Add telemetry configuration (optional) @@ -576,7 +575,7 @@ If your app includes C# services, ServiceDefaults is the standard way to add obs -1. Add ServiceDefaults if you did not enable it during `aspire init`: +1. Create a ServiceDefaults project and reference it from your service: ```bash title="Add ServiceDefaults" dotnet new aspire-servicedefaults -n YourProject.ServiceDefaults diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx index 580a34127..9a3210824 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx @@ -1,10 +1,10 @@ --- title: aspire init command -description: Learn about the aspire init command and how it scaffolds a C# or TypeScript AppHost in an existing codebase. +description: Learn about the aspire init command and how it uses the aspireify agent skill to wire up Aspire support in an existing codebase. --- import AsciinemaPlayer from '@components/AsciinemaPlayer.astro'; - +import { Aside } from '@astrojs/starlight/components'; import Include from '@components/Include.astro'; ## Name @@ -21,28 +21,42 @@ aspire init [options] ## Description -The `aspire init` command initializes Aspire support in an existing repo or workspace. It can scaffold a single-file **C# AppHost** or a **TypeScript AppHost**, then wire up the initial configuration you need to start modeling a distributed application without creating an entirely new solution structure. +The `aspire init` command initializes Aspire support in an existing repo or workspace. It scaffolds a minimal AppHost skeleton together with an `aspire.config.json`, then optionally installs the **`aspireify` agent skill** so your AI coding agent can complete the wiring. -This command defaults to **interactive** mode. When executed without any options, the command prompts you for the necessary information, including the AppHost language when more than one path is available. When the `--version` and `--source` options are provided, the command runs **non-interactive** mode. +This command defaults to **interactive** mode. When executed without any options, the command prompts you for the AppHost language when more than one path is available. -The command performs the following actions: + -1. Analyze your existing repo or workspace structure -2. Create the necessary C# or TypeScript AppHost -3. Install required Aspire packages -4. Set up the initial configuration for orchestration +### AppHost detection -## Options +The command adapts to the repo it finds: -The following options are available: +- **C# file-based AppHost** (when selected interactively) — creates `apphost.cs` with `#:sdk` and `#:package` directives for a lightweight single-file orchestrator. +- **TypeScript AppHost** (when selected interactively) — creates `apphost.ts` with the generated `.modules/` folder. + +:::note +When a `.sln` or `.slnx` is present, the C# option creates a **project-based AppHost** instead — an `AppHost.csproj` added to the solution with `ProjectReference` items and strongly-typed `AddProject()` calls. +::: -- **`-s, --source`** +In all cases, the AppHost language does not limit what you can orchestrate — C#, JavaScript, Python, Go, Rust, Java, containers, and more can all be modeled in the same application model. - The NuGet source to use for the project templates. +### The aspireify skill -- **`-v, --version`** +After the skeleton is dropped, `aspire init` has an option to install the `aspireify` skill into your AI agent's skill directory (the same directory used by `aspire agent init`). The skill is a Markdown file with instructions that guide your AI coding agent through completing the Aspire wiring for your specific codebase. + +The skill instructs the agent to: + +- Scan the repo and discovering existing projects, services, and containers +- Ask you clarifying questions before making decisions — for example, which services to orchestrate, whether a hardcoded port is significant, or whether to map an existing env var or switch to Aspire's service discovery +- Wire resources into the AppHost with `WithReference`, `WaitFor`, endpoints, and volumes +- Optionally configure OpenTelemetry +- Validate the wiring with a smoke-test `aspire start` + +## Options - The version of the project templates to use. +The following options are available: - **`--channel`** @@ -72,20 +86,15 @@ The following options are available: aspire init ``` -- Initialize Aspire support using a specific template version: - - ```bash title="Aspire CLI" - aspire init --version 13.3.0 - ``` -- Initialize Aspire support from a custom NuGet source: +- Initialize Aspire support with a TypeScript AppHost: ```bash title="Aspire CLI" - aspire init --source https://api.nuget.org/v3/index.json --version 13.3.0 + aspire init --language typescript ``` -- Initialize Aspire support with a TypeScript AppHost: +- Initialize Aspire support using the `daily` channel templates: ```bash title="Aspire CLI" - aspire init --language typescript + aspire init --channel daily ```