From dd1f612a3e764ddc2c4da32a4f5c7445c8f43614 Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:30:10 -0600 Subject: [PATCH 1/8] Consolidate docs-from-code updates for Aspire 17.0 Validates and consolidates the open docs-from-code PRs that relate to IEvangelist's product work or request their review, checking each against its merged microsoft/aspire source and the product release/17.0 branch. Also aligns WSLc guidance with the 3.0.4.0 minimum and limited publish support, and documents that WithTerminal/TerminalOptions are no longer experimental (ASPIRETERMINAL001 now covers the remaining terminal APIs). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../content/docs/app-host/configuration.mdx | 24 ++++++++- .../content/docs/app-host/console-apps.mdx | 6 +-- .../docs/app-host/go-apphost-conventions.mdx | 25 ++++++++- .../content/docs/app-host/with-terminal.mdx | 44 ++++++++-------- .../src/content/docs/dashboard/explore.mdx | 16 ++++-- .../src/content/docs/dashboard/terminals.mdx | 29 +++++++++-- .../kubernetes/persistent-volumes.mdx | 40 +++++++++++++++ .../docs/diagnostics/aspireterminal001.mdx | 20 ++++---- .../src/content/docs/diagnostics/overview.mdx | 2 +- .../extensibility/interaction-service.mdx | 4 ++ .../fundamentals/container-networking.mdx | 10 ++++ .../docs/fundamentals/networking-overview.mdx | 51 +++++++++++++++++++ .../content/docs/get-started/aspire-sdk.mdx | 2 + .../get-started/aspire-vscode-extension.mdx | 6 ++- .../docs/get-started/prerequisites.mdx | 16 ++++-- .../docs/get-started/troubleshooting.mdx | 16 ++++++ .../cli/commands/aspire-agent-init.mdx | 2 + .../cli/commands/aspire-describe.mdx | 12 ++++- .../reference/cli/commands/aspire-doctor.mdx | 8 +-- .../reference/cli/commands/aspire-init.mdx | 2 +- .../cli/commands/aspire-secret-path.mdx | 2 + .../reference/cli/commands/aspire-secret.mdx | 10 ++++ .../reference/cli/commands/aspire-update.mdx | 2 +- .../cli/includes/config-settings-table.md | 2 + .../cli/microsoft-collected-cli-telemetry.mdx | 4 +- .../src/content/docs/whats-new/aspire-17.mdx | 2 +- .../tests/e2e/custom-components.spec.ts | 8 +-- 27 files changed, 294 insertions(+), 71 deletions(-) diff --git a/src/frontend/src/content/docs/app-host/configuration.mdx b/src/frontend/src/content/docs/app-host/configuration.mdx index 026f681f5f..b70cb77388 100644 --- a/src/frontend/src/content/docs/app-host/configuration.mdx +++ b/src/frontend/src/content/docs/app-host/configuration.mdx @@ -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. | @@ -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` | `/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` | `/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 diff --git a/src/frontend/src/content/docs/app-host/console-apps.mdx b/src/frontend/src/content/docs/app-host/console-apps.mdx index 0a3a81af17..3288f3be0a 100644 --- a/src/frontend/src/content/docs/app-host/console-apps.mdx +++ b/src/frontend/src/content/docs/app-host/console-apps.mdx @@ -741,11 +741,7 @@ With `WithExplicitStart`, the resource appears in the Aspire dashboard but doesn user input to the process's stdin. -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 diff --git a/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx b/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx index 98798d978a..8c2662fca1 100644 --- a/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx +++ b/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx @@ -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` 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: @@ -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") @@ -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" @@ -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 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 a2a1ff6a23..1deaf410e0 100644 --- a/src/frontend/src/content/docs/app-host/with-terminal.mdx +++ b/src/frontend/src/content/docs/app-host/with-terminal.mdx @@ -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 13.6 preview] -This page describes resource-terminal behavior and defaults for Aspire 13.6 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/). @@ -47,7 +43,6 @@ await builder.build().run(); ```csharp title="AppHost.cs" -#pragma warning disable ASPIRETERMINAL001 var builder = DistributedApplication.CreateBuilder(args); builder.AddExecutable("repl", "python3", ".", "-i", "-q") @@ -61,10 +56,6 @@ builder.Build().Run(); 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). - - ## When to use WithTerminal Reach for `WithTerminal` when a resource is interactive rather than a plain background service: @@ -105,21 +96,25 @@ To query a running database or cache, use the integration's [`WithRepl()` comman The terminal session is described by a set of options with sensible defaults: -| Option | Default | Description | -| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Columns` | `120` | The initial number of columns for the terminal grid. | -| `Rows` | `30` | The initial number of rows for the terminal grid. | -| `ShowTerminalHost` | `false` | Whether the hidden per-replica terminal host resources appear in the dashboard and CLI resource lists **and** export their diagnostic logs, metrics, and traces. Set to `true` to diagnose terminal-host startup or connectivity issues. | +| Option | Default | Description | +| --------- | ------- | ---------------------------------------------------- | +| `Columns` | `132` | The initial number of columns for the terminal grid. | +| `Rows` | `50` | The initial number of rows for the terminal grid. | + +When you don't set either dimension, the dashboard automatically fits the terminal grid to the view when you open the terminal. Setting `Columns` or `Rows`, even to its default value, turns off automatic fitting: the dashboard keeps the terminal's current dimensions until you request a resize. A configuration callback that doesn't set either dimension keeps automatic fitting. -