Myce.Response 1.5.1

Myce.Response

A lightweight and robust .NET library implementing the Result Pattern to standardize API responses, handle business logic flow, and manage complex messaging with frontend-driven internationalization support.

Supports net6.0, net7.0, net8.0, net9.0, and netstandard2.0.

Features

• Unified Result Envelope: Standardized Result and Result<T> classes for consistent API contracts.
• Rich Messaging System: Support for multiple message types (Information, Warning, Error).
• Dynamic Variable Interpolation: Messages support placeholders (using {} or []) for runtime data injection.
• Frontend-Ready i18n: Messages carry unique codes and variable dictionaries, allowing the frontend to handle translations.
• Lean Payloads: Internal logic properties are marked with [JsonIgnore] to keep JSON responses small and efficient.
• Smart Fallback: The Title property automatically defaults to the text of the first message if not explicitly set.
• Merge: Easily combine results between types while preserving messages.

Installation

dotnet add package Myce.Response

Usage

1. Basic Result

Use the Result class for operations that report status without returning a data payload.

public Result UpdateSystemSetting(string key, string value)
{
    if (string.IsNullOrEmpty(key))
        return Result.Failure(new ErrorMessage("KEY_REQUIRED", "Setting key is mandatory"));
 
    // Business logic execution...
    return Result.Success("Setting updated successfully");
}

2. Returning Data with Result

Use Result<T> to wrap the return value of your services.

public Result<User> GetUser(int id)
{
    var user = _repository.Find(id);
    
    if (user == null)
        return Result<User>.Failure(new ErrorMessage("USER_NOT_FOUND", "The requested user does not exist"));

    return Result<User>.Success(user);
}

3. Messaging with Variables (i18n Support)

Placeholders in messages allow the frontend to perform translation using a dictionary while maintaining dynamic context.

var message = new ErrorMessage("INSUFFICIENT_FUNDS", "You need at least {Required} to complete this, but you have {Current}");
message.AddVariable("Required", "50.00");
message.AddVariable("Current", "10.50");

return Result.Failure(message);

4. Backend-Driven Multilingual Messaging

You can store multiple translations directly within the message on the backend and resolve them dynamically using the .Show(language) method.

Option A: Using dictionaries (Bulk initialization)

var templates = new Dictionary<string, string>
{
    { "en-US", "The field {fieldName} must be today." },
    { "pt-BR", "O campo {fieldName} deve ser a data de hoje." }
};

var fieldTranslations = new Dictionary<string, string>
{
    { "en-US", "Birth Date" },
    { "pt-BR", "Data de Nascimento" }
};

var message = new ErrorMessage("DATETIME_IS_TODAY", templates);
message.AddVariableMultilingual("fieldName", fieldTranslations);

// Resolve dynamically based on the client's language
string enOutput = message.Show("en-US"); // "The field Birth Date must be today."
string ptOutput = message.Show("pt-BR"); // "O campo Data de Nascimento deve ser a data de hoje."

Option B: Incremental configuration (Individual translations)

var message = new ErrorMessage(MessageType.Error);
message.Code = "INVALID_FIELD";

// Add text templates individually
message.AddTextTranslation("en-US", "The {fieldName} is invalid.");
message.AddTextTranslation("pt-BR", "O {fieldName} é inválido.");

// Add variable translations individually
message.AddVariableTranslation("fieldName", "en-US", "Email Address");
message.AddVariableTranslation("fieldName", "pt-BR", "Endereço de E-mail");

string result = message.Show("pt-BR"); // "O Endereço de E-mail é inválido."

Architecture

The Result Object

• Title: (string) A high-level summary. If null, it returns Messages.FirstOrDefault()?.Text.
• IsSuccess: (bool) Returns true only if no ErrorMessage is present.
• Messages: (IReadOnlyCollection) A list of Information, Warning, or Error objects.
• Data: (T) The generic payload (specific to Result<T>).

Message Types

1. InformationMessage: Used for non-critical status updates.
2. WarningMessage: Used for alerts that do not block the operation.
3. ErrorMessage: Critical failures. Presence of this type makes IsValid return false.

Frontend Integration (Internationalization)

This library follows a Client-Side Translation strategy. The backend provides the structural data, and the frontend applies the locale based on the Code.

Best Practices

1. Explicit Titles: Set the Title property when you want a specific summary for the UI that differs from individual error messages.
2. ToResult Mapping: Use .ToResult<V>(map) to convert between types (e.g., Entity to DTO) while preserving all messages and state.

Notes

Version 1.5.0

• Add internationalization support for Message class.

Version 1.3.0

• Remove obsolete attribute IsValid (was replaced by IsSuccess).

Version 1.2.0

• Introduces support for net10.0, ensuring compatibility with the latest .NET features and improvements.

Version 1.0.0

• The initial stable release of Myce.Response, providing basic response handling capabilities for .NET applications.