Interaction Service (Preview)

The interaction service (Aspire.Hosting.IInteractionService) allows you to prompt users for input, request confirmation, and display messages. The interaction service works in two different contexts:

• Aspire dashboard: When running aspire run or launching the app host directly, interactions appear as dialogs and notifications in the dashboard UI.
• Aspire CLI: When running aspire publish or aspire deploy, interactions are prompted through the command-line interface.

This is useful for scenarios where you need to gather information from the user or provide feedback on the status of operations, regardless of how the application is being launched or deployed.

The IInteractionService API

The IInteractionService interface is retrieved from the DistributedApplication dependency injection container. IInteractionService can be injected into types created from DI or resolved from IServiceProvider, which is usually available on a context argument passed to events.

When you request IInteractionService, be sure to check if it's available for usage. If you attempt to use the interaction service when it's not available (IInteractionService.IsAvailable returns false), an exception is thrown.

var interactionService = serviceProvider.GetRequiredService<IInteractionService>();
if (interactionService.IsAvailable)
{
    var result = await interactionService.PromptConfirmationAsync(
        title: "Delete confirmation",
        message: "Are you sure you want to delete the data?");
        
    if (result.Data)
    {
        // Run your resource/command logic.
    }
}

The interaction service has several methods that you use to interact with users or display messages. The behavior of these methods depends on the execution context:

• Dashboard context (aspire run or direct app host launch): Interactions appear as modal dialogs, notifications, and form inputs in the Aspire dashboard web interface.
• CLI context (aspire publish or aspire deploy): Interactions are prompted through the command-line interface with text-based prompts and responses.

The following sections describe how to use these APIs effectively in both contexts:

Where to use the interaction service

Any of the available callback-based extension methods of IResourceBuilder<T> can use the interaction service to prompt users for input or confirmation. Use the interaction service in these scenarios:

• Custom resource types: Gather input from users or confirm actions when you create custom resource types.

  Resource types are free to define dashboard interactions, such as prompting for user input or displaying messages. The interaction service allows you to create a more interactive experience for users when they manage resources in the Aspire dashboard or CLI. For more information, see Create custom .NET Aspire hosting integrations.

• Custom resource commands: Add commands to resources in the Aspire dashboard or CLI. Use the interaction service to prompt users for input or confirmation when these commands run.

  When you chain a call to WithCommand on a target IResourceBuilder<T>, for example, your callback can use the interaction service to gather input or confirm actions. For more information, see Custom resource commands in .NET Aspire.

• Publish and deploy workflows: During aspire publish or aspire deploy operations, use the interaction service to gather deployment-specific configuration and confirm destructive operations through the CLI.

These approaches help you create interactive, user-friendly experiences for local development, dashboard interactions, and deployment workflows.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddFakeResource("fake-resource")
       .WithCommand("msg-dialog", "Example Message Dialog", async context =>
{
    var interactionService = context.GetRequiredService<IInteractionService>();
    
    // Use interaction service...

    return CommandResults.Success();
});

Display messages

There are several ways to display messages to the user:

• Dialog messages: Show important information in a dialog box.
• Notification messages: Display less critical information in a notification.

Display a dialog message box

Dialog messages provide important information that requires user attention.

The IInteractionService.PromptMessageBoxAsync method displays a message with customizable response options.

var interactionService = context.ServiceProvider.GetRequiredService<IInteractionService>();

var result = await interactionService.PromptMessageBoxAsync(
    "Simple Message Box: Example",
    """
    ##### 🤓 Nice!

    It's worth noting that **Markdown** is _supported_
    (and demonstrated here) in the message body. Simply
    configure the options as:

    ```csharp
    var options = new MessageBoxInteractionOptions
    {
        EnableMessageMarkdown = true,
        // Other options...
    };
    ```

    Cool, [📖 learn more](https://learn.microsoft.com/dotnet/aspire/extensibility/interaction-service)...
    """,
    new MessageBoxInteractionOptions
    {
        EnableMessageMarkdown = true,
        PrimaryButtonText = "Awesome"
    }
);

