aspire new command

Esta página aún no está disponible en tu idioma.

Name

aspire new - Create a new Aspire project or solution.

Synopsis

aspire new [command] [options]

Description

The aspire new command is the driver for creating Aspire projects, apps, or solutions, based on the Aspire templates. Each command specifies the template to use, and the options for the driver specify the options for the template.

This command defaults to interactive mode. When executed without any options, the command prompts you for the project template and version, name, and output folder. When the --name, --output, and --version options are provided, the command runs non-interactive and generates files based on the command template.

Default output directory

When you don’t provide --output, the default output directory is derived from the template name. For example, running aspire new aspire-starter without --output creates a directory named ./aspire-starter in the current working directory.

If that directory already exists and is non-empty, the command automatically appends a numeric suffix to find a unique name (for example, ./aspire-starter-2, ./aspire-starter-3, and so on).

Output path validation

The --output option validates the provided path before creating the project:

Paths that contain invalid characters (such as null bytes) are rejected with an error.
Paths that point to an existing non-empty directory are rejected with a clear error message. Use a different output path or an empty directory.

Interactive prompts

When running aspire new in interactive mode, the command asks one or more questions before generating the project. The available prompts depend on the template and options you provide.

Use *.dev.localhost URLs?

During project creation, you may be prompted:

Use *.dev.localhost URLs?

This prompt determines whether the generated launch profile configures your Aspire services to be accessible via *.dev.localhost wildcard subdomain URLs (for example, https://myservice.dev.localhost) instead of standard http://localhost with port numbers.

What are *.dev.localhost URLs?

*.dev.localhost is a wildcard subdomain pattern that resolves to your local machine (127.0.0.1 or ::1) in most modern browsers without additional DNS configuration. This resolution is a browser feature — non-browser HTTP clients (for example, curl, HttpClient, or other command-line tools) don’t automatically resolve *.dev.localhost subdomains and may require hosts file entries to reach them.

The Aspire developer certificate trusts *.dev.localhost subdomains, so browsers accept HTTPS connections to any subdomain when the certificate is trusted.

Yes — use *.dev.localhost URLs

Choosing Yes configures the generated project so that each service gets a unique subdomain URL such as https://myservice.dev.localhost. This option:

Enables HTTPS for all services from the start, leveraging the Aspire developer certificate.
Gives each service its own origin, which prevents cookie and authentication token collisions between services running on the same machine.
More closely mirrors a production setup where services are hosted on separate domains or subdomains.

Prerequisite: The Aspire developer certificate must be trusted on your machine. If you haven’t already done so, run:

aspire certs trust

Command reference: aspire certs trust

No — use standard localhost URLs (default)

Choosing No (the default) configures services with standard http://localhost:<port> addresses. This option requires no certificate setup and works in all browsers and tools without additional configuration.

Options

The following options are available:

-n, --name

The name of the project to create.
-o, --output

The output path for the project.
-s, --source

The NuGet source to use for the project templates.
-v, --version

The version of the project templates to use.
--channel

Channel to use for templates (stable, staging, daily). If you don’t specify --version, aspire new selects a template package from the channel and prefers the version that matches the currently installed CLI/SDK. For explicit pre-release channels, such as staging and daily, it pins templates to the installed CLI/SDK version when the feed would otherwise select a newer pre-release package. For example, a 13.4 CLI using --channel daily won’t pull 13.5 preview templates even if the daily feed contains them. If you specify --version, that template version is used with the selected channel.

When --channel is not specified, aspire new automatically uses the running CLI’s identity channel — the channel that matches the CLI build you have installed (for example, daily for a nightly build, staging for a release-candidate build, or a pr-<N> channel for a pull-request build). This ensures that the correct package feed is used to resolve Aspire.ProjectTemplates without requiring an explicit flag.

If the CLI’s identity does not match any registered explicit channel (for example, on a stable release or a locally-built CLI), aspire new falls back to ambient NuGet configuration (the implicit nuget.org channel).
--suppress-agent-init

Suppress the prompt to initialize MCP server configuration for agent environments after project creation.
-?, -h, --help

Prints help and usage documentation for the available commands and options.
-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.
--non-interactive

Run the command in non-interactive mode, disabling all interactive prompts and spinners.
--nologo

Suppress the startup banner and telemetry notice.
--banner

Display the animated Aspire CLI welcome banner.
--wait-for-debugger

Wait for a debugger to attach before running a command.

Commands

Each command represents a template. Pass the --help parameter to the template command to print the options available to the template.

Command	Template
`aspire-starter`	Starter App (ASP.NET Core/Blazor)
`aspire-ts-cs-starter`	Starter App (ASP.NET Core/React)
`aspire-py-starter`	Starter App (FastAPI/React)
`aspire-ts-starter`	Starter App (Express/React)
`aspire-empty`	Empty (C# AppHost)
`aspire-ts-empty`	Empty (TypeScript AppHost)

aspire-py-starter options

The aspire-py-starter template accepts the following additional options:

--use-redis-cache

Scaffold the template with an optional Redis cache resource in the TypeScript AppHost. Accepts true or false. Defaults to prompting interactively.
Aspire CLI
```
aspire new aspire-py-starter --use-redis-cache true
```

Examples

Create an Aspire solution from the template. Because the template was selected (aspire-starter), you’re prompted for the name, output folder, and template version.
Aspire CLI
```
aspire new aspire-starter
```
Create an AppHost project named aspireapp from the 13.3.0 templates and place the output in a folder named dev.
Aspire CLI
```
aspire new aspire-empty --version 13.3.0 --name aspireapp --output ./dev
```
Create an Aspire starter app using templates from the daily channel to get the latest pre-release templates.
Aspire CLI
```
aspire new aspire-starter --channel daily
```

Troubleshooting

Language support not found

When aspire new runs a template that requires code generation (for example, a TypeScript or Python AppHost template), it uses language support and code generator assemblies loaded by the apphost server. If those assemblies cannot load their types, the command may fail with an error such as:

No language support found for: typescript/nodejs. Available languages: go, java, python, rust.

Or, when no language support implementations are discovered at all:

No language support found for: typescript/nodejs. No language support implementations were discovered in any loaded assembly.
This usually indicates a binary mismatch between the bundled apphost server and the integration assemblies on disk;
check the apphost server log for 'LoaderExceptions' Warnings.

These errors mean the integration assemblies on disk are not compatible with the bundled apphost server. This typically happens after a partial NuGet cache update, a version skew between the CLI and the integration packages, or an interrupted restore.

To resolve:

Clear the Aspire CLI cache to remove stale cached assemblies:
Aspire CLI
```
aspire cache clear
```
Re-run aspire new to trigger a fresh restore of the integration packages.

If the error persists, check the apphost server log for Warning entries that include LoaderExceptions or mention a shared assembly version mismatch (for example, Aspire.TypeSystem bundled version vs. the version on disk). These log entries name the offending assembly and describe the mismatch, making it easier to identify which package version is out of sync.