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
5 changes: 5 additions & 0 deletions src/frontend/config/sidebar/docs.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1164,6 +1164,11 @@ export const docsTopics = {
label: 'Multi-language integrations',
slug: 'extensibility/multi-language-integration-authoring',
},
{
label: 'TypeScript hosting integrations',
slug: 'extensibility/typescript-hosting-integrations',
badge: 'Experimental',
},
],
},
{
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
82 changes: 82 additions & 0 deletions src/frontend/src/content/docs/app-host/executable-resources.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,88 @@ Aspire 13.3 unified non-C# AppHost environment assignment behind a single `withE

When upgrading to Aspire 13.3, replace every earlier per-kind environment helper call with `withEnvironment(name, value)`. The 13.3 TypeScript SDK doesn't generate compatibility aliases for those helpers.

## Declare required commands

Executables depend on tools that must be installed on the developer's machine. Use <ApiReference name="Aspire.Hosting.RequiredCommandResourceExtensions.WithRequiredCommand" /> to declare a command that a resource needs, and optionally a link to installation instructions. You can call it on any resource, not only executables, and call it more than once to declare several commands:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var frontend = builder.AddExecutable("frontend", "vercel", ".", "dev")
.WithRequiredCommand("vercel", helpLink: "https://vercel.com/docs/cli");

builder.Build().Run();
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
```typescript title="apphost.mts" twoslash
import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const frontend = await builder.addExecutable("frontend", "vercel", ".", ["dev"])
.withRequiredCommand("vercel", { helpLink: "https://vercel.com/docs/cli" });

await builder.build().run();
```
</TabItem>
</Tabs>

Before the resource starts, Aspire checks that the command exists. A command that contains a directory separator is treated as a path to a file; otherwise Aspire searches the `PATH` (on Windows, `PATHEXT` extensions are also tried). If the command isn't found, Aspire:

- Logs a warning that the resource may fail to start.
- Shows a **Missing command** notification in the dashboard, with an **Installation instructions** link when you provide `helpLink`.
- Still lets the resource attempt to start. The check never blocks startup.

When several resources require the same command with the same validation, Aspire checks it and shows the notification only once per AppHost run.

### Validate the resolved command

To check more than whether the command exists, such as its version or install location, pass a validation callback. The callback runs only after the command is found and receives a `RequiredCommandValidationContext` with the resolved `ResolvedPath`, a `Services` provider, and a `CancellationToken`. Return `context.Success()` or `context.Failure(message)`. In TypeScript, use `withRequiredCommandValidation`:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var worker = builder.AddExecutable("worker", "python", ".", "worker.py")
.WithRequiredCommand(
"python",
context => Task.FromResult(
context.ResolvedPath.Contains(".venv")
? context.Success()
: context.Failure($"Activate the project's virtual environment. Found: {context.ResolvedPath}")),
helpLink: "https://docs.python.org/3/library/venv.html");

builder.Build().Run();
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
```typescript title="apphost.mts" twoslash
import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const worker = await builder.addExecutable("worker", "python", ".", ["worker.py"])
.withRequiredCommandValidation(
"python",
async (context) => {
const resolvedPath = await context.resolvedPath();
return resolvedPath.includes(".venv")
? context.success()
: context.failure(`Activate the project's virtual environment. Found: ${resolvedPath}`);
},
{ helpLink: "https://docs.python.org/3/library/venv.html" });