if (result.Canceled)
{
    return CommandResults.Failure("User cancelled.");
}

return result.Data
    ? CommandResults.Success()
    : CommandResults.Failure("The user doesn't like the example");

Dashboard view:

CLI view:

The PromptMessageBoxAsync method only works in the dashboard context. If you call it during aspire publish or aspire deploy, the method throws an exception and doesn't display a message in the CLI.

Display a notification message

Notification messages provide non-modal notifications.

The IInteractionService.PromptNotificationAsync method displays informational messages with optional action links in the dashboard context. You don't have to await the result of a notification message if you don't need to. This is especially useful for notifications, since you might want to display a notification and continue without waiting for user to dismiss it.

var interactionService = context.ServiceProvider.GetRequiredService<IInteractionService>();

// Demonstrating various notification types with different intents
var tasks = new List<Task>
{
    interactionService.PromptNotificationAsync(
        title: "Confirmation",
        message: "Are you sure you want to proceed?",
        options: new NotificationInteractionOptions
        {
            Intent = MessageIntent.Confirmation
        }),
    interactionService.PromptNotificationAsync(
        title: "Success",
        message: "Your operation completed successfully.",
        options: new NotificationInteractionOptions
        {
            Intent = MessageIntent.Success,
            LinkText = "View Details",
            LinkUrl = "https://learn.microsoft.com/dotnet/aspire/success"
        }),
    interactionService.PromptNotificationAsync(
        title: "Warning",
        message: "Your SSL certificate will expire soon.",
        options: new NotificationInteractionOptions
        {
            Intent = MessageIntent.Warning,
            LinkText = "Renew Certificate",
            LinkUrl = "https://portal.azure.com/certificates"
        }),
    interactionService.PromptNotificationAsync(
        title: "Information",
        message: "There is an update available for your application.",
        options: new NotificationInteractionOptions
        {
            Intent = MessageIntent.Information,
            LinkText = "Update Now",
            LinkUrl = "https://learn.microsoft.com/dotnet/aspire"
        }),
    interactionService.PromptNotificationAsync(
        title: "Error",
        message: "An error occurred while processing your request.",
        options: new NotificationInteractionOptions
        {
            Intent = MessageIntent.Error,
            LinkText = "Troubleshoot",
            LinkUrl = "https://learn.microsoft.com/dotnet/aspire/troubleshoot"
        })
};

await Task.WhenAll(tasks);

return CommandResults.Success();

The previous example demonstrates several ways to use the notification API. Each approach displays different types of notifications, all of which are invoked in parallel and displayed in the dashboard around the same time.

Dashboard view:

CLI view:

The PromptNotificationAsync method isn't available in CLI contexts. If you call it during aspire publish or aspire deploy, it throws an exception.

Prompt for user confirmation

Use the interaction service when you need the user to confirm an action before proceeding. The IInteractionService.PromptConfirmationAsync method displays a confirmation prompt in the dashboard context. Confirmation prompts are essential for destructive operations or actions that have significant consequences. They help prevent accidental actions and give users a chance to reconsider their decisions.

Prompt for confirmation before destructive operations

For operations that can't be undone, such as deleting resources, always prompt for confirmation:

var interactionService = context.ServiceProvider.GetRequiredService<IInteractionService>();        

// Prompt for confirmation before resetting database
var resetConfirmation = await interactionService.PromptConfirmationAsync(
    title: "Confirm Reset",
    message: "Are you sure you want to reset the `development-database`? This action **cannot** be undone.",
    options: new MessageBoxInteractionOptions
    {
        Intent = MessageIntent.Confirmation,
        PrimaryButtonText = "Reset",
        SecondaryButtonText = "Cancel",
        ShowSecondaryButton = true,
        EnableMessageMarkdown = true
    });

