Oakrey.Applications.UserPrompts 1.0.0

Oakrey.Applications.UserPrompts.Abstractions

A lightweight .NET library providing abstractions for user prompts and dialogs. This package enables decoupled, testable, and async-friendly user interaction patterns with support for dependency injection and strongly-typed results.

Features

Decoupled User Interaction

• IUserPrompter Interface: Define user prompts without tight coupling to UI implementations
• IUserPromptBus: Queue-based prompt handling for advanced scenarios
• Testability: Mock user interactions easily in unit tests

Rich Prompt Types

• Questions: Yes/No and Ok/Cancel prompts with strongly-typed results
• Information: Display info, warnings, errors, and success messages
• Input: Collect string input from users
• Selection: Present users with a list of options to choose from

Async/Await Support

All prompt methods are fully async, preventing UI blocking and enabling modern async patterns.

Strongly-Typed Results

• Result enum for button-based prompts (Yes, No, Ok, Cancel, Closed)
• InputPromptResult for text input with validation
• IPromptResult<T> for type-safe selection results

Extensibility

Create custom prompt types by implementing IPrompt and extending the bus architecture.

Installation

You can install the package via NuGet Package Manager, Package Manager Console or the .NET CLI.

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution....
3. Search for Oakrey.Applications.UserPrompts.Abstractions and click Install.

.NET CLI

Run the following command in your terminal:

dotnet add package Oakrey.Applications.UserPrompts.Abstractions

Package Manager Console

Run the following command in your Package Manager Console:

Install-Package Oakrey.Applications.UserPrompts.Abstractions

Usage Examples

Basic Setup with Dependency Injection

using Oakrey.Applications.UserPrompts;
using Microsoft.Extensions.DependencyInjection;

// Register the user prompter in your DI container
services.AddSingleton<IUserPrompter<MyService>, UserPrompter<MyService>>();
services.AddSingleton<IUserPromptBus, CustomUserPromptService>(); // or your implementation

Asking Yes/No Questions

public class MyService
{
    private readonly IUserPrompter<MyService> _prompter;

    public MyService(IUserPrompter<MyService> prompter)
    {
        _prompter = prompter;
    }

    public async Task DeleteFileAsync(string filePath)
    {
        var result = await _prompter.AskYesOrNoAsync(
            "Confirm Delete", 
            $"Are you sure you want to delete {filePath}?");

        if (result == Result.Yes)
        {
            // Proceed with deletion
            File.Delete(filePath);
        }
    }
}

Displaying Information Messages

public async Task ProcessDataAsync()
{
    try
    {
        // Process data...
        await _prompter.SuccessAsync("Success", "Data processed successfully!");
    }
    catch (Exception ex)
    {
        await _prompter.ErrorAsync("Error", $"Failed to process data: {ex.Message}");
    }
}

Getting User Input

public async Task RenameFileAsync(string currentName)
{
    var result = await _prompter.AskForStringAsync(
        "Rename File", 
        "Enter the new file name:");

    if (result.Result == Result.Ok && !string.IsNullOrWhiteSpace(result.Value))
    {
        // Rename the file
        File.Move(currentName, result.Value);
    }
}

Presenting Selection Options

public async Task SelectExportFormatAsync()
{
    var formats = new[] { "PDF", "Excel", "CSV", "JSON" };
    
    var result = await _prompter.AskForSelectionAsync(
        "Export Format", 
        "Select the export format:", 
        formats);

    if (result.Result == Result.Ok && result.Value != null)
    {
        await ExportDataAsync(result.Value);
    }
}

Creating Custom Prompts

using Oakrey.Applications.UserPrompts.Prompts;

// Define a custom prompt
public class CustomPrompt : PromptBase
{
    public CustomPrompt(string title, string message, string extraData) 
        : base(title, message)
    {
        ExtraData = extraData;
    }

    public string ExtraData { get; }
}

// Handle it in your prompt bus implementation
protected override Task<IPromptResult> Show(IPrompt request)
{
    return request switch
    {
        CustomPrompt customPrompt => ShowCustomDialog(customPrompt),
        _ => base.Show(request)
    };
}

Testing with Mock Prompter

public class MockUserPrompter : IUserPrompter<MyService>
{
    public Task<Result> AskYesOrNoAsync(string title, string message, CancellationToken ct = default)
        => Task.FromResult(Result.Yes); // Always return Yes for tests

    public Task<InputPromptResult> AskForStringAsync(string title, string message, CancellationToken ct = default)
        => Task.FromResult(InputPromptResult.Ok("Test Input"));

    // Implement other methods...
}

// In your tests
[Fact]
public async Task DeleteFile_WhenUserConfirms_DeletesFile()
{
    var mockPrompter = new MockUserPrompter();
    var service = new MyService(mockPrompter);
    
    await service.DeleteFileAsync("test.txt");
    
    // Assert file was deleted
}

Available Prompt Types

IUserPrompter Methods

Result Enum Values

• Ok - User clicked OK
• Cancel - User clicked Cancel
• Yes - User clicked Yes
• No - User clicked No
• Closed - Dialog was closed without selection

Requirements

• .NET 10 or higher

Implementation Packages

This is an abstractions package. To actually display prompts, you need an implementation package:

• Oakrey.Applications.UserPrompts.Windows - Standard Windows MessageBox implementation
• Oakrey.Applications.UserPrompts.Custom - Custom WPF dialogs with enhanced styling

Project Information

• Author: Oakrey
• Company: Oakrey
• License: MIT
• Repository: Git Repository
• Project URL: Project Website

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

License

This project is licensed under the MIT License. See the LICENSE file for details.