await builder.build().run();
```
</TabItem>
</Tabs>

A failed validation is reported the same way as a missing command: the warning and notification include your failure message, and the resource still attempts to start.

## Publishing with PublishAsDockerFile

For production deployment, executable resources need to be containerized. Use the <ApiReference name="Aspire.Hosting.ExecutableResourceBuilderExtensions.PublishAsDockerFile" /> method to specify how the executable should be packaged:
Expand Down
4 changes: 4 additions & 0 deletions src/frontend/src/content/docs/dashboard/explore.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,8 @@ Select **Group resources** to group the list by tags, resource type, or state, o

<ThemeImage dark={resourcesGrouped} light={resourcesGroupedLight} alt="A screenshot of the Aspire dashboard Resources page with resources grouped by resource type." />

Some resources, such as the management containers of integrations, are hidden by default. To include them, select **View options** (**...**) in the resource list and then **Show hidden resources**. Hidden resources are marked with an eye-off icon in the resource list and graph, so you can tell them apart from resources that are normally visible.

### Resource display order

By default, the resource list is ordered by resource type and then by name. To change where a resource appears, call `WithDisplayOrder` in the AppHost. It's a relative sort key: resources with a higher value appear first, resources without a value count as `0`, and a negative value moves a resource after them. Resources with the same value are sorted by name. If you reorder resources in the dashboard, your saved order takes precedence.
Expand Down Expand Up @@ -319,6 +321,8 @@ In the preceding example, `api` appears before `worker`, and both appear before

The Graph view and the telemetry pages (Console logs, Structured logs, Traces, and Metrics) show a resource list sidebar. Drag the splitter between the sidebar and the content to resize it. Select **Collapse resource list** to hide it and give the content more room.

When a resource has unviewed error logs, its row shows an error count badge. Select the badge to open the resource's [structured logs](#structured-logs-page) filtered to errors, without changing the current resource selection.

<ThemeImage dark={resourceListCollapse} light={resourceListCollapseLight} alt="A screenshot of the Aspire dashboard Metrics page with the Collapse resource list button highlighted." />

When the sidebar is collapsed, a resource drop-down replaces it. Select the drop-down to switch resources, and type in its **Filter** box to quickly find a resource.
Expand Down
83 changes: 78 additions & 5 deletions src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ This first deploy serves plain HTTP only. Continue to the next step before expos
var certManager = aks.AddCertManager("cert-manager");

var letsencrypt = certManager.AddIssuer("letsencrypt-prod")
.WithLetsEncryptProduction("ops@contoso.com")
.WithAcmeServer("https://acme-v02.api.letsencrypt.org/directory", "ops@contoso.com")
.WithHttp01Solver();

aks.AddGateway("storefront")
Expand All @@ -380,7 +380,10 @@ aks.AddGateway("storefront")
const certManager = await aks.addCertManager('cert-manager');

const letsencrypt = await certManager.addIssuer('letsencrypt-prod');
await letsencrypt.withLetsEncryptProduction('ops@contoso.com');
await letsencrypt.withAcmeServer(
'https://acme-v02.api.letsencrypt.org/directory',
'ops@contoso.com'
);
await letsencrypt.withHttp01Solver();

const storefront = await aks.addGateway('storefront');
Expand Down Expand Up @@ -423,9 +426,79 @@ await storefront.withTls(letsencrypt, {
</Tabs>

<Aside type="tip">
Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, swap <ApiReference name="Aspire.Hosting.CertManagerExtensions.WithLetsEncryptProduction" /> for <ApiReference name="Aspire.Hosting.CertManagerExtensions.WithLetsEncryptStaging" /> so failed attempts don't cost you your weekly quota. Browsers will warn on staging certificates — flip back to production once everything works end-to-end.
Let's Encrypt's production endpoint enforces strict rate limits. While iterating on your AppHost, pass the staging directory URL (`https://acme-staging-v02.api.letsencrypt.org/directory`) to <ApiReference name="Aspire.Hosting.CertManagerExtensions.WithAcmeServer" /> so failed attempts don't cost you your weekly quota. Browsers will warn on staging certificates — flip back to production once everything works end-to-end.
</Aside>

#### Choose the ACME directory per environment

`WithAcmeServer` accepts the ACME directory URL and contact email either as two literal strings or as two parameters. Use parameters to select the directory per environment without changing the AppHost:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
var serverUrl = builder.AddParameter("acmeserver");
var email = builder.AddParameter("acmeemail");

var issuer = certManager.AddIssuer("acme")
.WithAcmeServer(serverUrl, email)
.WithHttp01Solver();
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
```typescript title="apphost.mts"
const serverUrl = await builder.addParameter('acmeserver');
const email = await builder.addParameter('acmeemail');

const issuer = await certManager.addIssuer('acme');
await issuer.withAcmeServer(serverUrl, email);
await issuer.withHttp01Solver();
```
</TabItem>
</Tabs>

Set `Parameters__acmeserver` and `Parameters__acmeemail` before you run `aspire deploy`. You can't mix a literal URL with a parameter email; use two strings or two parameters.

#### Use a certificate authority that requires External Account Binding