if (resetConfirmation.Data is true)
{
    // Perform the reset operation...

    return CommandResults.Success();
}
else
{
    return CommandResults.Failure("Database reset canceled by user.");
}

Dashboard view:

CLI view:

The PromptConfirmationAsync method isn't available in CLI contexts. If you call it during aspire publish or aspire deploy, the method throws an exception.

Prompt for user input

The interaction service API allows you to prompt users for input in various ways. You can collect single values or multiple values, with support for different input types including text, secrets, choices, booleans, and numbers. The presentation adapts automatically to the execution context.

Prompt the user for input values

You can prompt for a single value using the IInteractionService.PromptInputAsync method, or collect multiple pieces of information with IInteractionService.PromptInputsAsync. In the dashboard, multiple inputs appear together in a single dialog. In the CLI, each input is requested one after another.

Consider the following example, which prompts the user for multiple input values:

var interactionService = context.ServiceProvider.GetRequiredService<IInteractionService>();
var loggerService = context.ServiceProvider.GetRequiredService<ResourceLoggerService>();
var logger = loggerService.GetLogger(fakeResource);

var inputs = new List<InteractionInput>
{
    new()
    {
        Label = "Application Name",
        InputType = InputType.Text,
        Required = true,
        Placeholder = "my-app"
    },
    new()
    {
        Label = "Environment",
        InputType = InputType.Choice,
        Required = true,
        Options =
        [
            new("dev", "Development"),
            new("staging", "Staging"),
            new("test", "Testing")
        ]
    },
    new()
    {
        Label = "Instance Count",
        InputType = InputType.Number,
        Required = true,
        Placeholder = "1"
    },
    new()
    {
        Label = "Enable Monitoring",
        InputType = InputType.Boolean,
        Required = false
    }
};

var appConfigurationInput = await interactionService.PromptInputsAsync(
    title: "Application Configuration",
    message: "Configure your application deployment settings:",
    inputs: inputs);

if (!appConfigurationInput.Canceled)
{
    // Process the collected input values
    var appName = appConfigurationInput.Data[0].Value;
    var environment = appConfigurationInput.Data[1].Value;
    var instanceCount = int.Parse(appConfigurationInput.Data[2].Value ?? "1");
    var enableMonitoring = bool.Parse(appConfigurationInput.Data[3].Value ?? "false");

    logger.LogInformation("""
        Application Name: {AppName}
        Environment: {Environment}
        Instance Count: {InstanceCount}
        Monitoring Enabled: {EnableMonitoring}
        """,
        appName, environment, instanceCount, enableMonitoring);

    // Use the collected values as needed
    return CommandResults.Success();
}
else
{
    return CommandResults.Failure("User canceled application configuration input.");
}

Dashboard view:

This renders on the dashboard as shown in the following image:

Imagine you fill out the dialog with the following values:

After you select the Ok button, the resource logs display the following output:

CLI view:

In the CLI context, the same inputs are requested sequentially:

aspire deploy

Step 1: Analyzing model.

       ✓ DONE: Analyzing the distributed application model for publishing and deployment capabilities. 00:00:00
           Found 1 resources that support deployment. (FakeResource)

✅ COMPLETED: Analyzing model. completed successfully

═══════════════════════════════════════════════════════════════════════════════════════════════════════════════

Configure your application deployment settings:
Application Name: example-app
Environment:  Staging
Instance Count: 3
Enable Monitoring: [y/n] (n): y
✓ DEPLOY COMPLETED: Deploying completed successfully

Depending on the input type, the CLI might display additional prompts. For example, the Enable Monitoring input is a boolean choice, so the CLI prompts for a yes/no response. If you enter y, it enables monitoring; if you enter n, it disables monitoring. For the environment input, the CLI displays a list of available environments for selection:

Configure your application deployment settings:
Application Name: example-app
Environment:

> Development
  Staging
  Testing

(Type to search)

