From b5b7efa53cd0f98fb5d0767ca41be952ed968e36 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Wed, 12 Aug 2026 15:21:55 +0100 Subject: [PATCH 1/6] Ensured the use of polyglot is consistent and linked first uses to a definition in the glossary. --- src/frontend/src/content/docs/app-host/with-terminal.mdx | 2 +- .../src/content/docs/diagnostics/aspireexport010.mdx | 2 +- .../src/content/docs/diagnostics/aspireexport013.mdx | 2 +- .../src/content/docs/diagnostics/aspireexport015.mdx | 2 +- .../extensibility/multi-language-integration-authoring.mdx | 2 +- .../content/docs/get-started/add-aspire-existing-app.mdx | 2 +- .../content/docs/get-started/aspire-vscode-extension.mdx | 2 +- src/frontend/src/content/docs/get-started/faq.mdx | 2 +- src/frontend/src/content/docs/get-started/glossary.mdx | 6 ++++++ .../cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx | 2 +- .../docs/integrations/cloud/azure/azure-log-analytics.mdx | 2 +- .../cloud/azure/azure-postgresql/azure-postgresql-host.mdx | 2 +- .../azure/azure-sql-database/azure-sql-database-host.mdx | 2 +- .../docs/integrations/cloud/azure/azure-virtual-network.mdx | 2 +- .../docs/integrations/databases/ravendb/ravendb-host.mdx | 2 +- .../integrations/databases/surrealdb/surrealdb-host.mdx | 2 +- .../src/content/docs/integrations/devtools/dev-tunnels.mdx | 2 +- .../docs/integrations/devtools/flagd/flagd-connect.mdx | 2 +- .../docs/integrations/devtools/flagd/flagd-get-started.mdx | 2 +- .../src/content/docs/integrations/frameworks/go/go-host.mdx | 2 +- .../extensibility/multi-language-integration-authoring.mdx | 2 ++ .../content/docs/reference/cli/commands/aspire-start.mdx | 2 +- .../src/content/docs/reference/cli/configuration.mdx | 2 +- .../docs/reference/cli/includes/config-settings-table.md | 2 +- src/frontend/src/content/docs/whats-new/aspire-13-3.mdx | 2 +- src/frontend/src/content/docs/whats-new/aspire-13-4.mdx | 2 +- src/frontend/src/content/docs/whats-new/aspire-13-5.mdx | 2 +- 27 files changed, 33 insertions(+), 25 deletions(-) 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 1e65c6147..b9f7759c8 100644 --- a/src/frontend/src/content/docs/app-host/with-terminal.mdx +++ b/src/frontend/src/content/docs/app-host/with-terminal.mdx @@ -111,7 +111,7 @@ await builder.build().run(); ``` diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx index 1df6f51b7..28a8bddcd 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> Exported builder method '{0}' directly invokes synchronous delegate parameter '{1}'. Defer the callback, expose an async delegate, or set RunSyncOnBackgroundThread = true to avoid polyglot deadlocks. +> Exported builder method '{0}' directly invokes synchronous delegate parameter '{1}'. Defer the callback, expose an async delegate, or set RunSyncOnBackgroundThread = true to avoid [polyglot](/get-started/glossary/#polyglot) deadlocks. This diagnostic warning is reported when an `[AspireExport]` method directly invokes a synchronous delegate parameter inline, inside the method body. In a multi-language (polyglot) app host, callbacks crossing the language boundary are dispatched through an async messaging channel. If a synchronous callback is invoked inline, it can block the calling thread while the message dispatcher is also waiting on the same thread, causing a deadlock. To avoid this, the callback should be deferred, exposed as an async delegate, or run on a background thread. diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx index ffcf1f8ca..4b9ca7c65 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> Polyglot capability ID '{0}' is defined by multiple exports in this assembly: {1}. Use unique AspireExport IDs for overloaded or colliding members. +> [Polyglot](/get-started/glossary/#polyglot) capability ID '{0}' is defined by multiple exports in this assembly: {1}. Use unique AspireExport IDs for overloaded or colliding members. This diagnostic warning is reported when two or more Aspire Type System (ATS) exports in the same assembly generate the same runtime capability ID. The capability ID is used to dispatch calls from TypeScript, Python, Java, and other AppHost runtimes back to the hosting integration. Unlike C# method signatures, a capability ID doesn't include the receiver type, parameter list, or overload signature, so exports that are distinct in C# can still collide at runtime. diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx index cbaa12d27..468ff2445 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> AspireExport Description is compatibility metadata. Use XML documentation with ATS tags such as `` for generated polyglot SDK documentation. +> AspireExport Description is compatibility metadata. Use XML documentation with ATS tags such as `` for generated [polyglot](/get-started/glossary/#polyglot) SDK documentation. This diagnostic error is reported when a new `[AspireExport]` attribute sets the `Description` property. Starting in Aspire 13.4, the ATS scanner uses XML doc comments as the primary source for generated polyglot SDK documentation. The `Description` property is supported only as a compatibility fallback and should not be used on new exports. diff --git a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx index 8d5b8cdda..d31d56ab8 100644 --- a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx +++ b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx @@ -119,7 +119,7 @@ XML doc comments are the primary source for generated SDK API documentation. The Use `ats-*` override tags when the standard C# XML documentation doesn't translate well to generated SDK docs — for example, when a `` references C#-specific types or language constructs that have no direct equivalent in TypeScript. The supported overrides are: -- `` — overrides `` in polyglot docs +- `` — overrides `` in [polyglot](/get-started/glossary/#polyglot) docs - `` — overrides `` for a specific parameter - `` — overrides `` - `` — overrides `` 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 8886bbfc8..b19173d68 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 @@ -96,7 +96,7 @@ The AppHost is the orchestration layer. Your choice here changes how you express 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. +**File-based AppHost** — a single `apphost.cs` file that uses `#:sdk` and `#:package` directives. No `.csproj`, no solution integration required. Best for repos with [polyglot](/get-started/glossary/#polyglot) code or quick setups. **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. diff --git a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx index 4c2fd2d72..0020c353f 100644 --- a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx @@ -14,7 +14,7 @@ import debugSessions from '@assets/get-started/code-extension-debug.png'; import debugSessionsLight from '@assets/get-started/code-extension-debug-light.png'; import { Kbd } from 'starlight-kbd/components'; -The official Aspire extension for [Visual Studio Code](https://code.visualstudio.com/) turns VS Code into a first-class environment for building, debugging, and shipping polyglot Aspire apps. +The official Aspire extension for [Visual Studio Code](https://code.visualstudio.com/) turns VS Code into a first-class environment for building, debugging, and shipping C# and [polyglot](/get-started/glossary/#polyglot) Aspire apps. Press to build your AppHost, start your resources, and debug supported resource types — C#, TypeScript, Python, browser apps, and Azure Functions — alongside the Aspire dashboard. :::note[Prerequisites] diff --git a/src/frontend/src/content/docs/get-started/faq.mdx b/src/frontend/src/content/docs/get-started/faq.mdx index ecb50e2fa..7b72b775c 100644 --- a/src/frontend/src/content/docs/get-started/faq.mdx +++ b/src/frontend/src/content/docs/get-started/faq.mdx @@ -10,7 +10,7 @@ This page answers common questions about what Aspire is, how it fits into your w Aspire is an agent-ready, code-first tool to compose, debug, and deploy any distributed app. It makes it easier to build, run, debug, and deploy services across any language, stack, or cloud. It's free and open source at [github.com/microsoft/aspire](https://github.com/microsoft/aspire). -Its central idea is the **AppHost**: the place where you declare your services, resources, dependencies, endpoints, parameters, and relationships in code instead of scattering that information across many config files. AppHosts can be written in **C# or TypeScript**, which makes Aspire a strong fit for polyglot teams. +Its central idea is the **AppHost**: the place where you declare your services, resources, dependencies, endpoints, parameters, and relationships in code instead of scattering that information across many config files. AppHosts can be written in **C# or TypeScript**, which makes Aspire a strong fit for teams that use [polyglot](/get-started/glossary/#polyglot) code. Learn more: [Build your first Aspire app](/get-started/first-app/) diff --git a/src/frontend/src/content/docs/get-started/glossary.mdx b/src/frontend/src/content/docs/get-started/glossary.mdx index 332b575ec..8cbe7f47b 100644 --- a/src/frontend/src/content/docs/get-started/glossary.mdx +++ b/src/frontend/src/content/docs/get-started/glossary.mdx @@ -72,6 +72,12 @@ Aspire helps you orchestrate all these pieces together. When you add `builder.AddServiceDefaults()` to a project, you get production-ready observability and resilience out of the box. +### Polyglot + +In this repository, **polyglot** means relating to code written in any language other than C#. + +Examples include TypeScript, Python, Go, Java, and Rust code as used in AppHosts, generated SDKs, or related tooling. + --- ## APIs and patterns diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx index eb0d27c5b..a700e0628 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx @@ -831,7 +831,7 @@ builder.AddFoundry("foundry") TypeScript AppHosts can use curated provisioning helper APIs when an integration exposes them. This example directly customizes Azure.Provisioning objects through `ConfigureInfrastructure`, which is currently C#-only unless - the integration wraps the scenario in a polyglot-friendly helper. + the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper. The preceding code: diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx index 40d437b04..95da2c645 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-log-analytics.mdx @@ -232,7 +232,7 @@ var appInsights = builder.AddAzureApplicationInsights("app-insights", logAnalyti TypeScript AppHosts can use curated provisioning helper APIs when an integration exposes them. This example directly customizes Azure.Provisioning objects through `ConfigureInfrastructure`, which is currently C#-only unless - the integration wraps the scenario in a polyglot-friendly helper. + the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper. The preceding code: diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx index b17ad7c81..e891bea61 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-postgresql/azure-postgresql-host.mdx @@ -483,7 +483,7 @@ builder.Build().Run(); TypeScript AppHosts can use curated provisioning helper APIs when an integration exposes them. This example directly customizes Azure.Provisioning objects through `ConfigureInfrastructure`, which is currently C#-only unless - the integration wraps the scenario in a polyglot-friendly helper. + the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper. The preceding code: diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx index e36f2d7f0..c6ee296cd 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx @@ -340,7 +340,7 @@ builder.Build().Run(); TypeScript AppHosts can use curated provisioning helper APIs when an integration exposes them. This example directly customizes Azure.Provisioning objects through `ConfigureInfrastructure`, which is currently C#-only unless - the integration wraps the scenario in a polyglot-friendly helper. + the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper. The preceding code: diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx index cdc14d34d..b9379cde4 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-virtual-network.mdx @@ -446,7 +446,7 @@ storage.ConfigureInfrastructure(infra => TypeScript AppHosts can use curated provisioning helper APIs when an integration exposes them. This example directly customizes Azure.Provisioning objects through `ConfigureInfrastructure`, which is currently C#-only unless - the integration wraps the scenario in a polyglot-friendly helper. + the integration wraps the scenario in a [polyglot](/get-started/glossary/#polyglot)-friendly helper. #### Service-specific requirements diff --git a/src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx b/src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx index ce246363d..1f5e287ce 100644 --- a/src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx +++ b/src/frontend/src/content/docs/integrations/databases/ravendb/ravendb-host.mdx @@ -353,7 +353,7 @@ builder.Build().Run(); ## Connection properties diff --git a/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx b/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx index 83c43a98b..874e94e7b 100644 --- a/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx +++ b/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx @@ -323,7 +323,7 @@ await builder.build().run(); -The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The polyglot TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`). +The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The [polyglot](/get-started/glossary/#polyglot) TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`). ## Health checks diff --git a/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx b/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx index 28ab0d978..b88f3db3c 100644 --- a/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx +++ b/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx @@ -244,7 +244,7 @@ The `DevTunnelOptions` class provides several configuration options: | `Region` | The `DevTunnelRegion` to create the tunnel in; automatic when unset | diff --git a/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-connect.mdx b/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-connect.mdx index bbb448aef..05529a58f 100644 --- a/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-connect.mdx +++ b/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-connect.mdx @@ -239,7 +239,7 @@ For more information, see the [OpenFeature JavaScript SDK](https://openfeature.d ## Use OFREP provider -As an alternative to the native provider, you can connect to flagd using the [OFREP (OpenFeature Remote Evaluation Protocol)](https://openfeature.dev/specification/appendix-c/). OFREP is a standardized HTTP/REST-based protocol for remote feature flag evaluation, making it language-agnostic and well-suited for polyglot environments. +As an alternative to the native provider, you can connect to flagd using the [OFREP (OpenFeature Remote Evaluation Protocol)](https://openfeature.dev/specification/appendix-c/). OFREP is a standardized HTTP/REST-based protocol for remote feature flag evaluation, making it language-agnostic and well-suited for [polyglot](/get-started/glossary/#polyglot) environments. ### Install the OFREP provider diff --git a/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-get-started.mdx b/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-get-started.mdx index 12ffe55c0..d609c70a7 100644 --- a/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/devtools/flagd/flagd-get-started.mdx @@ -89,7 +89,7 @@ Getting there is a two-step process: model the flagd resource in your AppHost, t diff --git a/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx index 2c5ffc326..fc548c912 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx @@ -511,7 +511,7 @@ await builder.build().run(); ## Experimental Go AppHost templates -The `Aspire.Hosting.Go` integration can be used from C# and TypeScript AppHosts. Aspire also includes experimental Go AppHost and Go starter template support in the Aspire CLI. The Go AppHost templates use experimental Go AppHost APIs instead of the `Aspire.Hosting.Go` package. To enable Go AppHost language support for CLI templates, enable the Go polyglot feature flag: +The `Aspire.Hosting.Go` integration can be used from C# and TypeScript AppHosts. Aspire also includes experimental Go AppHost and Go starter template support in the Aspire CLI. The Go AppHost templates use experimental Go AppHost APIs instead of the `Aspire.Hosting.Go` package. To enable Go AppHost language support for CLI templates, enable the Go [polyglot](/get-started/glossary/#polyglot) feature flag: ```bash title="Aspire CLI" aspire config set features:experimentalPolyglot:go true --global diff --git a/src/frontend/src/content/docs/ja/extensibility/multi-language-integration-authoring.mdx b/src/frontend/src/content/docs/ja/extensibility/multi-language-integration-authoring.mdx index ad493fe90..9b4d19f51 100644 --- a/src/frontend/src/content/docs/ja/extensibility/multi-language-integration-authoring.mdx +++ b/src/frontend/src/content/docs/ja/extensibility/multi-language-integration-authoring.mdx @@ -223,6 +223,8 @@ TypeScript 側で値を一度読み取る async 操作として扱いたい場 2. TypeScript 呼び出し元に必要なプロパティだけを個別の `[AspireExport]` 属性で注釈します。 3. 可変状態（環境変数、コマンド ライン引数、URL リスト）には、生のコレクションではなく小さな *editor* クラスを公開します。 +このドキュメントで使う [polyglot](/get-started/glossary/#polyglot) は、C# 以外の言語で書かれたコードを指します。 + ### editor クラスを定義する editor は可変コレクションをラップし、生のコレクションを TypeScript に渡す代わりに、通常は `add`、`set`、`remove` などの特定操作を公開します: diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx index 1693f1127..bb7910c94 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx @@ -27,7 +27,7 @@ You can output detached startup details as a table or JSON, and you can pass add ### Startup readiness and failure diagnostics -`aspire start` waits for the AppHost to report that it has reached a stable running state before detaching. This means that early startup failures — such as TypeScript syntax errors in a polyglot AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background. +`aspire start` waits for the AppHost to report that it has reached a stable running state before detaching. This means that early startup failures — such as TypeScript syntax errors in a [polyglot](/get-started/glossary/#polyglot) AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background. When the AppHost fails to start, `aspire start` displays a curated excerpt of the startup output that filters out noise such as package install logs and highlights the relevant error messages: diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx index 9dbc489cc..a871c9421 100644 --- a/src/frontend/src/content/docs/reference/cli/configuration.mdx +++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx @@ -163,7 +163,7 @@ CLI supports. aspire config set features. true --global ``` - For example, consider the following that enables global support for Go: + For example, consider the following that enables global [polyglot](/get-started/glossary/#polyglot) support for Go: ```bash title="Enable global polyglot Go support" aspire config set features:experimentalPolyglot:go true diff --git a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md index b7dd06837..84afdfa74 100644 --- a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md +++ b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md @@ -8,7 +8,7 @@ title: Config Settings Table | `channel` | `channel` | Default Aspire channel used by channel-aware commands such as `aspire new`, `aspire init`, and `aspire update`. | | `features.aspireSkillsRemoteFetchEnabled` | `features.aspireSkillsRemoteFetchEnabled` | Enable or disable preview remote fetching of Aspire skills bundles from GitHub. | | `features.defaultWatchEnabled` | `features.defaultWatchEnabled` | Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes. | -| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for polyglot Aspire applications. | +| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for [polyglot](/get-started/glossary/#polyglot) Aspire applications. | | `features.experimentalPolyglot:java` | `features.experimentalPolyglot:java` | Enable or disable experimental Java language support for polyglot Aspire applications. | | `features.experimentalPolyglot:python` | `features.experimentalPolyglot:python` | Enable or disable experimental Python language support for polyglot Aspire applications. | | `features.experimentalPolyglot:rust` | `features.experimentalPolyglot:rust` | Enable or disable experimental Rust language support for polyglot Aspire applications. | diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-3.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-3.mdx index 1a07dc941..4a58a7396 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-3.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-3.mdx @@ -694,7 +694,7 @@ Aspire 13.3 closes most of the remaining functional gap between C# AppHosts and ### Unified `withEnvironment` API -Aspire 13.3 introduces a unified `withEnvironment(name, value)` API for polyglot AppHosts (TypeScript, Java, Python, Go, Rust). Previously, environment variable injection required separate methods for each value kind (`withEnvironmentEndpoint`, `withEnvironmentParameter`, `withEnvironmentConnectionString`, and so on). Now, a single call handles all value types: +Aspire 13.3 introduces a unified `withEnvironment(name, value)` API for [polyglot](/get-started/glossary/#polyglot) AppHosts (TypeScript, Java, Python, Go, Rust). Previously, environment variable injection required separate methods for each value kind (`withEnvironmentEndpoint`, `withEnvironmentParameter`, `withEnvironmentConnectionString`, and so on). Now, a single call handles all value types: ```typescript title="apphost.mts" const api = await builder.addProject('api', '../Api/Api.csproj'); diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx index 359e4ea97..a92f1fd9b 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx @@ -138,7 +138,7 @@ Aspire 13.4 validates TypeScript AppHosts before startup, so type-checking and c Docs now include TypeScript examples alongside C# where the API is available, and the release adds TypeScript samples you can start from. -The [Aspire Type System (ATS)](/extensibility/multi-language-integration-authoring/) APIs that power polyglot AppHost authoring are now generally available, so projects can remove `ASPIREATS001` suppressions. The generated TypeScript SDK also adds C# XML-doc JSDoc, fluent async method chaining, `ExternalServiceResource` support in `withEnvironment`, and fixes for generated names and exports. +The [Aspire Type System (ATS)](/extensibility/multi-language-integration-authoring/) APIs that power [polyglot](/get-started/glossary/#polyglot) AppHost authoring are now generally available, so projects can remove `ASPIREATS001` suppressions. The generated TypeScript SDK also adds C# XML-doc JSDoc, fluent async method chaining, `ExternalServiceResource` support in `withEnvironment`, and fixes for generated names and exports. Existing TypeScript AppHosts scaffolded by earlier CLI versions continue to work on 13.4 without changes. If your project uses `apphost.ts` and `./.modules/aspire.js`, see [Legacy `apphost.ts` projects (pre-13.4)](#legacy-apphostts-projects-pre-134) for compatibility details and an opt-in migration to the new `apphost.mts` layout. diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx index 39914b986..10448df9e 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx @@ -20,7 +20,7 @@ import { import LearnMore from '@components/LearnMore.astro'; import OsAwareTabs from '@components/OsAwareTabs.astro'; -Aspire 13.5 is here with focus on **developer experience**, **polyglot feature parity**, and **runtime stability**. This release brings **interactive terminal sessions** via `WithTerminal()`, **IInteractionService available across all polyglot AppHosts** (TypeScript, Python, Go, Java, and Rust), **user-defined arguments in resource commands** for interactive workflows, **TypeScript AppHost startup optimizations** and **stability fixes**, **custom health checks for TypeScript AppHosts**, **container file copying** in polyglot AppHosts, **promoted IInteractionService to stable**, a major **Foundry integration update** to use the CLI-based lifecycle, **distributed trace improvements** including timestamp filtering, **dashboard telemetry enhancements**, new **VS Code extension commands** including opening the Dashboard in a side panel, **Bun debugging support**, **resource command visibility** in the extension tree, **Aspire CLI available via npm**, and many more improvements and bug fixes across AppHost, CLI, Dashboard, and Extensions. +Aspire 13.5 is here with focus on **developer experience**, **[polyglot](/get-started/glossary/#polyglot) feature parity**, and **runtime stability**. This release brings **interactive terminal sessions** via `WithTerminal()`, **IInteractionService available across all polyglot AppHosts** (TypeScript, Python, Go, Java, and Rust), **user-defined arguments in resource commands** for interactive workflows, **TypeScript AppHost startup optimizations** and **stability fixes**, **custom health checks for TypeScript AppHosts**, **container file copying** in polyglot AppHosts, **promoted IInteractionService to stable**, a major **Foundry integration update** to use the CLI-based lifecycle, **distributed trace improvements** including timestamp filtering, **dashboard telemetry enhancements**, new **VS Code extension commands** including opening the Dashboard in a side panel, **Bun debugging support**, **resource command visibility** in the extension tree, **Aspire CLI available via npm**, and many more improvements and bug fixes across AppHost, CLI, Dashboard, and Extensions. We'd love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues). From 60b916b2ed3846752f1d28c034ab7cdfb8891e06 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Wed, 12 Aug 2026 16:18:52 +0100 Subject: [PATCH 2/6] Addressed feedback from @Copilot. --- src/frontend/src/content/docs/diagnostics/aspireexport010.mdx | 2 +- src/frontend/src/content/docs/diagnostics/aspireexport013.mdx | 2 +- src/frontend/src/content/docs/diagnostics/aspireexport015.mdx | 2 +- src/frontend/src/content/docs/reference/cli/configuration.mdx | 2 +- .../docs/reference/cli/includes/config-settings-table.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx index 28a8bddcd..1df6f51b7 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport010.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> Exported builder method '{0}' directly invokes synchronous delegate parameter '{1}'. Defer the callback, expose an async delegate, or set RunSyncOnBackgroundThread = true to avoid [polyglot](/get-started/glossary/#polyglot) deadlocks. +> Exported builder method '{0}' directly invokes synchronous delegate parameter '{1}'. Defer the callback, expose an async delegate, or set RunSyncOnBackgroundThread = true to avoid polyglot deadlocks. This diagnostic warning is reported when an `[AspireExport]` method directly invokes a synchronous delegate parameter inline, inside the method body. In a multi-language (polyglot) app host, callbacks crossing the language boundary are dispatched through an async messaging channel. If a synchronous callback is invoked inline, it can block the calling thread while the message dispatcher is also waiting on the same thread, causing a deadlock. To avoid this, the callback should be deferred, exposed as an async delegate, or run on a background thread. diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx index 4b9ca7c65..ffcf1f8ca 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport013.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> [Polyglot](/get-started/glossary/#polyglot) capability ID '{0}' is defined by multiple exports in this assembly: {1}. Use unique AspireExport IDs for overloaded or colliding members. +> Polyglot capability ID '{0}' is defined by multiple exports in this assembly: {1}. Use unique AspireExport IDs for overloaded or colliding members. This diagnostic warning is reported when two or more Aspire Type System (ATS) exports in the same assembly generate the same runtime capability ID. The capability ID is used to dispatch calls from TypeScript, Python, Java, and other AppHost runtimes back to the hosting integration. Unlike C# method signatures, a capability ID doesn't include the receiver type, parameter list, or overload signature, so exports that are distinct in C# can still collide at runtime. diff --git a/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx b/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx index 468ff2445..cbaa12d27 100644 --- a/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspireexport015.mdx @@ -13,7 +13,7 @@ import { Badge } from '@astrojs/starlight/components'; class:list={'mb-1'} /> -> AspireExport Description is compatibility metadata. Use XML documentation with ATS tags such as `` for generated [polyglot](/get-started/glossary/#polyglot) SDK documentation. +> AspireExport Description is compatibility metadata. Use XML documentation with ATS tags such as `` for generated polyglot SDK documentation. This diagnostic error is reported when a new `[AspireExport]` attribute sets the `Description` property. Starting in Aspire 13.4, the ATS scanner uses XML doc comments as the primary source for generated polyglot SDK documentation. The `Description` property is supported only as a compatibility fallback and should not be used on new exports. diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx index a871c9421..ba16aaa0e 100644 --- a/src/frontend/src/content/docs/reference/cli/configuration.mdx +++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx @@ -163,7 +163,7 @@ CLI supports. aspire config set features. true --global ``` - For example, consider the following that enables global [polyglot](/get-started/glossary/#polyglot) support for Go: + For example, consider the following that enables global [polyglot](/get-started/glossary/#polyglot) support for Go: ```bash title="Enable global polyglot Go support" aspire config set features:experimentalPolyglot:go true diff --git a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md index 84afdfa74..922437408 100644 --- a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md +++ b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md @@ -8,7 +8,7 @@ title: Config Settings Table | `channel` | `channel` | Default Aspire channel used by channel-aware commands such as `aspire new`, `aspire init`, and `aspire update`. | | `features.aspireSkillsRemoteFetchEnabled` | `features.aspireSkillsRemoteFetchEnabled` | Enable or disable preview remote fetching of Aspire skills bundles from GitHub. | | `features.defaultWatchEnabled` | `features.defaultWatchEnabled` | Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes. | -| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for [polyglot](/get-started/glossary/#polyglot) Aspire applications. | +| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for [polyglot](/get-started/glossary/#polyglot) Aspire applications. | | `features.experimentalPolyglot:java` | `features.experimentalPolyglot:java` | Enable or disable experimental Java language support for polyglot Aspire applications. | | `features.experimentalPolyglot:python` | `features.experimentalPolyglot:python` | Enable or disable experimental Python language support for polyglot Aspire applications. | | `features.experimentalPolyglot:rust` | `features.experimentalPolyglot:rust` | Enable or disable experimental Rust language support for polyglot Aspire applications. | From 27c6407c5858be1e4881eee08781ed439144baca Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Thu, 13 Aug 2026 12:01:53 +0100 Subject: [PATCH 3/6] Added TypeScript examples to all C# examples in the Glossary. --- .../src/content/docs/get-started/glossary.mdx | 97 +++++++++++++++++-- 1 file changed, 88 insertions(+), 9 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/glossary.mdx b/src/frontend/src/content/docs/get-started/glossary.mdx index 8cbe7f47b..e37a383de 100644 --- a/src/frontend/src/content/docs/get-started/glossary.mdx +++ b/src/frontend/src/content/docs/get-started/glossary.mdx @@ -4,6 +4,8 @@ description: Key terms and concepts used throughout Aspire documentation — App --- import { Aside } from '@astrojs/starlight/components'; +import PivotSelector from '@components/PivotSelector.astro'; +import Pivot from '@components/Pivot.astro'; This glossary defines the key terms and concepts you'll encounter when working with Aspire. Bookmark this page as a quick reference. @@ -13,16 +15,27 @@ These are the foundational concepts you need to understand when working with Asp ### AppHost -The **AppHost** is the orchestration project where you define your entire application's architecture in C# code. It's a special Aspire project that: +The **AppHost** is the orchestration project where you define your entire application's architecture. It's a special Aspire project that: -- Declares what services, databases, and containers make up your application -- Defines how resources depend on each other -- Configures how resources communicate -- Orchestrates startup order during local development -- Generates deployment artifacts for production +- Declares what services, databases, and containers make up your application. +- Defines how resources depend on each other. +- Configures how resources communicate. +- Orchestrates startup order during local development. +- Generates deployment artifacts for production. Think of it as the "control tower" for your distributed application. + + + ```csharp title="AppHost.cs" // This IS the AppHost - Program.cs in your AppHost project var builder = DistributedApplication.CreateBuilder(args); @@ -33,6 +46,21 @@ var api = builder.AddProject("api") builder.Build().Run(); ``` + + +```typescript title="apphost.mts" +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +// This IS the AppHost in a TypeScript project +const builder = await createBuilder(); + +const db = await builder.addPostgres("db"); +await builder.addProject("api", "../Api/Api.csproj") + .withReference(db); + +await builder.build().run(); +``` + ### Resource @@ -92,11 +120,20 @@ These are the key APIs and patterns you'll use when building Aspire applications 2. Sets up service discovery so your code can find the other resource 3. Creates a dependency relationship for startup ordering + ```csharp title="AppHost.cs" var db = builder.AddPostgres("db"); var api = builder.AddProject("api") .WithReference(db); // API now has DATABASE connection info injected ``` + + +```typescript title="apphost.mts" +const db = await builder.addPostgres("db"); +await builder.addProject("api", "../Api/Api.csproj") + .withReference(db); // API now has DATABASE connection info injected +``` + The API project will receive environment variables like: - `ConnectionStrings__db` - The database connection string @@ -104,38 +141,66 @@ The API project will receive environment variables like: ### WaitFor -`WaitFor()` tells Aspire to delay starting a resource until its dependency is ready: +`WaitFor()`/`waitFor()` tells Aspire to delay starting a resource until its dependency is ready: + ```csharp title="AppHost.cs" var db = builder.AddPostgres("db"); var api = builder.AddProject("api") .WithReference(db) .WaitFor(db); // Don't start API until database is healthy ``` + + +```typescript title="apphost.mts" +const db = await builder.addPostgres("db"); +await builder.addProject("api", "../Api/Api.csproj") + .withReference(db) + .waitFor(db); // Don't start API until database is healthy +``` + ### WaitForCompletion `WaitForCompletion()` waits for a resource to finish and exit (not just start). Useful for setup scripts: + ```csharp title="AppHost.cs" var migrate = builder.AddProject("migrate"); var api = builder.AddProject("api") .WaitForCompletion(migrate); // Wait for migrations to complete ``` + + +```typescript title="apphost.mts" +const migrate = await builder.addProject("migrate", "../DbMigration/DbMigration.csproj"); +await builder.addProject("api", "../Api/Api.csproj") + .waitForCompletion(migrate); // Wait for migrations to complete +``` + ### WaitForStart `WaitForStart()` waits only for a resource to reach the running state, without waiting for health checks to pass: + ```csharp title="AppHost.cs" var db = builder.AddPostgres("db"); var api = builder.AddProject("api") .WaitForStart(db); // Start as soon as db is running, don't wait for healthy ``` + + +```typescript title="apphost.mts" +const db = await builder.addPostgres("db"); +await builder.addProject("api", "../Api/Api.csproj") + .waitForStart(db); // Start as soon as db is running, don't wait for healthy +``` + ## Connection properties diff --git a/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx b/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx index 874e94e7b..5811d0e58 100644 --- a/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx +++ b/src/frontend/src/content/docs/integrations/databases/surrealdb/surrealdb-host.mdx @@ -323,7 +323,7 @@ await builder.build().run(); -The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The [polyglot](/get-started/glossary/#polyglot) TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`). +The `WithLogLevel` method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The non-C# TypeScript AppHost accepts the log level as a string (for example, `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"`, or `"None"`). ## Health checks diff --git a/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx b/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx index b88f3db3c..64e2804f5 100644 --- a/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx +++ b/src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx @@ -244,7 +244,7 @@ The `DevTunnelOptions` class provides several configuration options: | `Region` | The `DevTunnelRegion` to create the tunnel in; automatic when unset | diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx index bb7910c94..c61625f03 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx @@ -27,7 +27,7 @@ You can output detached startup details as a table or JSON, and you can pass add ### Startup readiness and failure diagnostics -`aspire start` waits for the AppHost to report that it has reached a stable running state before detaching. This means that early startup failures — such as TypeScript syntax errors in a [polyglot](/get-started/glossary/#polyglot) AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background. +`aspire start` waits for the AppHost to report that it has reached a stable running state before detaching. This means that early startup failures — such as TypeScript syntax errors in a non-C# AppHost or C# compile errors in a .NET AppHost — are surfaced in the parent terminal instead of being silently lost in the background. When the AppHost fails to start, `aspire start` displays a curated excerpt of the startup output that filters out noise such as package install logs and highlights the relevant error messages: diff --git a/src/frontend/src/content/docs/reference/cli/configuration.mdx b/src/frontend/src/content/docs/reference/cli/configuration.mdx index ba16aaa0e..b6f9e6856 100644 --- a/src/frontend/src/content/docs/reference/cli/configuration.mdx +++ b/src/frontend/src/content/docs/reference/cli/configuration.mdx @@ -163,9 +163,9 @@ CLI supports. aspire config set features. true --global ``` - For example, consider the following that enables global [polyglot](/get-started/glossary/#polyglot) support for Go: + For example, consider the following that enables global support for Go: - ```bash title="Enable global polyglot Go support" + ```bash title="Enable global Go support" aspire config set features:experimentalPolyglot:go true ``` diff --git a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md index 522069df0..a194839c6 100644 --- a/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md +++ b/src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md @@ -6,11 +6,12 @@ title: Config Settings Table | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `appHost.path` | `appHost.path` | Project-scoped path to the default AppHost entry point. This setting must be configured in the local `aspire.config.json` file. | | `channel` | `channel` | Default Aspire channel used by channel-aware commands such as `aspire new`, `aspire init`, and `aspire update`. | +| `features.aspireSkillsRemoteFetchEnabled` | `features.aspireSkillsRemoteFetchEnabled` | Enable or disable preview remote fetching of Aspire skills bundles from GitHub. | | `features.defaultWatchEnabled` | `features.defaultWatchEnabled` | Enable or disable watch mode by default when running Aspire applications for automatic restarts on file changes. | -| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for [polyglot](/get-started/glossary/#polyglot) Aspire applications. | -| `features.experimentalPolyglot:java` | `features.experimentalPolyglot:java` | Enable or disable experimental Java language support for polyglot Aspire applications. | -| `features.experimentalPolyglot:python` | `features.experimentalPolyglot:python` | Enable or disable experimental Python language support for polyglot Aspire applications. | -| `features.experimentalPolyglot:rust` | `features.experimentalPolyglot:rust` | Enable or disable experimental Rust language support for polyglot Aspire applications. | +| `features.experimentalPolyglot:go` | `features.experimentalPolyglot:go` | Enable or disable experimental Go language support for non-C# Aspire applications. | +| `features.experimentalPolyglot:java` | `features.experimentalPolyglot:java` | Enable or disable experimental Java language support for non-C# Aspire applications. | +| `features.experimentalPolyglot:python` | `features.experimentalPolyglot:python` | Enable or disable experimental Python language support for non-C# Aspire applications. | +| `features.experimentalPolyglot:rust` | `features.experimentalPolyglot:rust` | Enable or disable experimental Rust language support for non-C# Aspire applications. | | `features.polyglotIntegrationFilterEnabled` | `features.polyglotIntegrationFilterEnabled` | Enable or disable filtering `aspire add`, `aspire integration list`, and `aspire integration search` results to only integrations compatible with a non-C# AppHost. Disabled by default because remote NuGet feeds don't reliably answer the `tags:polyglot` query used to build the compatibility allow-list. | | `features.showAllTemplates` | `features.showAllTemplates` | Show all available templates, including experimental ones, in `aspire new` and `aspire init`. | | `features.showDeprecatedPackages` | `features.showDeprecatedPackages` | Show or hide deprecated packages in `aspire add` search results. | diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx index a92f1fd9b..360c7324d 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-4.mdx @@ -138,12 +138,12 @@ Aspire 13.4 validates TypeScript AppHosts before startup, so type-checking and c Docs now include TypeScript examples alongside C# where the API is available, and the release adds TypeScript samples you can start from. -The [Aspire Type System (ATS)](/extensibility/multi-language-integration-authoring/) APIs that power [polyglot](/get-started/glossary/#polyglot) AppHost authoring are now generally available, so projects can remove `ASPIREATS001` suppressions. The generated TypeScript SDK also adds C# XML-doc JSDoc, fluent async method chaining, `ExternalServiceResource` support in `withEnvironment`, and fixes for generated names and exports. +The [Aspire Type System (ATS)](/extensibility/multi-language-integration-authoring/) APIs that power non-C# AppHost authoring are now generally available, so projects can remove `ASPIREATS001` suppressions. The generated TypeScript SDK also adds C# XML-doc JSDoc, fluent async method chaining, `ExternalServiceResource` support in `withEnvironment`, and fixes for generated names and exports. Existing TypeScript AppHosts scaffolded by earlier CLI versions continue to work on 13.4 without changes. If your project uses `apphost.ts` and `./.modules/aspire.js`, see [Legacy `apphost.ts` projects (pre-13.4)](#legacy-apphostts-projects-pre-134) for compatibility details and an opt-in migration to the new `apphost.mts` layout. - For preview polyglot AppHosts behind feature flags, see [`aspire config set`](/reference/cli/commands/aspire-config-set/). + For preview non-C# AppHosts behind feature flags, see [`aspire config set`](/reference/cli/commands/aspire-config-set/). For setup details, see [TypeScript AppHosts](/app-host/typescript-apphost/). To explore working examples, browse the [Aspire samples](/reference/samples/). @@ -770,7 +770,7 @@ After migrating, `aspire run` behaves exactly the same as before — the CLI now -Aspire 13.4 includes several breaking changes. Most are small renames or configuration moves, but a few affect deployment and the polyglot AppHost SDK layout. Review the subsections that apply to your app before upgrading. +Aspire 13.4 includes several breaking changes. Most are small renames or configuration moves, but a few affect deployment and the non-C# AppHost SDK layout. Review the subsections that apply to your app before upgrading. #### `aspire exec` command removed @@ -780,7 +780,7 @@ Remove scripts or workflows that call `aspire exec`. For resource-specific actio #### Generated TypeScript modules consolidated under `.aspire/modules/` -Generated polyglot SDK modules now live under a single `.aspire/modules/` directory instead of being split across `.modules/` and `.aspire/`. Generated language references — TypeScript imports, Go replace directives, Python editable paths, Java source lists, and Rust module paths — are updated automatically to point at the new location. +Generated non-C# SDK modules now live under a single `.aspire/modules/` directory instead of being split across `.modules/` and `.aspire/`. Generated language references — TypeScript imports, Go replace directives, Python editable paths, Java source lists, and Rust module paths — are updated automatically to point at the new location. Re-run `aspire run` (or your code-generation step) to regenerate references, and update any custom tooling or `.gitignore` entries that referenced the old `.modules/` path. @@ -874,7 +874,7 @@ For full guidance and the container path mapping, see [PostgreSQL 18 data direct 1. **Update the CLI** — run `aspire update --self`. This step is **required** for TypeScript AppHosts; running `aspire update` against a 13.3.x TypeScript project before updating the CLI fails with `No code generator found for language: TypeScript` and leaves the project in a partially-upgraded, unrunnable state (see [microsoft/aspire#17077](https://github.com/microsoft/aspire/issues/17077)). -2. **Update your projects** — run `aspire update` from the root of your repository. For polyglot AppHosts, this regenerates SDK modules under `.aspire/modules/`. +2. **Update your projects** — run `aspire update` from the root of your repository. For non-C# AppHosts, this regenerates SDK modules under `.aspire/modules/`. 3. **Run `aspire doctor`** to check your environment setup and spot conflicting CLI installs. 4. **Audit scripts and CI** for removed/changed commands — `aspire exec` and non-interactive `aspire update` calls. 5. **Update Kubernetes deployment code** — move Helm chart properties into `WithHelm(...)`, rename `ingress.WithRoute(...)` to `ingress.WithPath(...)`, and mark routed endpoints external with `WithExternalHttpEndpoints()`. diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx index 991d760b5..a7fcfb85f 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-5.mdx @@ -1,6 +1,6 @@ --- title: "What's new in Aspire 13.5" -description: "Explore Aspire 13.5, a developer-experience release: interactive terminal sessions, the Interaction Service across C# and TypeScript AppHosts with file uploads and progress dialogs, user-defined resource command arguments, generally available TypeScript AppHosts with health checks and container files, HTTPS certificates for projects, Kubernetes and AKS persistent volumes, a refreshed dashboard, and a rebranded VS Code extension." +description: "Explore Aspire 13.5: Interactive terminal sessions, polyglot IInteractionService, TypeScript AppHost stability, terminal commands with user inputs, custom health checks, distributed tracing improvements, and dashboard enhancements." sidebar: label: Aspire 13.5 order: 0 @@ -12,29 +12,40 @@ tableOfContents: import { Steps, Aside, + FileTree, Icon, Tabs, TabItem, } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; import OsAwareTabs from '@components/OsAwareTabs.astro'; -import { Image } from 'astro:assets'; -Aspire 13.5 is here with focus on **developer experience**, **[polyglot](/get-started/glossary/#polyglot) feature parity**, and **runtime stability**. This release brings **interactive terminal sessions** via `WithTerminal()`, **IInteractionService available across all non-C# AppHosts** (TypeScript, Python, Go, Java, and Rust), **user-defined arguments in resource commands** for interactive workflows, **TypeScript AppHost startup optimizations** and **stability fixes**, **custom health checks for TypeScript AppHosts**, **container file copying** in non-C# AppHosts, **promoted IInteractionService to stable**, a major **Foundry integration update** to use the CLI-based lifecycle, **distributed trace improvements** including timestamp filtering, **dashboard telemetry enhancements**, new **VS Code extension commands** including opening the Dashboard in a side panel, **Bun debugging support**, **resource command visibility** in the extension tree, **Aspire CLI available via npm**, and many more improvements and bug fixes across AppHost, CLI, Dashboard, and Extensions. +Aspire 13.5 is here with focus on **developer experience**, **[polyglot](/get-started/glossary/#polyglot) feature parity**, and **runtime stability**. This release brings **interactive terminal sessions** via `WithTerminal()`, **IInteractionService available across all polyglot AppHosts** (TypeScript, Python, Go, Java, and Rust), **user-defined arguments in resource commands** for interactive workflows, **TypeScript AppHost startup optimizations** and **stability fixes**, **custom health checks for TypeScript AppHosts**, **container file copying** in polyglot AppHosts, **promoted IInteractionService to stable**, a major **Foundry integration update** to use the CLI-based lifecycle, **distributed trace improvements** including timestamp filtering, **dashboard telemetry enhancements**, new **VS Code extension commands** including opening the Dashboard in a side panel, **Bun debugging support**, **resource command visibility** in the extension tree, **Aspire CLI available via npm**, and many more improvements and bug fixes across AppHost, CLI, Dashboard, and Extensions. We'd love to hear what you think. Drop by [ Discord](https://aka.ms/aspire-discord) to chat with the team and the community, or file feedback and issues on [ GitHub](https://github.com/microsoft/aspire/issues). This release introduces: -- **Interactive terminal sessions** with the experimental `WithTerminal()` API, so you can attach to REPLs, shells, and other terminal programs running as Aspire resources from the dashboard — with an opt-in `aspire terminal` CLI command. -- **The Interaction Service across C# and TypeScript AppHosts** — prompts, message boxes, notifications, and dynamic inputs, now with **file uploads** and **progress dialogs**. The core `PromptInput`/`PromptInputs` surface is stable and no longer requires suppressing `ASPIREINTERACTION001`. -- **User-defined resource command arguments**, so the dashboard can prompt for input before invoking a command — the CLI exposes them as `--` options — with full C# and TypeScript parity. -- **HTTPS certificates for project resources** through a new experimental configuration API. -- **Generally available TypeScript AppHosts**, adding **custom health checks** and **container file copying** at parity with C#, plus faster startup and a batch of reliability fixes. -- **The Aspire CLI on npm and Nix**, with the CLI bundle enabled by default in new C# projects — acquired on the fly via `dnx`. -- **A refreshed, officially branded dashboard** with timestamp filtering, numeric operators, and console-log text search. -- **A rebranded Visual Studio Code extension** with a dashboard side panel, Bun and MAUI debugging, and resource commands in the tree view. -- **Cross-scope Azure resource references** with the `AsExisting*` family, and **persistent volumes for Kubernetes and AKS**. +- **Interactive terminal sessions** with `WithTerminal()` on AppHost resources enable live REPL and shell interaction through the Dashboard and CLI. +- **Polyglot IInteractionService parity** brings prompts, message boxes, notifications, and dynamic inputs to TypeScript, Python, Go, Java, and Rust AppHosts alongside C#. +- **User-defined resource command arguments** let Dashboard and CLI prompt for input before invoking commands like custom deploy or setup workflows. +- **TypeScript AppHost stability improvements** fix deadlocks, optimize startup by racing connection attempts against process exit, and validate compilation before execution. +- **Custom health checks in TypeScript AppHosts** enable resource-specific health monitoring in polyglot environments. +- **Container file copying in TypeScript AppHosts** brings parity with C# for copying host files into containers with ownership and permission controls. +- **IInteractionService promoted to stable** removes the ASPIREINTERACTION001 diagnostic requirement from production code. +- **CLI available via npm** (@microsoft/aspire-cli) provides an alternative installation path alongside the default distribution. +- **Embedded Aspire skills bundle fallback** ensures the CLI can bootstrap even when GitHub release asset acquisition is unavailable. +- **Faster TypeScript AppHost startup** skips fixed delays and races the connection retry loop, reducing time-to-ready. +- **Friendly error messages for health check failures** replace raw exception stacks with actionable diagnostics in the Dashboard. +- **Distributed trace timestamp filtering** enables precise telemetry searches by date and time. +- **VS Code Dashboard in side panel** lets you monitor your app without leaving VS Code. +- **Bun debugging support** in VS Code extension via WebKit Inspector Protocol. +- **Resource commands in VS Code tree view** display all available actions (Start, Stop, custom commands) under each resource. +- **Improved parameter display** in VS Code shows secret masks, missing value warnings, and consistent formatting across panels. +- **VS Code extension renamed to "Aspire"** and rebranded for clarity on the Marketplace. +- **AppHost discovery efficiency** in VS Code respects exclusion settings and debounces file changes to reduce background scanning. +- **Foundry Local integration CLI update** now uses the foundry CLI for lifecycle management, requiring foundry 1.1.0+. +- **Proxyless endpoint port allocation** assigns dynamic public host ports before resources are created, so endpoint property references resolve consistently. - …and much more. ## 🆙 Upgrade to Aspire 13.5 @@ -42,10 +53,6 @@ This release introduces:
- -