From 8f74d150dfde1d68df72d8980ec2f4ade3199b37 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Thu, 8 Oct 2026 15:55:05 +0100 Subject: [PATCH 1/9] Changed API references in English prose text to use ApiRefernce.astro where appropriate. --- .../app-host/certificate-configuration.mdx | 11 ++--- .../content/docs/app-host/container-files.mdx | 9 ++-- .../docs/app-host/container-registry.mdx | 5 ++- .../src/content/docs/app-host/eventing.mdx | 13 +++--- .../docs/app-host/executable-resources.mdx | 9 ++-- .../app-host/migrate-from-docker-compose.mdx | 23 +++++----- .../docs/app-host/resource-lifetimes.mdx | 15 ++++--- .../docs/app-host/typescript-apphost.mdx | 5 ++- .../content/docs/app-host/with-terminal.mdx | 7 +-- .../content/docs/app-host/withdockerfile.mdx | 11 ++--- .../multi-language-architecture.mdx | 5 ++- .../architecture/resource-api-patterns.mdx | 3 +- .../docs/architecture/resource-examples.mdx | 4 +- .../architecture/resource-hierarchies.mdx | 7 +-- .../docs/architecture/resource-publishing.mdx | 3 +- .../docs/dashboard/ephemeral-terminals.mdx | 4 +- .../src/content/docs/dashboard/explore.mdx | 5 ++- .../dashboard/telemetry-after-deployment.mdx | 3 +- .../src/content/docs/dashboard/terminals.mdx | 5 ++- .../docs/deployment/azure/app-service.mdx | 5 ++- .../deployment/azure/azure-developer-cli.mdx | 5 ++- .../azure/azure-security-best-practices.mdx | 5 ++- .../docs/deployment/azure/container-apps.mdx | 9 ++-- .../docs/deployment/azure/sandboxes.mdx | 15 ++++--- .../docs/deployment/custom-deployments.mdx | 5 ++- .../docs/deployment/deploy-with-aspire.mdx | 3 +- .../docs/deployment/docker-compose.mdx | 23 +++++----- .../content/docs/deployment/environments.mdx | 5 ++- .../docs/deployment/javascript-apps.mdx | 27 +++++------ .../deployment/kubernetes-gateway-aks.mdx | 9 ++-- .../deployment/kubernetes-ingress-aks.mdx | 9 ++-- .../docs/deployment/kubernetes-ingress.mdx | 7 +-- .../docs/deployment/kubernetes/aks.mdx | 25 ++++++----- .../docs/deployment/kubernetes/clusters.mdx | 9 ++-- .../deployment/kubernetes/helm-charts.mdx | 3 +- .../kubernetes/persistent-volumes.mdx | 9 ++-- .../src/content/docs/deployment/pipelines.mdx | 9 ++-- .../docs/diagnostics/aspireacadomains001.mdx | 3 +- .../docs/diagnostics/aspireacanaming001.mdx | 3 +- .../docs/diagnostics/aspireazure002.mdx | 3 +- .../docs/diagnostics/aspireazure003.mdx | 3 +- .../docs/diagnostics/aspireblazor001.mdx | 3 +- .../docs/diagnostics/aspirebrowserlogs001.mdx | 3 +- .../diagnostics/aspirecertificates001.mdx | 5 ++- .../docs/diagnostics/aspirecommand001.mdx | 3 +- .../docs/diagnostics/aspirecompute002.mdx | 3 +- .../docs/diagnostics/aspirecompute003.mdx | 3 +- .../docs/diagnostics/aspirecosmosdb001.mdx | 3 +- .../docs/diagnostics/aspirecsharpapps001.mdx | 3 +- .../aspiredockerfilebuilder001.mdx | 3 +- .../diagnostics/aspiredotnetproject001.mdx | 5 ++- .../docs/diagnostics/aspiredotnettool001.mdx | 3 +- .../docs/diagnostics/aspiredurabletask001.mdx | 11 ++--- .../docs/diagnostics/aspireextension001.mdx | 3 +- .../diagnostics/aspirehostingpython001.mdx | 3 +- .../docs/diagnostics/aspirejavascript001.mdx | 11 ++--- .../content/docs/diagnostics/aspiremcp001.mdx | 3 +- .../docs/diagnostics/aspirepersistence001.mdx | 9 ++-- .../docs/diagnostics/aspirepipelines003.mdx | 3 +- .../docs/diagnostics/aspirepostgres001.mdx | 5 ++- .../docs/diagnostics/aspireprobes001.mdx | 3 +- .../diagnostics/aspireprocesscommand001.mdx | 3 +- .../docs/diagnostics/aspireprojects001.mdx | 3 +- .../docs/diagnostics/aspireradius003.mdx | 3 +- .../docs/diagnostics/aspireterminal001.mdx | 3 +- .../docs/diagnostics/aspireusersecrets001.mdx | 5 ++- .../src/content/docs/diagnostics/overview.mdx | 14 +++--- .../docs/extensibility/custom-resources.mdx | 5 ++- .../extensibility/interaction-service.mdx | 3 +- .../multi-language-integration-authoring.mdx | 3 +- .../fundamentals/annotations-overview.mdx | 9 ++-- .../fundamentals/container-networking.mdx | 3 +- .../fundamentals/custom-resource-commands.mdx | 5 ++- .../fundamentals/custom-resource-urls.mdx | 11 ++--- .../fundamentals/environment-variables.mdx | 5 ++- .../docs/fundamentals/external-parameters.mdx | 13 +++--- .../docs/fundamentals/health-checks.mdx | 7 +-- .../docs/fundamentals/http-commands.mdx | 3 +- .../docs/fundamentals/networking-overview.mdx | 9 ++-- .../fundamentals/persist-data-volumes.mdx | 13 +++--- .../docs/fundamentals/service-discovery.mdx | 5 ++- .../get-started/add-aspire-existing-app.mdx | 2 +- .../docs/get-started/ai-coding-agents.mdx | 3 +- .../content/docs/get-started/aspire-sdk.mdx | 3 +- .../get-started/aspire-vscode-extension.mdx | 3 +- .../ai/github-models/github-models-host.mdx | 5 ++- .../integrations/ai/ollama/ollama-connect.mdx | 3 +- .../integrations/ai/ollama/ollama-host.mdx | 9 ++-- .../integrations/ai/openai/openai-host.mdx | 9 ++-- .../caching/garnet/garnet-connect.mdx | 3 +- .../caching/garnet/garnet-host.mdx | 7 +-- .../redis-distributed-get-started.mdx | 3 +- .../redis-distributed-host.mdx | 11 ++--- .../integrations/caching/redis-extensions.mdx | 5 ++- .../caching/redis/redis-connect.mdx | 3 +- .../integrations/caching/redis/redis-host.mdx | 9 ++-- .../caching/valkey/valkey-connect.mdx | 3 +- .../caching/valkey/valkey-host.mdx | 9 ++-- .../integrations/cloud/azure/aks/index.mdx | 9 ++-- .../azure-ai-foundry-connect.mdx | 3 +- .../azure-ai-foundry-get-started.mdx | 5 ++- .../azure-ai-foundry-host.mdx | 43 +++++++++--------- .../azure-ai-inference-host.mdx | 3 +- .../azure-ai-search/azure-ai-search-host.mdx | 9 ++-- .../azure-app-configuration-host.mdx | 19 ++++---- .../azure-app-service-get-started.mdx | 3 +- .../azure-app-service-host.mdx | 13 +++--- .../azure/azure-application-insights.mdx | 9 ++-- .../azure-cache-redis-connect.mdx | 5 ++- .../azure-cache-redis-host.mdx | 13 +++--- .../cloud/azure/azure-connector-namespace.mdx | 5 ++- .../azure-container-registry-connect.mdx | 5 ++- .../azure-container-registry-get-started.mdx | 3 +- .../azure-container-registry-host.mdx | 15 ++++--- .../azure-cosmos-db-connect.mdx | 5 ++- .../azure-cosmos-db/azure-cosmos-db-host.mdx | 27 +++++------ .../cloud/azure/azure-data-explorer.mdx | 11 ++--- .../cloud/azure/azure-default-credential.mdx | 3 +- .../azure-event-hubs-host.mdx | 19 ++++---- .../cloud/azure/azure-front-door.mdx | 11 ++--- .../azure-functions-connect.mdx | 3 +- .../azure-functions-get-started.mdx | 3 +- .../azure-functions/azure-functions-host.mdx | 15 ++++--- .../azure-key-vault/azure-key-vault-host.mdx | 17 +++---- .../cloud/azure/azure-log-analytics.mdx | 7 +-- .../azure/azure-openai/azure-openai-host.mdx | 13 +++--- .../azure-postgresql-connect.mdx | 3 +- .../azure-postgresql-get-started.mdx | 3 +- .../azure-postgresql-host.mdx | 19 ++++---- .../azure-service-bus-host.mdx | 21 ++++----- .../azure-signalr/azure-signalr-connect.mdx | 3 +- .../azure-signalr/azure-signalr-host.mdx | 13 +++--- .../azure-sql-database-connect.mdx | 5 ++- .../azure-sql-database-get-started.mdx | 5 ++- .../azure-sql-database-host.mdx | 19 ++++---- .../azure-storage-blobs-connect.mdx | 7 +-- .../azure-storage-blobs-host.mdx | 21 ++++----- .../cloud/azure/azure-storage-datalake.mdx | 7 +-- .../azure-storage-queues-connect.mdx | 3 +- .../azure-storage-queues-get-started.mdx | 3 +- .../azure-storage-queues-host.mdx | 13 +++--- .../azure-storage-tables-connect.mdx | 3 +- .../azure-storage-tables-get-started.mdx | 3 +- .../azure-storage-tables-host.mdx | 21 ++++----- .../cloud/azure/azure-virtual-network.mdx | 37 +++++++-------- .../azure-web-pubsub-connect.mdx | 3 +- .../azure-web-pubsub-host.mdx | 13 +++--- .../cloud/azure/configure-container-apps.mdx | 17 +++---- .../cloud/azure/container-app-jobs.mdx | 9 ++-- .../cloud/azure/customize-resources.mdx | 15 ++++--- .../cloud/azure/local-provisioning.mdx | 5 ++- .../integrations/cloud/azure/overview.mdx | 13 +++--- .../cloud/azure/user-assigned-identity.mdx | 7 +-- .../docs/integrations/compute/docker.mdx | 31 ++++++------- .../docs/integrations/compute/floci.mdx | 7 +-- .../content/docs/integrations/compute/k3s.mdx | 17 +++---- .../docs/integrations/compute/kubernetes.mdx | 13 +++--- .../hosting-integrations.mdx | 7 +-- .../secure-communication.mdx | 3 +- .../clickhouse/clickhouse-connect.mdx | 3 +- .../databases/clickhouse/clickhouse-host.mdx | 5 ++- .../azure-cosmos-db/azure-cosmos-db-host.mdx | 11 ++--- .../azure-sql/azure-sql-get-started.mdx | 3 +- .../efcore/azure-sql/azure-sql-host.mdx | 11 ++--- .../databases/efcore/migrations.mdx | 9 ++-- .../efcore/mongodb/mongodb-efcore-connect.mdx | 3 +- .../databases/efcore/mysql/mysql-connect.mdx | 3 +- .../databases/efcore/oracle/oracle-host.mdx | 9 ++-- .../efcore/postgres/postgresql-connect.mdx | 3 +- .../databases/efcore/seed-database.mdx | 5 ++- .../efcore/sql-server/sql-server-connect.mdx | 3 +- .../elasticsearch/elasticsearch-connect.mdx | 5 ++- .../elasticsearch/elasticsearch-host.mdx | 3 +- .../databases/kurrentdb/kurrentdb-connect.mdx | 3 +- .../meilisearch/meilisearch-connect.mdx | 3 +- .../meilisearch/meilisearch-host.mdx | 7 +-- .../databases/milvus/milvus-host.mdx | 5 ++- .../databases/mongodb/mongodb-extensions.mdx | 5 ++- .../databases/mongodb/mongodb-host.mdx | 25 ++++++----- .../databases/mysql/mysql-extensions.mdx | 7 +-- .../databases/mysql/mysql-get-started.mdx | 3 +- .../databases/mysql/mysql-host.mdx | 9 ++-- .../databases/postgres/postgres-host.mdx | 13 +++--- .../postgres/postgresql-extensions.mdx | 9 ++-- .../databases/ravendb/ravendb-connect.mdx | 3 +- .../databases/ravendb/ravendb-host.mdx | 3 +- .../sql-server/sql-server-extensions.mdx | 7 +-- .../databases/sql-server/sql-server-host.mdx | 9 ++-- .../databases/sqlite/sqlite-connect.mdx | 3 +- .../databases/sqlite/sqlite-get-started.mdx | 3 +- .../databases/sqlite/sqlite-host.mdx | 5 ++- .../databases/surrealdb/surrealdb-connect.mdx | 3 +- .../databases/surrealdb/surrealdb-host.mdx | 7 +-- .../integrations/devtools/browser-logs.mdx | 3 +- .../integrations/devtools/dab/dab-host.mdx | 3 +- .../integrations/devtools/dev-tunnels.mdx | 7 +-- .../devtools/flagd/flagd-host.mdx | 5 ++- .../devtools/goff/goff-connect.mdx | 3 +- .../integrations/devtools/goff/goff-host.mdx | 9 ++-- .../docs/integrations/devtools/k6/k6-host.mdx | 11 ++--- .../devtools/mailpit/mailpit-connect.mdx | 3 +- .../sql-projects/sql-projects-host.mdx | 13 +++--- .../integrations/dotnet/blazor-connect.mdx | 3 +- .../dotnet/blazor-get-started.mdx | 5 ++- .../integrations/dotnet/blazor-hosting.mdx | 2 +- .../dotnet/csharp-file-based-apps.mdx | 5 ++- .../dotnet/dotnet-tool-resources.mdx | 15 ++++--- .../integrations/dotnet/launch-profiles.mdx | 7 +-- .../content/docs/integrations/dotnet/maui.mdx | 5 ++- .../integrations/dotnet/project-resources.mdx | 15 ++++--- .../docs/integrations/frameworks/bun-apps.mdx | 5 ++- .../frameworks/deno/deno-get-started.mdx | 3 +- .../frameworks/deno/deno-host.mdx | 11 ++--- .../frameworks/dotnet/dotnet-get-started.mdx | 5 ++- .../frameworks/dotnet/dotnet-host.mdx | 9 ++-- .../frameworks/go/go-get-started.mdx | 3 +- .../integrations/frameworks/go/go-host.mdx | 19 ++++---- .../frameworks/java/java-connect.mdx | 4 +- .../integrations/frameworks/javascript.mdx | 31 ++++++------- .../frameworks/nodejs-extensions.mdx | 11 ++--- .../docs/integrations/frameworks/orleans.mdx | 5 ++- .../frameworks/perl/perl-get-started.mdx | 3 +- .../frameworks/perl/perl-host.mdx | 23 +++++----- .../frameworks/powershell/powershell-host.mdx | 11 ++--- .../docs/integrations/frameworks/python.mdx | 25 ++++++----- .../frameworks/rust/rust-host.mdx | 2 +- .../integrations/frameworks/wpf-winforms.mdx | 3 +- .../apache-kafka/apache-kafka-host.mdx | 3 +- .../messaging/lavinmq/lavinmq-host.mdx | 5 ++- .../messaging/nats/nats-get-started.mdx | 3 +- .../integrations/messaging/nats/nats-host.mdx | 3 +- .../messaging/rabbitmq/rabbitmq-connect.mdx | 3 +- .../messaging/rabbitmq/rabbitmq-host.mdx | 7 +-- .../observability/seq/seq-connect.mdx | 3 +- .../integrations/reverse-proxies/yarp.mdx | 11 ++--- .../docs/integrations/security/keycloak.mdx | 19 ++++---- .../cli/commands/aspire-docs-api-search.mdx | 3 +- .../reference/cli/commands/aspire-init.mdx | 3 +- .../docs/testing/accessing-resources.mdx | 3 +- .../docs/testing/advanced-scenarios.mdx | 7 +-- .../docs/testing/write-your-first-test.mdx | 3 +- .../content/docs/whats-new/aspire-13-1.mdx | 11 ++--- .../content/docs/whats-new/aspire-13-2.mdx | 35 ++++++++------- .../content/docs/whats-new/aspire-13-3.mdx | 33 +++++++------- .../content/docs/whats-new/aspire-13-4.mdx | 33 +++++++------- .../content/docs/whats-new/aspire-13-5.mdx | 19 ++++---- .../content/docs/whats-new/aspire-13-6.mdx | 43 +++++++++--------- .../src/content/docs/whats-new/aspire-13.mdx | 45 ++++++++++--------- .../src/content/docs/whats-new/aspire-9-1.mdx | 5 ++- .../src/content/docs/whats-new/aspire-9-2.mdx | 13 +++--- .../src/content/docs/whats-new/aspire-9-3.mdx | 33 +++++++------- .../src/content/docs/whats-new/aspire-9-4.mdx | 21 ++++----- .../src/content/docs/whats-new/aspire-9-5.mdx | 23 +++++----- .../src/content/docs/whats-new/aspire-9.mdx | 13 +++--- 254 files changed, 1230 insertions(+), 977 deletions(-) diff --git a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx index 7acf8fc54a..3ade07657c 100644 --- a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx +++ b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx @@ -6,13 +6,14 @@ description: Configure HTTPS endpoints and certificate trust for Aspire resource import { Aside, Tabs, TabItem } from '@astrojs/starlight/components'; import OsAwareTabs from '@components/OsAwareTabs.astro'; +import ApiReference from '@components/ApiReference.astro'; Aspire provides two complementary sets of certificate APIs: 1. **HTTPS endpoint APIs**: Configure the certificates that resources use for their own HTTPS endpoints (server authentication) 2. **Certificate trust APIs**: Configure which certificates resources trust when making outbound HTTPS connections (client authentication) -Both sets of APIs work together to enable secure HTTPS communication during local development. For example, a Vite frontend might use `WithHttpsDeveloperCertificate` to serve HTTPS traffic, while also using `WithDeveloperCertificateTrust` to trust the dashboard's OTLP endpoint certificate. +Both sets of APIs work together to enable secure HTTPS communication during local development. For example, a Vite frontend might use to serve HTTPS traffic, while also using to trust the dashboard's OTLP endpoint certificate. -Use the `AddContainerRegistry` method to configure a generic container registry for your application. This works with any Docker-compatible registry including DockerHub, GitHub Container Registry, Harbor, and private registries. +Use the method to configure a generic container registry for your application. This works with any Docker-compatible registry including DockerHub, GitHub Container Registry, Harbor, and private registries. ### Basic usage @@ -303,7 +304,7 @@ In the preceding example: ### Using an existing ACR -To use an existing Azure Container Registry, call the `PublishAsExisting` method when you add the ACR: +To use an existing Azure Container Registry, call the method when you add the ACR: diff --git a/src/frontend/src/content/docs/app-host/eventing.mdx b/src/frontend/src/content/docs/app-host/eventing.mdx index ba6dafd55d..f45685daa8 100644 --- a/src/frontend/src/content/docs/app-host/eventing.mdx +++ b/src/frontend/src/content/docs/app-host/eventing.mdx @@ -6,6 +6,7 @@ description: Use the Aspire AppHost eventing APIs for lifecycle events, custom e import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; +import ApiReference from '@components/ApiReference.astro'; In Aspire, eventing allows you to publish and subscribe to events during various AppHost life cycles. Eventing is more flexible than life cycle events. Both let you run arbitrary code during event callbacks, but eventing offers finer control of event timing, publishing, and provides supports for custom events. @@ -110,7 +111,7 @@ builder.Eventing.Subscribe( `builder.Eventing.Subscribe()` API. Use the named callback APIs generated for each supported event, such as `subscribeBeforeStart`, `subscribeAfterResourcesCreated`, `addEventingSubscriber`, and resource - callbacks like `onResourceReady`. + callbacks like . -- `OnInitializeResource` / `onInitializeResource`: Subscribes to the `InitializeResourceEvent`. -- `OnResourceEndpointsAllocated` / `onResourceEndpointsAllocated`: Subscribes to the `ResourceEndpointsAllocatedEvent` event. -- `OnConnectionStringAvailable` / `onConnectionStringAvailable`: Subscribes to the `ConnectionStringAvailableEvent` event. -- `OnBeforeResourceStarted` / `onBeforeResourceStarted`: Subscribes to the `BeforeResourceStartedEvent` event. +- : Subscribes to the `InitializeResourceEvent`. +- : Subscribes to the `ResourceEndpointsAllocatedEvent` event. +- : Subscribes to the `ConnectionStringAvailableEvent` event. +- : Subscribes to the `BeforeResourceStartedEvent` event. - `OnResourceReady` / `onResourceReady`: Subscribes to the `ResourceReadyEvent` event. -- `OnResourceStopped` / `onResourceStopped`: Subscribes to the `ResourceStoppedEvent` event. +- : Subscribes to the `ResourceStoppedEvent` event. When the AppHost is run, by the time the Aspire dashboard is displayed, you should see the following log output in the console: diff --git a/src/frontend/src/content/docs/app-host/executable-resources.mdx b/src/frontend/src/content/docs/app-host/executable-resources.mdx index d02b1ead88..118f282e60 100644 --- a/src/frontend/src/content/docs/app-host/executable-resources.mdx +++ b/src/frontend/src/content/docs/app-host/executable-resources.mdx @@ -4,8 +4,9 @@ description: Host external executable applications in your Aspire AppHost using --- import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import ApiReference from '@components/ApiReference.astro'; -In Aspire, you can host external executable applications alongside your projects using the `AddExecutable` method. This capability is useful when you need to integrate executable applications or tools into your distributed application, such as Node.js applications, Python scripts, or specialized CLI tools. +In Aspire, you can host external executable applications alongside your projects using the method. This capability is useful when you need to integrate executable applications or tools into your distributed application, such as Node.js applications, Python scripts, or specialized CLI tools. ## When to use executable resources @@ -122,7 +123,7 @@ const app = await builder.addExecutable("worker", "python", ".", ["worker.py"]) -When one resource depends on another, `WithReference` passes along environment variables containing the dependent resource's connection details. For example, the `worker` executable's reference to `redis` and `postgres` provides it with the `ConnectionStrings__cache` and `ConnectionStrings__appdb` environment variables, which contain connection strings to these resources. +When one resource depends on another, passes along environment variables containing the dependent resource's connection details. For example, the `worker` executable's reference to `redis` and `postgres` provides it with the `ConnectionStrings__cache` and `ConnectionStrings__appdb` environment variables, which contain connection strings to these resources. ### Access specific endpoint information @@ -282,7 +283,7 @@ When upgrading to Aspire 13.3, replace every earlier per-kind environment helper ## Publishing with PublishAsDockerFile -For production deployment, executable resources need to be containerized. Use the `PublishAsDockerFile` method to specify how the executable should be packaged: +For production deployment, executable resources need to be containerized. Use the method to specify how the executable should be packaged: @@ -353,7 +354,7 @@ When working with executable resources: 1. **Use explicit paths**: For better reliability, use full paths to executables when possible. 1. **Handle dependencies**: Use `WithReference` to establish proper dependency relationships. -1. **Configure explicit start**: Use `WithExplicitStart()` for executables that shouldn't start automatically. +1. **Configure explicit start**: Use for executables that shouldn't start automatically. 1. **Prepare for deployment**: Always use `PublishAsDockerFile()` for production scenarios. 1. **Environment isolation**: Use environment variables rather than command-line arguments for sensitive configuration. 1. **Resource naming**: Use descriptive names that clearly identify the executable's purpose. diff --git a/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx b/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx index 249a486453..c69a2f18d4 100644 --- a/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx +++ b/src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx @@ -5,6 +5,7 @@ description: Compare Aspire and Docker Compose for local development, service di import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; +import ApiReference from '@components/ApiReference.astro'; Docker Compose and Aspire both describe and run multi-service applications. This guide compares their local development workflows and maps Compose services, dependencies, and configuration to an Aspire AppHost written in TypeScript or C#. @@ -157,17 +158,17 @@ await builder.build().run(); **Key differences explained:** - **Build vs. project** — Docker Compose `build:` services become `AddProject()` for .NET apps, which runs them directly instead of in containers - **Ports** — Both examples explicitly map ports (3000 and 5000) -- **Startup order** — Docker Compose uses `depends_on` with health conditions; Aspire uses `WaitFor()` for startup ordering -- **Service discovery** — `WithReference()` only configures service discovery and connection strings; it doesn't control startup order -- **Connection strings** — By default, `WithReference(database)` provides `ConnectionStrings__myapp` using the resource name from `AddDatabase()`. To match a different name like `DefaultConnection`, use a named reference: `.WithReference(database, "DefaultConnection")` -- **Volumes** — `WithDataVolume()` must be called explicitly to add persistent storage; it's not automatic +- **Startup order** — Docker Compose uses `depends_on` with health conditions; Aspire uses for startup ordering +- **Service discovery** — only configures service discovery and connection strings; it doesn't control startup order +- **Connection strings** — By default, `WithReference(database)` provides `ConnectionStrings__myapp` using the resource name from . To match a different name like `DefaultConnection`, use a named reference: `.WithReference(database, "DefaultConnection")` +- **Volumes** — must be called explicitly to add persistent storage; it's not automatic - **Image versions** — `WithImageTag("15")` pins PostgreSQL to version 15 ### Container-based services @@ -277,13 +278,13 @@ Aspire generates .NET-format connection strings, which differ from Docker Compos - Docker Compose: `DATABASE_URL=postgresql://postgres:secret@postgres:5432/main` - Aspire: `ConnectionStrings__main=Host=localhost;Port=12345;Username=postgres;Password=;Database=main` -If your application expects URL-format environment variables, construct them manually with `WithEnvironment()`. See [Environment variables and configuration](#environment-variables-and-configuration) for details. +If your application expects URL-format environment variables, construct them manually with . See [Environment variables and configuration](#environment-variables-and-configuration) for details. **Key differences explained:** -- **Image versions** — Explicitly specified with `WithImageTag()` to match Docker Compose -- **Dockerfile builds** — Docker Compose `build: .` maps to `AddDockerfile("web", ".")`, which builds a container image from a Dockerfile. Use `AddContainer()` for pre-built images that use `image:` in Docker Compose +- **Image versions** — Explicitly specified with to match Docker Compose +- **Dockerfile builds** — Docker Compose `build: .` maps to `AddDockerfile("web", ".")`, which builds a container image from a Dockerfile. Use for pre-built images that use `image:` in Docker Compose - **Ports** — `WithHostPort()` maps to a static host port; without it, Aspire assigns a random port - **Volumes** — `WithDataVolume()` must be called explicitly to add persistent storage - **Startup ordering** — `WaitFor()` controls startup order, similar to Docker Compose `depends_on` with conditions @@ -462,7 +463,7 @@ await builder.build().run(); **Key differences:** - **Named volumes** — Created with `AddVolume()` and shared between containers -- **Bind mounts** — Use `WithBindMount()` for host directory access +- **Bind mounts** — Use for host directory access ### Networking @@ -532,14 +533,14 @@ Successfully migrating from Docker Compose to Aspire requires a systematic appro - **Configure dependencies** with `WithReference()` for service discovery - **Add startup ordering** with `WaitFor()` to match `depends_on` behavior - **Set up environment variables** — Note that connection string formats will differ - - **Migrate health checks** — Use `WithHttpHealthCheck()` or `WithHealthCheck()` for custom checks + - **Migrate health checks** — Use or for custom checks 4. ### Handle data migration For persistent data: - Use `WithDataVolume()` for automatic volume management with integrations - - Use `WithVolume()` for named volumes that need to persist data + - Use for named volumes that need to persist data - Use `WithBindMount()` for host directory mounts when you need direct access to host files 5. ### Test and validate diff --git a/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx b/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx index a39514c1c6..22214da3de 100644 --- a/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx +++ b/src/frontend/src/content/docs/app-host/resource-lifetimes.mdx @@ -10,6 +10,7 @@ import LearnMore from '@components/LearnMore.astro'; import persistentContainer from '@assets/fundamentals/persistent-container-dark.png'; import persistentContainerLight from '@assets/fundamentals/persistent-container-light.png'; import persistentContainerDocker from '@assets/whats-new/aspire-9/persistent-container-docker-desktop.png'; +import ApiReference from '@components/ApiReference.astro'; Aspire resources support a number of different lifetime modes. For example, the default **session lifetime** starts a resource when the AppHost starts and shuts it down when the AppHost exits. A **persistent lifetime** leaves a resource running when the AppHost exits and can reuse the same instance on the next run. @@ -29,11 +30,11 @@ A session lifetime creates the resource when the AppHost starts and disposes of Use session lifetime for resources that should only exist while the AppHost is running, such as local test dependencies, temporary containers, or processes that don't need stable state across runs. Session resources also default to proxied endpoints, which are available while the AppHost is running. -If you previously configured another lifetime and want to return a resource to the default behavior, call `WithSessionLifetime()`. For container resources, `WithLifetime(ContainerLifetime.Session)` is still supported. +If you previously configured another lifetime and want to return a resource to the default behavior, call . For container resources, `WithLifetime(ContainerLifetime.Session)` is still supported. ### Persistent lifetime -A persistent lifetime reuses a previously created resource when possible and doesn't dispose of it when the AppHost stops. Configure this behavior with `WithPersistentLifetime()`, or with the existing container-specific `WithLifetime(ContainerLifetime.Persistent)` API for container resources. +A persistent lifetime reuses a previously created resource when possible and doesn't dispose of it when the AppHost stops. Configure this behavior with , or with the existing container-specific `WithLifetime(ContainerLifetime.Persistent)` API for container resources. Use persistent lifetime for resources that are expensive to initialize, need stable local endpoints, or should remain available while you restart or rebuild the AppHost. Common examples include databases, message brokers, emulators, long-running executables, and project resources that should continue running after the AppHost exits. @@ -80,9 +81,9 @@ Aspire evaluates the source resource's lifetime when it prepares the application ## Defer resource start with explicit start -Use `WithExplicitStart()` to prevent a resource from starting automatically with the rest of the AppHost. The resource appears in the dashboard but remains stopped until you start it manually. +Use to prevent a resource from starting automatically with the rest of the AppHost. The resource appears in the dashboard but remains stopped until you start it manually. -Starting in Aspire 13.5, `WithExplicitStart()` also affects when execution configuration callbacks (for example, `WithEnvironment` and `WithArgs`) are evaluated, depending on whether the resource is session-scoped or persistent. +Starting in Aspire 13.5, `WithExplicitStart()` also affects when execution configuration callbacks (for example, and ) are evaluated, depending on whether the resource is session-scoped or persistent. ### Session-scoped explicit-start resources @@ -257,7 +258,7 @@ Persistent project and executable resources are run by Aspire's orchestrator so ## Match another resource's lifetime -Use `WithLifetimeOf` when a companion resource should follow another resource's lifetime. This is useful when a sidecar, helper process, or supporting service should become persistent only when its source resource is persistent. +Use when a companion resource should follow another resource's lifetime. This is useful when a sidecar, helper process, or supporting service should become persistent only when its source resource is persistent. @@ -305,7 +306,7 @@ The dependent resource's lifetime is evaluated when Aspire prepares the applicat ## Scope cleanup to a parent process -Use `WithParentProcessLifetime` when a resource should survive AppHost restarts but be cleaned up when another process exits. Aspire records the parent process identity instead of retaining a live process handle, so the cleanup scope follows the specific process instance instead of a reused process ID. +Use when a resource should survive AppHost restarts but be cleaned up when another process exits. Aspire records the parent process identity instead of retaining a live process handle, so the cleanup scope follows the specific process instance instead of a reused process ID. @@ -413,7 +414,7 @@ For example, if you have a service named `"postgres"` in an AppHost project loca ### Custom container names -For advanced scenarios, you can set a custom container name using the `WithContainerName` method: +For advanced scenarios, you can set a custom container name using the method: diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index 27c4a361ce..6728fe5fc2 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -7,6 +7,7 @@ description: Learn the files and configuration that make up a TypeScript AppHost import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; import FileTree from 'starlight-plugin-icons/components/FileTree.astro'; import LearnMore from '@components/LearnMore.astro'; +import ApiReference from '@components/ApiReference.astro'; When you create a TypeScript AppHost with `aspire new`, the CLI scaffolds a project with the following structure: @@ -295,7 +296,7 @@ The Aspire CLI supports the following package managers at the **AppHost root** | Deno | `packageManager`, `deno.lock`, `deno.json`, or `deno.jsonc` | Deno 2 or later | | Yarn Classic (v1) | `yarn.lock` with `# yarn lockfile v1` or `packageManager` with `yarn@1.x` | Not supported | -This policy governs the **AppHost root only**. Apps the AppHost orchestrates — for example, a Node.js service added with `addNodeApp`, a Bun guest app, or a workspace package — can use any package manager their own tooling requires; they are independent of the AppHost-root toolchain. +This policy governs the **AppHost root only**. Apps the AppHost orchestrates — for example, a Node.js service added with , a Bun guest app, or a workspace package — can use any package manager their own tooling requires; they are independent of the AppHost-root toolchain. Aspire end-to-end tests cover TypeScript AppHosts with representative `packageManager` pins such as `npm@10.0.0`, `pnpm@10.0.0`, `yarn@4.14.1`, and `bun@1.2.0`. These tested versions are representative points within the supported ranges, not the only versions you can use. @@ -456,7 +457,7 @@ Bun has built-in TypeScript support, so it runs `apphost.mts` directly without ` ### Use Deno as the AppHost runtime -Install Deno 2 or later and select it with a Deno configuration file, lockfile, or a `packageManager` entry such as `"deno@2.0.0"`. The generated AppHost module and resource APIs stay the same. This is distinct from [hosting a Deno application](/integrations/frameworks/deno/deno-host/): `addDenoApp` models a guest resource and doesn't choose the AppHost runtime. +Install Deno 2 or later and select it with a Deno configuration file, lockfile, or a `packageManager` entry such as `"deno@2.0.0"`. The generated AppHost module and resource APIs stay the same. This is distinct from [hosting a Deno application](/integrations/frameworks/deno/deno-host/): models a guest resource and doesn't choose the AppHost runtime. Aspire restores dependencies with `deno install` and validates the AppHost with `deno check`. Deno uses its own configuration rather than `tsconfig.apphost.json`. Watch mode uses Deno's native watcher and checks types on every restart, without `tsx` or `nodemon`. The CLI rejects Deno 1.x. 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 3f7ebb3199..40f341228e 100644 --- a/src/frontend/src/content/docs/app-host/with-terminal.mdx +++ b/src/frontend/src/content/docs/app-host/with-terminal.mdx @@ -10,8 +10,9 @@ import terminalResourceDark from '@assets/dashboard/terminals/terminal-resource- import terminalResourceLight from '@assets/dashboard/terminals/terminal-resource-light.png'; import terminalDetachedDark from '@assets/dashboard/terminals/terminal-detached-dark.png'; import terminalDetachedLight from '@assets/dashboard/terminals/terminal-detached-light.png'; +import ApiReference from '@components/ApiReference.astro'; -If you have a terminal user interface (TUI) application or a shell-based experience that you want to exercise while it runs under Aspire, add `WithTerminal(...)` to the resource. Aspire then exposes an interactive terminal session that you can attach to from the [Aspire dashboard](/dashboard/overview/) or from the [`aspire terminal`](/reference/cli/commands/aspire-terminal/) CLI command. +If you have a terminal user interface (TUI) application or a shell-based experience that you want to exercise while it runs under Aspire, add to the resource. Aspire then exposes an interactive terminal session that you can attach to from the [Aspire dashboard](/dashboard/overview/) or from the [`aspire terminal`](/reference/cli/commands/aspire-terminal/) CLI command. For an introduction to the resource Terminal view, terminal dock, and detached windows, start with [Dashboard terminals](/dashboard/terminals/). @@ -78,7 +79,7 @@ Reach for `WithTerminal` when a resource is interactive rather than a plain back The [TypeScript terminal basics sample](https://github.com/microsoft/aspire-samples/tree/main/samples/terminals/basics-typescript) and [C# terminal basics sample](https://github.com/microsoft/aspire-samples/tree/main/samples/terminals/basics-csharp) demonstrate this with a containerized REST client, an API, and Redis. -The [TypeScript AppHost](https://github.com/microsoft/aspire-samples/blob/main/samples/terminals/basics-typescript/apphost.mts) and [C# AppHost](https://github.com/microsoft/aspire-samples/blob/main/samples/terminals/basics-csharp/apphost.cs) build the client's image with `AddDockerfile`, pass the API endpoint through `BASE_URL`, wait for the API, and enable the terminal with `WithTerminal()`. The client runs as the resource's main process; there is no separate client session to create. +The [TypeScript AppHost](https://github.com/microsoft/aspire-samples/blob/main/samples/terminals/basics-typescript/apphost.mts) and [C# AppHost](https://github.com/microsoft/aspire-samples/blob/main/samples/terminals/basics-csharp/apphost.cs) build the client's image with , pass the API endpoint through `BASE_URL`, wait for the API, and enable the terminal with `WithTerminal()`. The client runs as the resource's main process; there is no separate client session to create. Follow either sample's README to send a request from the resource terminal, change the stored data through Redis's separate REPL command, and read it back through the API. This illustrates the distinction between an interactive resource and an [ephemeral terminal](/dashboard/ephemeral-terminals/) without requiring host installations of the client tools. @@ -170,7 +171,7 @@ builder.Build().Run(); ## Terminals and replicas -Each replica of a resource gets its own independent terminal session. Aspire creates one terminal host per parent replica, so requesting three replicas yields three separate terminals. The order of `WithReplicas` and `WithTerminal` does not matter. For a project-based interactive app in `../Agent/Agent.csproj`: +Each replica of a resource gets its own independent terminal session. Aspire creates one terminal host per parent replica, so requesting three replicas yields three separate terminals. The order of and `WithTerminal` does not matter. For a project-based interactive app in `../Agent/Agent.csproj`: diff --git a/src/frontend/src/content/docs/app-host/withdockerfile.mdx b/src/frontend/src/content/docs/app-host/withdockerfile.mdx index df30b82577..0c1cbab721 100644 --- a/src/frontend/src/content/docs/app-host/withdockerfile.mdx +++ b/src/frontend/src/content/docs/app-host/withdockerfile.mdx @@ -5,8 +5,9 @@ description: Add Dockerfiles to your Aspire app model with WithDockerfile — bu --- import { Aside, Tabs, TabItem } from '@astrojs/starlight/components'; +import ApiReference from '@components/ApiReference.astro'; -With Aspire it's possible to specify a _Dockerfile_ to build when the [AppHost](/get-started/app-host/) is started using either the `AddDockerfile` or `WithDockerfile` extension methods. +With Aspire it's possible to specify a _Dockerfile_ to build when the [AppHost](/get-started/app-host/) is started using either the or extension methods. These two methods serve different purposes: @@ -126,7 +127,7 @@ await pgsql.withPgAdmin(); // Still works because it's still a PostgreSQL resour ## Generate a Dockerfile programmatically -Use `AddDockerfileBuilder` or `WithDockerfileBuilder` when you need Aspire to generate a Dockerfile from AppHost code. These APIs are useful when the Dockerfile depends on AppHost configuration, when you want to compose Dockerfile fragments, or when you want to keep multi-stage image build logic near the resource definition. +Use or when you need Aspire to generate a Dockerfile from AppHost code. These APIs are useful when the Dockerfile depends on AppHost configuration, when you want to compose Dockerfile fragments, or when you want to keep multi-stage image build logic near the resource definition.