Input validation

Basic input validation is available by configuring InteractionInput. It provides options for requiring a value, or the maximum text length of Text or SecretText fields.

For complex scenarios, you can provide custom validation logic using the InputsDialogInteractionOptions.ValidationCallback property:

// Multiple inputs with custom validation
var databaseInputs = new List<InteractionInput>
{
    new()
    {
        Label = "Database Name",
        InputType = InputType.Text,
        Required = true,
        Placeholder = "myapp-db"
    },
    new()
    {
        Label = "Username",
        InputType = InputType.Text,
        Required = true,
        Placeholder = "admin"
    },
    new()
    {
        Label = "Password",
        InputType = InputType.SecretText,
        Required = true,
        Placeholder = "Enter a strong password"
    },
    new()
    {
        Label = "Confirm password",
        InputType = InputType.SecretText,
        Required = true,
        Placeholder = "Confirm your password"
    }
};

var validationOptions = new InputsDialogInteractionOptions
{
    ValidationCallback = async context =>
    {
        var passwordInput = context.Inputs.FirstOrDefault(i => i.Label == "Password");
        var confirmPasswordInput = context.Inputs.FirstOrDefault(i => i.Label == "Confirm password");

        // Validate password strength
        if (passwordInput?.Value is { Length: < 8 })
        {
            context.AddValidationError(passwordInput, "Password must be at least 8 characters long");
        }

        // Validate password confirmation
        if (passwordInput?.Value != confirmPasswordInput?.Value)
        {
            context.AddValidationError(confirmPasswordInput!, "Passwords do not match");
        }

        await Task.CompletedTask;
    }
};

var dbResult = await interactionService.PromptInputsAsync(
    title: "Database configuration",
    message: "Configure your PostgreSQL database connection:",
    inputs: databaseInputs,
    options: validationOptions);

if (!dbResult.Canceled && dbResult.Data != null)
{
    // Use the validated configuration
}

Prompting the user for a password and confirming they match is referred to as "dual independent verification" input. This approach is common in scenarios where you want to ensure the user enters the same password twice to avoid typos or mismatches.

Best practices for user input

When prompting for user input, consider these best practices:

1. Group related inputs: Use multiple input prompts to collect related configuration values. In the dashboard, these appear in a single dialog; in the CLI, they're requested sequentially but grouped conceptually.
2. Provide clear labels and placeholders: Help users understand what information is expected, regardless of context.
3. Use appropriate input types: Choose the right input type for the data you're collecting (secret for passwords, choice for predefined options, etc.). Both contexts support these input types appropriately.
4. Implement validation: Validate user input and provide clear error messages when validation fails. Both contexts support validation feedback.
5. Make required fields clear: Mark required fields and provide appropriate defaults for optional ones.
6. Handle cancellation: Always check if the user canceled the input prompt and handle it gracefully. Users can cancel in both dashboard and CLI contexts.

Interaction contexts

The interaction service behaves differently depending on how your Aspire solution is launched:

Dashboard context

When you run your application using aspire run or by directly launching the app host project, interactions appear in the Aspire dashboard web interface:

• Modal dialogs: Message boxes and input prompts appear as overlay dialogs that require user interaction.
• Notification messages: Informational messages appear as dismissible banners at the top of the dashboard.
• Rich UI: Full support for interactive form elements, validation, and visual feedback.
• All methods available: All interaction service methods are supported in dashboard contexts.

CLI context

When you run aspire publish or aspire deploy, interactions are prompted through the command-line interface:

• Text prompts: Only input prompts (PromptInputAsync and PromptInputsAsync) are available and appear as text-based prompts in the terminal.
• Sequential input: Multiple inputs are requested one at a time rather than in a single dialog.
• Limited functionality: Message boxes, notifications, and confirmation dialogs aren't available and throws exceptions if called.

See also

• Aspire.Hosting.IInteractionService
• .NET Aspire extensibility overview