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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/frontend/config/aspire-versions.mjs
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
export const currentAspireMajorMinorVersion = '13.6';
export const currentAspireVersion = '13.6.0';
export const currentAspireMajorMinorVersion = '17.0';
export const currentAspireVersion = '17.0.0';
// Release date (YYYY-MM-DD) of currentAspireVersion; update together with the version.
export const currentAspireReleaseDate = '2026-09-29';
export const currentAspirePreviewVersion = '13.6.0-preview.1.26479.8';
export const currentAspireReleaseDate = '2026-11-17';
export const currentAspirePreviewVersion = '17.0.0-preview.1.26480.6';

export const aspireVersionPlaceholders = Object.freeze({
'%ASPIRE_VERSION_MAJOR_MINOR%': currentAspireMajorMinorVersion,
Expand Down
7 changes: 3 additions & 4 deletions src/frontend/src/components/live-status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,9 @@ function syncDom(): void {
btn.dataset.pipOpen = pipOpen ? 'true' : 'false';
btn.dataset.liveDismissed = notificationDismissed ? 'true' : 'false';
btn.dataset.source = sourceAttr;
btn.setAttribute(
'aria-label',
current.isLive ? 'Aspire is live — watch now' : 'Watch Aspire live streams'
);
const label = current.isLive ? 'Aspire is live — watch now' : 'Watch Aspire live streams';
btn.setAttribute('aria-label', label);
btn.setAttribute('title', label);
});
}

