diff --git a/src/frontend/config/sidebar/docs.topics.ts b/src/frontend/config/sidebar/docs.topics.ts index ddea6badb..4270f1ca3 100644 --- a/src/frontend/config/sidebar/docs.topics.ts +++ b/src/frontend/config/sidebar/docs.topics.ts @@ -885,6 +885,10 @@ export const docsTopics: StarlightSidebarTopicsUserConfig = { label: 'Executable resources', slug: 'app-host/executable-resources', }, + { + label: '.NET tool resources', + slug: 'app-host/dotnet-tool-resources', + }, { label: 'Migrate from Docker Compose', translations: { diff --git a/src/frontend/src/content/docs/app-host/dotnet-tool-resources.mdx b/src/frontend/src/content/docs/app-host/dotnet-tool-resources.mdx new file mode 100644 index 000000000..dc0ac888d --- /dev/null +++ b/src/frontend/src/content/docs/app-host/dotnet-tool-resources.mdx @@ -0,0 +1,207 @@ +--- +title: Host .NET tools in Aspire +description: Learn how to use DotnetToolResource and AddDotnetTool to run .NET CLI tools as resources in your Aspire AppHost. +--- + +import { Aside, Steps } from '@astrojs/starlight/components'; + +In Aspire, you can host .NET CLI tools as resources in your application using the `AddDotnetTool` method. This feature enables you to run tools like `dotnet-ef`, `dotnet-dump`, `dotnet-trace`, and other NuGet-distributed CLI tools as part of your distributed application. + + + +## When to use dotnet tool resources + +Use dotnet tool resources when you need to: + +- Run .NET CLI tools that are distributed as NuGet packages. +- Integrate database migration tools like Entity Framework Core CLI (`dotnet-ef`). +- Execute diagnostic tools such as `dotnet-dump`, `dotnet-trace`, or `dotnet-counters`. +- Run code generators or analysis tools as part of your development workflow. + +## Prerequisites + +Before using dotnet tool resources, ensure you have: + +- **.NET 10 SDK** or later installed. +- The tool's working directory must **not** be in the context of a `global.json` file that forces an older SDK version. + +## Basic usage + +The `AddDotnetTool` method requires a resource name and the NuGet package ID of the tool: + +```csharp title="AppHost.cs" +#pragma warning disable ASPIREDOTNETTOOL +var builder = DistributedApplication.CreateBuilder(args); + +// Add Entity Framework Core CLI tool +var efTool = builder.AddDotnetTool("ef", "dotnet-ef"); + +builder.Build().Run(); +#pragma warning restore ASPIREDOTNETTOOL +``` + +This example adds the Entity Framework Core CLI tool as a resource. When the AppHost runs, Aspire executes `dotnet tool exec dotnet-ef` to run the tool. + +## Passing arguments to tools + +Use the `WithArgs` method to pass command-line arguments to the tool: + +```csharp title="AppHost.cs" +#pragma warning disable ASPIREDOTNETTOOL +var builder = DistributedApplication.CreateBuilder(args); + +// Run dotnet-ef with migrations list command +var efTool = builder.AddDotnetTool("ef", "dotnet-ef") + .WithArgs("migrations", "list"); + +builder.Build().Run(); +#pragma warning restore ASPIREDOTNETTOOL +``` + +## Configure tool versions + +By default, the latest stable version of the tool is used. You can specify a particular version or allow prerelease versions. + +### Specify a version + +Use `WithToolVersion` to pin to a specific version: + +```csharp title="AppHost.cs" +var efTool = builder.AddDotnetTool("ef", "dotnet-ef") + .WithToolVersion("9.0.1"); +``` + +You can also use wildcard versions to get the latest patch: + +```csharp title="AppHost.cs" +var efTool = builder.AddDotnetTool("ef", "dotnet-ef") + .WithToolVersion("10.0.*"); +``` + +### Allow prerelease versions + +Use `WithToolPrerelease` to allow prerelease versions of the tool: + +```csharp title="AppHost.cs" +var efTool = builder.AddDotnetTool("ef", "dotnet-ef") + .WithToolPrerelease(); +``` + +## Configure package sources + +By default, tools are acquired from configured NuGet feeds. You can add additional sources or configure the tool to use only specific sources. + +### Add a package source + +Use `WithToolSource` to add a NuGet package source: + +```csharp title="AppHost.cs" +var tool = builder.AddDotnetTool("my-tool", "my-custom-tool") + .WithToolSource("https://my-private-feed.example.com/nuget/v3/index.json"); +``` + +### Use only specified sources + +Use `WithToolIgnoreExistingFeeds` to ignore the existing NuGet configuration and use only the sources you specify: + +```csharp title="AppHost.cs" +var tool = builder.AddDotnetTool("my-tool", "my-custom-tool") + .WithToolSource("./local-packages") + .WithToolIgnoreExistingFeeds(); +``` + +### Ignore failed sources + +Use `WithToolIgnoreFailedSources` to treat package source failures as warnings rather than errors: + +```csharp title="AppHost.cs" +var tool = builder.AddDotnetTool("my-tool", "my-custom-tool") + .WithToolIgnoreFailedSources(); +``` + +## Practical example: Database migrations + +Here's a complete example using Entity Framework Core CLI to run database migrations: + +```csharp title="AppHost.cs" +#pragma warning disable ASPIREDOTNETTOOL + +var builder = DistributedApplication.CreateBuilder(args); + +// Add PostgreSQL database +var postgres = builder.AddPostgres("postgres") + .AddDatabase("appdb"); + +// Add the API project that contains the DbContext +var api = builder.AddProject("api") + .WithReference(postgres); + +// Add EF Core tool for migrations +var efMigrations = builder.AddDotnetTool("ef-migrate", "dotnet-ef") + .WithArgs("database", "update", "--project", "../Api") + .WithReference(postgres) + .WaitFor(postgres); + +builder.Build().Run(); + +#pragma warning restore ASPIREDOTNETTOOL +``` + +## Dashboard integration + +Dotnet tool resources appear in the Aspire Dashboard with a dedicated resource type, allowing you to filter and view tools separately from other resources. The dashboard displays tool-specific properties including: + +- **Package**: The NuGet package ID of the tool. +- **Version**: The version of the tool being used (if specified). +- **Source**: The package source from which the tool was acquired. + +## Extension methods reference + +| Method | Description | +|--------|-------------| +| `AddDotnetTool(name, packageId)` | Adds a .NET tool resource with the specified name and NuGet package ID. | +| `WithToolVersion(version)` | Sets the package version for the tool. Supports wildcards like `10.0.*`. | +| `WithToolPrerelease()` | Allows prerelease versions of the tool to be used. | +| `WithToolSource(source)` | Adds a NuGet package source for tool acquisition. | +| `WithToolIgnoreExistingFeeds()` | Configures the tool to use only specified package sources. | +| `WithToolIgnoreFailedSources()` | Treats package source failures as warnings. | + +## Known limitations + + + +## Suppress the experimental warning + +Since the dotnet tool APIs are experimental, you need to suppress the `ASPIREDOTNETTOOL` warning to use them. + +### Suppress in code + +```csharp title="Suppress in code" +#pragma warning disable ASPIREDOTNETTOOL +var tool = builder.AddDotnetTool("my-tool", "dotnet-tool-package"); +#pragma warning restore ASPIREDOTNETTOOL +``` + +### Suppress in project file + +```xml title="AppHost.csproj" + + $(NoWarn);ASPIREDOTNETTOOL + +``` + +## See also + +- [ASPIREDOTNETTOOL diagnostic](/diagnostics/aspiredotnettool/) +- [Executable resources](/app-host/executable-resources/) diff --git a/src/frontend/src/content/docs/diagnostics/aspiredotnettool.mdx b/src/frontend/src/content/docs/diagnostics/aspiredotnettool.mdx index fddcf8196..502467495 100644 --- a/src/frontend/src/content/docs/diagnostics/aspiredotnettool.mdx +++ b/src/frontend/src/content/docs/diagnostics/aspiredotnettool.mdx @@ -41,4 +41,5 @@ Or in your project file: ## See also +- [.NET tool resources](/app-host/dotnet-tool-resources/) - Learn about hosting .NET CLI tools - [Executables](/get-started/app-host/#add-executable-resource) - Learn about executable resources