Some ACME certificate authorities, such as ZeroSSL and Google Trust Services, require [External Account Binding (EAB)](https://www.rfc-editor.org/rfc/rfc8555.html#section-7.3.4) to link the ACME account cert-manager registers to your existing account with the provider. Get an EAB key ID and HMAC key from the provider, then call `WithExternalAccountBinding` after `WithAcmeServer`:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
var keyId = builder.AddParameter("acmeeabkeyid");
var hmacKey = builder.AddParameter("acmeeabhmackey", secret: true);

var zeroSsl = certManager.AddIssuer("zerossl")
.WithAcmeServer("https://acme.zerossl.com/v2/DV90", "ops@contoso.com")
.WithExternalAccountBinding(keyId, hmacKey)
.WithHttp01Solver();
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
```typescript title="apphost.mts"
const keyId = await builder.addParameter('acmeeabkeyid');
const hmacKey = await builder.addParameter('acmeeabhmackey', { secret: true });

const zeroSsl = await certManager.addIssuer('zerossl');
await zeroSsl.withAcmeServer('https://acme.zerossl.com/v2/DV90', 'ops@contoso.com');
await zeroSsl.withExternalAccountBinding(keyId, hmacKey);
await zeroSsl.withHttp01Solver();
```
</TabItem>
</Tabs>

Both EAB values must be parameters, and the HMAC key must be a secret parameter. Supply them from your pipeline's secret store as `Parameters__acmeeabkeyid` and `Parameters__acmeeabhmackey`, passing the provider's HMAC key text unchanged. At deploy time, Aspire stores the HMAC key in a Kubernetes Secret named `<issuer>-eab` that cert-manager reads; the key isn't written to published artifacts, and `aspire destroy` removes the Secret. EAB only authorizes account registration—the HTTP-01 challenge still validates domain ownership.

| Provider | ACME directory URL | EAB required |
|---|---|---|
| Let's Encrypt (production) | `https://acme-v02.api.letsencrypt.org/directory` | No |
| Let's Encrypt (staging) | `https://acme-staging-v02.api.letsencrypt.org/directory` | No |
| ZeroSSL | `https://acme.zerossl.com/v2/DV90` | Yes |
| Google Trust Services (production) | `https://dv.acme-v02.api.pki.goog/directory` | Yes |
| Google Trust Services (staging) | `https://dv.acme-v02.test-api.pki.goog/directory` | Yes |

Some providers issue single-use or expiring EAB credentials. Aspire doesn't acquire or refresh them; supply a fresh pair when cert-manager needs to register a new ACME account. Existing accounts are reused.

#### How the certificate gets issued

cert-manager validates domain ownership using the **HTTP-01** challenge configured by <ApiReference name="Aspire.Hosting.CertManagerExtensions.WithHttp01Solver" /> — it asks the gateway to serve a token at `/.well-known/acme-challenge/<token>` and verifies the response. There is no DNS API access required, so this works for the auto-assigned `*.alb.azure.com` FQDN out of the box.
Expand Down Expand Up @@ -671,13 +744,13 @@ Common causes:

- **DNS hasn't propagated yet** when using a custom domain — Let's Encrypt fetches `http://<your-host>/.well-known/acme-challenge/...` and that has to resolve to the AGC frontend.
- **HTTP traffic is blocked** between Let's Encrypt and the gateway — HTTP-01 needs port 80 open. AGC keeps the HTTP listener that `AddGateway` generates open by default; don't remove it.
- **Production rate limit hit** while iterating — switch the issuer to `WithLetsEncryptStaging` until everything else works, then flip back to production.
- **Production rate limit hit** while iterating — point the issuer's `WithAcmeServer` call at the Let's Encrypt staging directory until everything else works, then flip back to production.
- **The contact email was rejected by ACME** — see [Let's Encrypt rejects the contact email](#lets-encrypt-rejects-the-contact-email).
- **The bootstrap TLS secret is missing** — see [Gateway HTTPS listener reports `InvalidCertificateRef`](#gateway-https-listener-reports-invalidcertificateref).

### Let's Encrypt rejects the contact email

The first time you `aspire deploy` with `WithLetsEncryptProduction(email)` or `WithLetsEncryptStaging(email)`, cert-manager creates an ACME account using that email. Let's Encrypt validates the address and refuses to register accounts whose email uses a reserved or forbidden domain. The `ClusterIssuer` will report `Ready=False` and `kubectl describe clusterissuer <name>` will show one of:
The first time you `aspire deploy` with `WithAcmeServer(serverUrl, email)` pointing at Let's Encrypt, cert-manager creates an ACME account using that email. Let's Encrypt validates the address and refuses to register accounts whose email uses a reserved or forbidden domain. The `ClusterIssuer` will report `Ready=False` and `kubectl describe clusterissuer <name>` will show one of:

- `Domain name does not end with a valid public suffix` — the TLD isn't a registered public suffix. Reserved TLDs from RFC 2606 (`.test`, `.example`, `.invalid`, `.localhost`) are common offenders.
- `contact email has forbidden domain example.com` — Let's Encrypt explicitly blocks the IANA example domains (`example.com`, `example.net`, `example.org`).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import ApiReference from '@components/ApiReference.astro';
/>

:::note[Retired in Aspire 17.0]
Starting with Aspire 17.0, the required-command validation APIs (the `WithRequiredCommand` overload that accepts a validation callback, `RequiredCommandAnnotation`, `IRequiredCommandValidator`, `RequiredCommandValidationContext`, and `RequiredCommandValidationResult`) are stable and no longer report `ASPIRECOMMAND001`. After you upgrade, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. The rest of this page describes the diagnostic as it applied to earlier versions.
Starting with Aspire 17.0, the required-command validation APIs (the `WithRequiredCommand` overload that accepts a validation callback, `RequiredCommandAnnotation`, `IRequiredCommandValidator`, `RequiredCommandValidationContext`, and `RequiredCommandValidationResult`) are stable and no longer report `ASPIRECOMMAND001`. After you upgrade, remove any `ASPIRECOMMAND001` suppressions from _.editorconfig_ files, project files, and `#pragma warning` directives. For current usage, see [Declare required commands](/app-host/executable-resources/#declare-required-commands). The rest of this page describes the diagnostic as it applied to earlier versions.
:::

> Required command validation types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1191,5 +1191,6 @@ Types that are **not** ATS-compatible include: interpolated string handlers and
## See also

- [Build your first app](/get-started/first-app/?lang=typescript) — Get started with a TypeScript AppHost
- [Author hosting integrations in TypeScript](/extensibility/typescript-hosting-integrations/) — Write an integration in TypeScript instead of C# (experimental)
- [Custom resources](/extensibility/custom-resources/) — Creating custom resource types
- [Integrations overview](/integrations/overview/) — Available integrations
Loading
Loading