Expand Down
3 changes: 3 additions & 0 deletions src/frontend/src/components/starlight/Header.astro
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ const tryLabel = t('header.try' as any);
data-tour-target="install-cli"
data-tour-step="install-cli"
aria-label="Open install Aspire CLI dialog"
title="Install Aspire CLI"
>
<span class="sr-only">Install Aspire CLI</span>
<Icon name="download" />
Expand All @@ -55,6 +56,7 @@ const tryLabel = t('header.try' as any);
data-source="none"
data-tour-target="live-status"
aria-label="Watch Aspire live streams"
title="Watch Aspire live streams"
aria-current={Astro.url.pathname === '/community/videos/' ? 'page' : undefined}
>
<span class="sr-only">Watch Aspire live streams</span>
Expand All @@ -71,6 +73,7 @@ const tryLabel = t('header.try' as any);
data-tour-target="cookie-preferences"
data-tour-step="cookie-preferences"
aria-label="Open cookie preferences dialog"
title="Cookie preferences"
>
<span class="sr-only">Cookie Preferences</span>
<CookiesSvg />
Expand Down
24 changes: 22 additions & 2 deletions src/frontend/src/content/docs/app-host/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,8 @@ In Go AppHosts, profiles live in `aspire.config.json`:
| Option | Default value | Description |
| ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ASPIRE_ALLOW_UNSECURED_TRANSPORT` | `false` | Allows communication with the AppHost without https. `ASPNETCORE_URLS` (dashboard address) and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` (AppHost resource service address) must be secured with HTTPS unless true. |
| `ASPIRE_CONTAINER_RUNTIME` | Auto-detected | Selects the runtime for container resources. Supported values are `docker`, `podman`, and `wslc`. WSLc is supported only on Windows and only for local development. Publish and deploy are not yet supported. See [container runtime prerequisites](/get-started/prerequisites/#install-an-oci-compliant-container-runtime). |
| `ASPIRE_CONTAINER_RUNTIME` | Auto-detected | Selects the runtime for container resources. Supported values are `docker`, `podman`, and `wslc`. WSLc is supported only on Windows and has limited publishing support; Docker Compose deployment isn't supported. See [container runtime prerequisites](/get-started/prerequisites/#install-an-oci-compliant-container-runtime). |
| `ASPIRE_CONTAINER_TUNNEL_BASE_IMAGE` | `null` | Overrides the base image used to build the [container tunnel](/fundamentals/container-networking/) proxy image, such as a mirrored copy for networks that can't reach the default image. `DcpPublisher:ContainerTunnelBaseImage` and the `--dcp-container-tunnel-base-image` AppHost argument take precedence. The Aspire CLI sets this variable from the `containerTunnel.baseImage` setting when it isn't already set. |
| `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` | `true` | When `true` (the default), Aspire uses the ASP.NET Core developer certificate to secure the internal DCP server instead of an ephemeral certificate generated by DCP. On Windows, Aspire passes the certificate thumbprint to DCP. On macOS and Linux, Aspire passes the certificate and private key file paths (plus the thumbprint) so DCP can verify the loaded certificate. Set to `false` to opt out and use DCP's default ephemeral certificate. If no trusted developer certificate is found, Aspire automatically falls back to the ephemeral certificate. For more information, see [Certificate configuration](/app-host/certificate-configuration/). |
| `ASPIRE_ENVIRONMENT` | `null` | Configures the AppHost environment when no higher-priority environment source is set. If no environment is configured, the AppHost uses `Production`. |
| `ASPIRE_VERSION_CHECK_DISABLED` | `false` | When set to `true`, Aspire doesn't check for newer versions on startup. |
Expand Down Expand Up @@ -187,7 +188,26 @@ By default, the dashboard is automatically started by the AppHost. The dashboard
| `ASPIRE_DASHBOARD_API_ENABLED` | `true` | Enables the dashboard [telemetry API](/dashboard/configuration/#api) (`/api/telemetry/*`) endpoints. The AppHost always sets this to `true`. |
| `ASPIRE_DASHBOARD_FORWARDEDHEADERS_ENABLED` | `false` | Enables the Forwarded headers middleware that replaces the scheme and host values on the Request context with the values coming from the `X-Forwarded-Proto` and `X-Forwarded-Host` headers. |
| `ASPIRE_DASHBOARD_PERSISTENCE_MODE` | `Run` | Configures [dashboard data persistence](/dashboard/data-persistence/). Valid values are `None`, `Run`, and `Resume`. The AppHost automatically sets this value to `Run`. |
| `ASPIRE_DASHBOARD_DATA_DIRECTORY` | `<ASPIRE_HOME>/dashboard` | Configures the root directory for persistent dashboard data. The directory must be writable by the account running the dashboard and have restrictive file-system permissions because it can contain sensitive data. |
| `ASPIRE_DASHBOARD_DATA_DIRECTORY` | `<ASPIRE_HOME>/dashboard` | Configures the root directory for persistent dashboard data. The directory must be writable by the account running the dashboard and have restrictive file-system permissions because it can contain sensitive data. A relative path is resolved against the AppHost directory. |

## DCP API timeouts

The AppHost communicates with the Developer Control Plane (DCP) through a local Kubernetes-style API. If DCP responds slowly, such as on resource-constrained CI agents or heavily loaded machines, increase these timeouts. Set them as environment variables in your launch profile, or in any other AppHost configuration source. Values use the `hh:mm:ss` format.

```json title="JSON — Launch profile environment variables"
{
"environmentVariables": {
"DcpPublisher__KubernetesApiTimeout": "00:01:00",
"DcpPublisher__KubernetesCreateRecoveryTimeout": "00:03:00"
}
}
```

| Option | Default value | Description |
| --------------------------------------------------------- | ------------- | ----------- |
| `DcpPublisher:KubernetesApiTimeout` | `00:00:40` | Time budget for a single API operation, such as connecting to DCP or sending a request. Doesn't limit the lifetime of established watch and log streams. Valid values range from one second to ten minutes. |
| `DcpPublisher:KubernetesInitializationAdditionalTimeout` | `00:00:20` | Extra time added to `KubernetesApiTimeout` until the first API operation succeeds, to cover one-time client setup. Can be zero. The combined value can't exceed ten minutes. |
| `DcpPublisher:KubernetesCreateRecoveryTimeout` | `00:02:00` | Total time budget for creating a resource in DCP, including client setup, retries, and recovery. If a create request times out or returns HTTP 504, the AppHost checks whether DCP already created the resource before retrying, instead of failing the resource immediately. Valid values range from one second to ten minutes. |

## Internal

Expand Down
6 changes: 1 addition & 5 deletions src/frontend/src/content/docs/app-host/console-apps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -741,11 +741,7 @@ With `WithExplicitStart`, the resource appears in the Aspire dashboard but doesn
user input to the process's stdin.
</Aside>

Aspire builds that include the experimental `WithTerminal` API support interactive terminal user interfaces (TUIs) and shell-based experiences that need a live, bidirectional session, separately from the dashboard's console log viewer.

:::caution[Experimental API]
`WithTerminal` is reported under diagnostic ID `ASPIRETERMINAL001`. Using it in C# requires suppressing that diagnostic, and its API surface and behavior may change. This API might not be present in your installed release; use compatible hosting packages and a CLI build that includes it.
:::
Use the `WithTerminal` API for interactive terminal user interfaces (TUIs) and shell-based experiences that need a live, bidirectional session, separately from the dashboard's console log viewer. For more information, see [Attach a terminal to a resource](/app-host/with-terminal/).

## Viewing console output

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,25 @@ The Aspire CLI generates the Go SDK from the integrations in your `aspire.config

Every integration adds its methods to the `aspire` package, and method names are PascalCase. The TypeScript method `addRedis` is `AddRedis` in Go.

Numeric parameters and fields use the Go type that matches the .NET type, such as `int` for a port and `int64` for a file size. Methods and properties that are marked obsolete in .NET aren't generated.

Methods that add a resource, such as `AddRedis` and `AddGoApp`, return a _handle_. A handle is a Go interface that stands for the resource in the app model, for example `aspire.RedisResource`. Methods that configure a resource return the same handle type, so calls chain. Errors are reported when you call `Build`, as described in [Errors](#errors).

### Pass derived resource handles

Go interfaces don't support covariant return types, so the handle for a derived resource type doesn't satisfy the handle interface of its base type. When other resource types derive from a type, the SDK also generates an `Any<Type>` interface that accepts a handle of that type or of any type derived from it. Parameters that take such a resource use this interface. For example, `WithNodePool` takes an `aspire.AnyKubernetesNodePoolResource`, so it accepts the `aspire.AksNodePoolResource` handle that `AddNodePool` returns:

```go title="apphost.go"
aks := builder.AddAzureKubernetesEnvironment("aks")
pool := aks.AddNodePool("workload", func(config *aspire.AksNodePoolConfig) {
config.MaxCount = 5
})

builder.AddContainer("api", "nginx").WithNodePool(pool)
```

The compiler rejects a handle of an unrelated resource type. Methods still return the receiver's own handle type, so chained calls keep their type.

## Optional parameters

Optional parameters go in a trailing variadic options argument. Leave it out to use the defaults, or pass typed option values for the settings you want to change. You don't need an options struct or pointer helpers:
Expand Down Expand Up @@ -41,7 +58,7 @@ The [`WithHttpEndpoint` API reference](/reference/api/go/aspire.hosting/withhttp

The SDK reports errors in two ways.

Methods that add or configure a resource return a handle instead of an error, so you can add many resources without checking each call. The SDK aggregates the errors and reports them when you call `Build`:
Methods that add or configure a resource return a handle instead of an error, so you can add many resources without checking each call. A failed resource doesn't stop you from adding other resources. The SDK collects the error from every failed handle and `Build` returns them together, joined with `errors.Join`:

```go title="apphost.go"
cache := builder.AddRedis("cache")
Expand All @@ -53,6 +70,8 @@ if err != nil {
}
```

Each failure is reported once, even when it passes through a chain of calls. To check for errors before you call `Build`, call `builder.Err()`, which returns the same combined error. To check a single resource, call the `Err()` method on its handle, which returns the first error recorded for that resource.

Methods that return a value return a `(T, error)` pair, and `Build` and `Run` return an `error`:

```go title="apphost.go"
Expand All @@ -64,7 +83,9 @@ if err != nil {
log.Println("AppHost directory:", dir)
```

`aspire.FormatError` turns an error into a message that is ready to log. When the AppHost server returns an error for a call, the error is an `*aspire.CapabilityError`, and `FormatError` adds its error code and the capability that failed. Use `errors.As` and the `Code`, `Message`, and `Capability` methods to read these values yourself. For any other error, `FormatError` returns `err.Error()`.
`aspire.FormatError` turns an error into a message that is ready to log. When the AppHost server returns an error for a call, the error is an `*aspire.CapabilityError`, and `FormatError` adds its error code and the capability that failed. Use `errors.As` and the `Code`, `Message`, and `Capability` methods to read these values yourself. When the error combines several errors, such as the error that `Build` returns, `FormatError` formats each one on its own line. For any other error, `FormatError` returns `err.Error()`.

If a callback that you pass to an SDK method panics, the AppHost process keeps running. The SDK recovers the panic and fails only the call that invoked the callback.

## Cancellation

Expand Down
29 changes: 17 additions & 12 deletions src/frontend/src/content/docs/app-host/with-terminal.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,6 @@ If you have a terminal user interface (TUI) application or a shell-based experie

For an introduction to the resource Terminal view, terminal dock, and detached windows, start with [Dashboard terminals](/dashboard/terminals/).

:::caution[Aspire 17.0 preview]
This page describes resource-terminal behavior and defaults for Aspire 17.0 preview. Use matching AppHost, dashboard, and CLI builds.
:::

## Prerequisites

Start with a [TypeScript or C# AppHost](/get-started/app-host/) and an installed interactive program. Resource terminals support executable and project processes on Windows, macOS, and Linux, as well as container processes through the container runtime. Containers require a [supported container runtime](/get-started/prerequisites/).
Expand Down Expand Up @@ -58,7 +54,7 @@ builder.Build().Run();
</TabItem>
</Tabs>

Start the app with `aspire run`, select `repl` on the dashboard's **Console logs** page, and switch to **Terminal** if needed. At the Python prompt, enter `print("Hello from Aspire")`. You can also run `aspire terminal attach repl` after [enabling the CLI commands](#work-with-terminals-from-the-cli).
Start the app with `aspire run`, select `repl` on the dashboard's **Console logs** page, and switch to **Terminal** if needed. At the Python prompt, enter `print("Hello from Aspire")`. You can also use [`aspire terminal attach repl`](#work-with-terminals-from-the-cli).

## When to use WithTerminal

Expand Down Expand Up @@ -105,11 +101,20 @@ The terminal session is described by a set of options with sensible defaults:
| `Columns` | `132` | The initial number of columns for the terminal grid. |
| `Rows` | `50` | The initial number of rows for the terminal grid. |

On the resource **Terminal** page, the dashboard automatically fits the terminal grid to the view when you open the terminal unless you set `Columns` or `Rows`. Setting either dimension, even to its default value, turns off automatic fitting on that page until you request a resize. A configuration callback that doesn't set either dimension keeps automatic fitting. The terminal dock still automatically fits its resource-terminal pane when it opens, even if you set dimensions.

<Aside type="tip">
`Columns` and `Rows` must each be `1` or greater. Configuring either with zero
or a negative value in the `WithTerminal(...)` callback throws an
`ArgumentOutOfRangeException` immediately instead of failing later during
terminal-host startup.
or a negative value in the `WithTerminal(...)` callback fails immediately
instead of failing later during terminal-host startup. In C#, the setter
throws an `ArgumentOutOfRangeException`.
</Aside>

<Aside type="note" title="Terminal host resources">
Aspire runs a terminal host resource for each replica to bridge the terminal
session. These resources are hidden by default. To inspect their state and
logs, select **Show hidden resources** in the dashboard; you don't need to
change or restart your AppHost.
</Aside>

<Aside type="note">
Expand All @@ -123,20 +128,20 @@ The terminal session is described by a set of options with sensible defaults:
<Tabs syncKey='aspire-lang'>
<TabItem id='typescript' label='TypeScript'>

In TypeScript, pass a `configure` callback to set the initial number of columns and rows. Calling `withTerminal()` without a callback, or with a callback that doesn't assign a dimension, keeps the default dimensions and automatic dashboard fitting. Assigning `columns` or `rows`, even to its default value, disables automatic fitting.
In TypeScript, pass a `configure` callback to override any of these options:

```typescript title="apphost.mts"
```typescript title="apphost.mts" twoslash
import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

await builder
.addExecutable('repl', 'python3', '.', ['-i', '-q'])
.withTerminal({
configure: async options => {
configure: async (options) => {
options.columns = 200;
options.rows = 50;
}
},
});

await builder.build().run();
Expand Down
2 changes: 1 addition & 1 deletion src/frontend/src/content/docs/dashboard/terminals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import ApiReference from '@components/ApiReference.astro';

The Aspire dashboard can display interactive terminal applications as well as logs. A terminal lets you type into a running process, respond to its prompts, and use a terminal user interface (TUI) without leaving the dashboard.

:::caution[Experimental terminal features]
:::caution[Experimental terminal APIs]
AppHost-owned terminals and terminal interaction APIs are experimental and may change in future releases.
:::

Expand Down
Loading
Loading