diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index 2af25b4f42..5085b76fa6 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -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', + }, ], }, { diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png new file mode 100644 index 0000000000..42a04c006d Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home-light.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png new file mode 100644 index 0000000000..2a6447ecc4 Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-home.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png new file mode 100644 index 0000000000..524e3e047b Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics-light.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png new file mode 100644 index 0000000000..94788432b0 Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-metrics.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png new file mode 100644 index 0000000000..c8a27481d3 Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview-light.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png new file mode 100644 index 0000000000..2e5412ac3d Binary files /dev/null and b/src/frontend/src/assets/whats-new/aspire-17/dashboard-overview.png differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png b/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png deleted file mode 100644 index e174f6bea3..0000000000 Binary files a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources-light.png and /dev/null differ diff --git a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png b/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png deleted file mode 100644 index cc73850a25..0000000000 Binary files a/src/frontend/src/assets/whats-new/aspire-17/testshop-all-resources.png and /dev/null differ 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 b21858ce6e..649d84f9c7 100644 --- a/src/frontend/src/content/docs/app-host/executable-resources.mdx +++ b/src/frontend/src/content/docs/app-host/executable-resources.mdx @@ -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 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: + + + +```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(); +``` + + +```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(); +``` + + + +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`: + + + +```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(); +``` + + +```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(); +``` + + + +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 method to specify how the executable should be packaged: diff --git a/src/frontend/src/content/docs/dashboard/explore.mdx b/src/frontend/src/content/docs/dashboard/explore.mdx index 34644d2ddf..bbad4d49d6 100644 --- a/src/frontend/src/content/docs/dashboard/explore.mdx +++ b/src/frontend/src/content/docs/dashboard/explore.mdx @@ -276,6 +276,8 @@ Select **Group resources** to group the list by tags, resource type, or state, o +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. @@ -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. + 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. diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx index c57c2c3485..eaf617e6d7 100644 --- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx +++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx @@ -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") @@ -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'); @@ -423,9 +426,79 @@ await storefront.withTls(letsencrypt, { +#### 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: + + + +```csharp title="AppHost.cs" +var serverUrl = builder.AddParameter("acmeserver"); +var email = builder.AddParameter("acmeemail"); + +var issuer = certManager.AddIssuer("acme") + .WithAcmeServer(serverUrl, email) + .WithHttp01Solver(); +``` + + +```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(); +``` + + + +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`: + + + +```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(); +``` + + +```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(); +``` + + + +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 `-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 — it asks the gateway to serve a token at `/.well-known/acme-challenge/` 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. @@ -671,13 +744,13 @@ Common causes: - **DNS hasn't propagated yet** when using a custom domain — Let's Encrypt fetches `http:///.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 ` 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 ` 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`). diff --git a/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx b/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx index f4b96f192b..557a18198e 100644 --- a/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspirecommand001.mdx @@ -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. diff --git a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx index 7f1a790bae..f545480e68 100644 --- a/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx +++ b/src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx @@ -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 diff --git a/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx b/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx new file mode 100644 index 0000000000..1027a1416f --- /dev/null +++ b/src/frontend/src/content/docs/extensibility/typescript-hosting-integrations.mdx @@ -0,0 +1,207 @@ +--- +title: Author hosting integrations in TypeScript +description: Write experimental Aspire hosting integrations in TypeScript with AspireExport and defineIntegration, then consume them as builder methods from polyglot AppHosts. +--- + +import { Steps } from '@astrojs/starlight/components'; + +You can write a hosting integration in TypeScript instead of C#. The integration exports methods, such as `addNuxtApp`, that appear in the generated SDK of a consuming AppHost, just like the methods of a C# integration. Under the hood, Aspire runs your integration in its own Node.js process and routes each call to it, so your code configures the same resource model as a C# integration. + +:::caution[Experimental] +Hosting integrations written in TypeScript are experimental and disabled by default. AppHosts that consume them must opt in, and the authoring APIs might change in future releases. +::: + +To make a C# integration available to TypeScript AppHosts instead, see [Multi-language integrations](/extensibility/multi-language-integration-authoring/). + +## Choose a library or an exported integration + +You can share TypeScript AppHost code in two ways: + +- **Plain library**: An npm package that exports ordinary functions, such as `addKafka(builder, ...)`. A TypeScript AppHost imports and calls them directly. No opt-in is required, but the functions aren't added to the builder and AppHosts in other languages can't use them. +- **Exported integration**: A package that marks its functions with `AspireExport` and runs as an integration host. Consuming AppHosts get fluent builder methods, such as `builder.addNuxtApp(...)`, in their generated SDK. This page describes this option. + +## Author an integration + +An integration is a library package, not an app. It has its own _aspire.config.json_ so that `aspire restore` can generate the typed Aspire SDK that your code builds on, and an entry point that starts the integration host. + + + +1. Create a package with an _aspire.config.json_ file that declares the TypeScript language and the hosting packages your integration uses. Don't set an AppHost path: + + ```json title="aspire.config.json" + { + "appHost": { + "language": "typescript/nodejs" + }, + "packages": { + "Aspire.Hosting.JavaScript": "" + } + } + ``` + +1. Add a _package.json_ file. Aspire starts the integration host with `node --import tsx`, so include `tsx` as a dependency: + + ```json title="package.json" + { + "name": "@contoso/aspire-nuxt", + "version": "0.1.0", + "type": "module", + "dependencies": { + "tsx": "^4.21.0", + "vscode-jsonrpc": "8.2.1" + } + } + ``` + +1. Run `aspire restore` in the package directory. It generates the SDK in _.aspire/modules/_, including the `AspireExport`, `defineIntegration`, and `runIntegrationHost` helpers. + +1. Write your integration. Wrap each method with `AspireExport` and use the generated builder APIs to configure resources. The `projection` describes the method's target, parameters, and return type so that consuming AppHosts can generate a typed method for it. The `typeId` of each Aspire type matches the handle types in the generated _.aspire/modules/aspire.mts_ file. Finally, group the methods with `defineIntegration`: + + ```typescript title="src/integration.ts" + import type { + DistributedApplicationBuilder, + JavaScriptAppResource, + } from '../.aspire/modules/aspire.mjs'; + import { + AspireExport, + defineIntegration, + type AspireTypeRef, + } from '../.aspire/modules/base.mjs'; + + const builderType: AspireTypeRef = { + typeId: 'Aspire.Hosting/Aspire.Hosting.IDistributedApplicationBuilder', + category: 'Handle', + isInterface: true, + }; + const appType: AspireTypeRef = { + typeId: 'Aspire.Hosting.JavaScript/Aspire.Hosting.JavaScript.JavaScriptAppResource', + category: 'Handle', + }; + const stringType: AspireTypeRef = { typeId: 'string', category: 'Primitive' }; + + interface AddNuxtAppArgs { + builder: DistributedApplicationBuilder; + name: string; + appDirectory: string; + } + + export const addNuxtApp = AspireExport( + { + id: '@contoso/aspire-nuxt/addNuxtApp', + method: 'addNuxtApp', + description: 'Adds a Nuxt application.', + projection: { + capabilityKind: 'Method', + targetTypeId: builderType.typeId, + targetType: builderType, + targetParameterName: 'builder', + returnsBuilder: true, + returnType: appType, + parameters: [ + { name: 'name', type: stringType }, + { name: 'appDirectory', type: stringType }, + ], + }, + }, + async ({ builder, name, appDirectory }) => { + return await builder.addJavaScriptApp(name, appDirectory, { runScriptName: 'dev' }) + .withHttpEndpoint({ env: 'PORT' }) + .withEnvironment('HOST', '0.0.0.0'); + }, + ); + + export default defineIntegration({ + name: 'NuxtIntegration', + capabilities: [addNuxtApp], + }); + ``` + + Give each method a unique `id`. Consuming AppHosts call the method by its `method` name. + +1. Add an entry point that starts the integration host: + + ```typescript title="src/host.ts" + import nuxtIntegration from './integration.js'; + import { runIntegrationHost } from '../.aspire/modules/integration-host.mjs'; + + await runIntegrationHost({ + packageName: '@contoso/aspire-nuxt', + integrations: [nuxtIntegration], + }); + ``` + + `runIntegrationHost` handles the connection to the AppHost, registration, and dispatching calls to your methods. + + + +To distribute the integration, compile it and publish or pack it as an npm package. Include the compiled output and the generated _.aspire/modules/_ SDK, as the preview [`@aspire/nuxt`](https://github.com/microsoft/aspire/tree/release/17.0/src/Aspire.Hosting.Nuxt) package does. + +## Consume an integration + + + +1. Enable the feature in the AppHost directory: + + ```bash title="Aspire CLI" + aspire config set features.experimentalHostingIntegrations true + ``` + + Without this setting, the CLI rejects AppHosts that reference npm hosting integrations and shows the command to enable them. Running the command adds the `features` setting shown in the next step to _aspire.config.json_. + +1. Install the integration package, and then add it to the `packages` section of the AppHost's _aspire.config.json_ file. Set `source` to `npm` and `path` to the integration's host entry point, relative to _aspire.config.json_: + + ```json title="aspire.config.json" + { + "appHost": { + "path": "apphost.mts", + "language": "typescript/nodejs" + }, + "features": { + "experimentalHostingIntegrations": true + }, + "packages": { + "Aspire.Hosting.JavaScript": "", + "@contoso/aspire-nuxt": { + "source": "npm", + "path": "./node_modules/@contoso/aspire-nuxt/dist/src/host.js" + } + } + } + ``` + + During development, `path` can also point to a TypeScript entry point in a local folder, such as `./nuxt-integration/src/host.ts`. + +1. Run `aspire restore`. The CLI installs the integration's dependencies, starts its host, and adds its methods to the generated SDK. + +1. Call the methods from your AppHost like any other builder method: + + ```typescript title="apphost.mts" + import { createBuilder } from './.aspire/modules/aspire.mjs'; + + const builder = await createBuilder(); + + const api = await builder.addJavaScriptApp('api', './api', { runScriptName: 'start' }) + .withHttpEndpoint({ env: 'PORT' }); + + await builder.addNuxtApp('web', './web') + .withReference(api) + .waitFor(api); + + await builder.build().run(); + ``` + + + +## Current limitations + +- TypeScript is the only supported language for authoring these integrations. +- You write the `projection` metadata for each method by hand. +- `aspire add` doesn't find npm integrations. Add them to _aspire.config.json_ manually. +- The preview `@aspire/nuxt` integration isn't published to npm. To try it, build and pack it from the [Aspire repository](https://github.com/microsoft/aspire/tree/release/17.0/src/Aspire.Hosting.Nuxt). +- If an integration host that registered callbacks stops unexpectedly, the AppHost stops and you need to start it again. + +## See also + +- [Multi-language integrations](/extensibility/multi-language-integration-authoring/): Export C# hosting integrations to TypeScript AppHosts. +- [TypeScript AppHost](/app-host/typescript-apphost/): Build an AppHost in TypeScript. +- [Custom resources](/extensibility/custom-resources/): Create custom resource types. diff --git a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx index f7802a78db..a3b63c7db7 100644 --- a/src/frontend/src/content/docs/fundamentals/external-parameters.mdx +++ b/src/frontend/src/content/docs/fundamentals/external-parameters.mdx @@ -367,7 +367,11 @@ The manifest representation is as follows: ## Optional parameters -By default, a parameter is required: if no value is configured, you're prompted for one when you run or publish the app, and publishing fails until a value is supplied. Some parameters don't need a value in every environment. Use `AsOptional` to mark a parameter as optional: +By default, a parameter is required: if no value is configured, you're prompted for one when you run or publish the app, and publishing fails until a value is supplied. An empty string doesn't satisfy a required parameter either, including secret and connection-string parameters. + +When a required value is missing or empty during `aspire run`, the parameter shows a `ValueMissing` state, and the dashboard asks you to supply the value. When the dashboard can't prompt, such as in publish or non-interactive runs, initialization fails with a `MissingParameterValueException` that names the parameter. + +Some parameters don't need a value in every environment. Use `AsOptional` to mark a parameter as optional: @@ -403,7 +407,9 @@ await builder.build().run(); -When an optional parameter has no configured value, you aren't prompted for it, and resources that depend on it don't wait for it. The parameter resolves to `null`, and a `null` value is omitted when it's used as an environment variable, so in the preceding example `MESSAGE_PREFIX` isn't set. If a value is configured, it's used just like a required parameter's value. +When an optional parameter has no configured value, you aren't prompted for it, and resources that depend on it don't wait for it. The parameter resolves to `null`, and a `null` value is omitted when it's used as an environment variable, so in the preceding example `MESSAGE_PREFIX` isn't set. If a value is configured, it's used just like a required parameter's value, and an explicitly configured empty string stays `""`. + +Mark a parameter optional only when an absent or empty value is genuinely valid for your app. Don't make required credentials optional to avoid the missing-value check.