|
| 1 | +--- |
| 2 | +title: Custom HTTP commands in .NET Aspire |
| 3 | +description: Learn how to create custom HTTP commands in .NET Aspire. |
| 4 | +ms.date: 03/20/2025 |
| 5 | +ms.topic: how-to |
| 6 | +--- |
| 7 | + |
| 8 | +# Custom HTTP commands in .NET Aspire |
| 9 | + |
| 10 | +In .NET Aspire, you can add custom HTTP commands to resources using the `WithHttpCommand` API. This API extends existing functionality, where you can provide [custom resource commands](custom-resource-commands.md). This feature enables a command on a resource that sends an HTTP request to the specified endpoint and path. This is useful for scenarios such as triggering database migrations, clearing caches, or performing custom actions on resources through HTTP requests. |
| 11 | + |
| 12 | +## Add HTTP commands to a resource |
| 13 | + |
| 14 | +The available APIs provide extensive capabilities with numerous parameters to customize the HTTP command. To add an HTTP command to a resource, use the `WithHttpCommand` extension method on the resource builder. There are two overloads available: |
| 15 | + |
| 16 | +<!-- TODO: Replace with xref when available... --> |
| 17 | + |
| 18 | +```csharp |
| 19 | +public static IResourceBuilder<TResource> WithHttpCommand<TResource>( |
| 20 | + this IResourceBuilder<TResource> builder, |
| 21 | + string path, |
| 22 | + string displayName, |
| 23 | + [EndpointName] string? endpointName = null, |
| 24 | + HttpMethod? method = null, |
| 25 | + string? httpClientName = null, |
| 26 | + Func<HttpCommandRequestContext, Task>? configureRequest = null, |
| 27 | + Func<HttpCommandResultContext, Task<ExecuteCommandResult>>? getCommandResult = null, |
| 28 | + string? commandName = null, |
| 29 | + Func<UpdateCommandStateContext, ResourceCommandState>? updateState = null, |
| 30 | + string? displayDescription = null, |
| 31 | + string? confirmationMessage = null, |
| 32 | + string? iconName = null, |
| 33 | + IconVariant? iconVariant = null, |
| 34 | + bool isHighlighted = false) |
| 35 | + where TResource : IResourceWithEndpoints; |
| 36 | +``` |
| 37 | + |
| 38 | +The parameters are defined as follows: |
| 39 | + |
| 40 | +- `path`: The relative path for the HTTP request. |
| 41 | +- `displayName`: The name displayed in the [.NET Aspire dashboard](dashboard/overview.md). |
| 42 | +- `endpointName`: (Optional) The name of the endpoint to use for the HTTP request. |
| 43 | +- `method`: (Optional) The HTTP method to use (defaults to <xref:System.Net.Http.HttpMethod.Post?displayProperty=nameWithType>). |
| 44 | +- `httpClientName`: (Optional) The name of the HTTP client to use when creating it via <xref:System.Net.Http.IHttpClientFactory.CreateClient(System.String)?displayProperty=nameWithType>. |
| 45 | +- `configureRequest`: (Optional) A callback to be invoked to configure the HTTP request before it is sent. |
| 46 | +- `getCommandResult`: (Optional) A callback to be invoked after the HTTP response is received to determine the result of the command invocation. |
| 47 | +- `commandName`: (Optional) The unique identifier for the command. |
| 48 | +- `updateState`: (Optional) A callback that is used to update the command state. The callback is executed when the command's resource snapshot is updated. By default, the command is enabled when the resource is <xref:Aspire.Hosting.ApplicationModel.KnownResourceStates.Running?displayProperty=nameWithType>. |
| 49 | +- `displayDescription`: (Optional) A description displayed in the dashboard. Could be used as a tooltip and might be localized. |
| 50 | +- `confirmationMessage`: (Optional) When a confirmation message is specified, the UI prompts the user to confirm the execution of the command with an Ok/Cancel dialog. |
| 51 | +- `iconName`: (Optional) The name of the icon to display in the dashboard. The icon is optional, but when you do provide it, it should be a valid [Fluent UI Blazor icon name](https://www.fluentui-blazor.net/Icon#explorer). |
| 52 | +- `iconVariant`: (Optional) The variant of the icon to display in the dashboard, valid options are `Regular` (default) or `Filled`. |
| 53 | +- `isHighlighted`: (Optional) Indicates whether the command is highlighted in the dashboard. |
| 54 | + |
| 55 | +```csharp |
| 56 | +public static IResourceBuilder<TResource> WithHttpCommand<TResource>( |
| 57 | + this IResourceBuilder<TResource> builder, |
| 58 | + string path, |
| 59 | + string displayName, |
| 60 | + Func<EndpointReference>? endpointSelector, |
| 61 | + HttpMethod? method = null, |
| 62 | + string? httpClientName = null, |
| 63 | + Func<HttpCommandRequestContext, Task>? configureRequest = null, |
| 64 | + Func<HttpCommandResultContext, Task<ExecuteCommandResult>>? getCommandResult = null, |
| 65 | + string? commandName = null, |
| 66 | + Func<UpdateCommandStateContext, ResourceCommandState>? updateState = null, |
| 67 | + string? displayDescription = null, |
| 68 | + string? confirmationMessage = null, |
| 69 | + string? iconName = null, |
| 70 | + IconVariant? iconVariant = null, |
| 71 | + bool isHighlighted = false) |
| 72 | + where TResource : IResourceWithEndpoints; |
| 73 | +``` |
| 74 | + |
| 75 | +The parameters are defined as follows: |
| 76 | + |
| 77 | +- `path`: The relative path for the HTTP request. |
| 78 | +- `displayName`: The name displayed in the [.NET Aspire dashboard](dashboard/overview.md). |
| 79 | +- `endpointSelector`: (Optional) A callback that selects the HTTP endpoint to send the request to when the command is invoked. |
| 80 | +- `method`: (Optional) The HTTP method to use (defaults to <xref:System.Net.Http.HttpMethod.Post?displayProperty=nameWithType>). |
| 81 | +- `httpClientName`: (Optional) The name of the HTTP client to use when creating it via <xref:System.Net.Http.IHttpClientFactory.CreateClient(System.String)?displayProperty=nameWithType>. |
| 82 | +- `configureRequest`: (Optional) A callback to be invoked to configure the HTTP request before it is sent. |
| 83 | +- `getCommandResult`: (Optional) A callback to be invoked after the HTTP response is received to determine the result of the command invocation. |
| 84 | +- `commandName`: (Optional) The unique identifier for the command. |
| 85 | +- `updateState`: (Optional) A callback that is used to update the command state. The callback is executed when the command's resource snapshot is updated. By default, the command is enabled when the resource is <xref:Aspire.Hosting.ApplicationModel.KnownResourceStates.Running?displayProperty=nameWithType>. |
| 86 | +- `displayDescription`: (Optional) A description displayed in the dashboard. Could be used as a tooltip and might be localized. |
| 87 | +- `confirmationMessage`: (Optional) When a confirmation message is specified, the UI prompts the user to confirm the execution of the command with an Ok/Cancel dialog. |
| 88 | +- `iconName`: (Optional) The name of the icon to display in the dashboard. The icon is optional, but when you do provide it, it should be a valid [Fluent UI Blazor icon name](https://www.fluentui-blazor.net/Icon#explorer). |
| 89 | +- `iconVariant`: (Optional) The variant of the icon to display in the dashboard, valid options are `Regular` (default) or `Filled`. |
| 90 | +- `isHighlighted`: (Optional) Indicates whether the command is highlighted in the dashboard. |
| 91 | + |
| 92 | +## See also |
| 93 | + |
| 94 | +- [Custom resource commands in .NET Aspire](custom-resource-commands.md) |
0 commit comments