Configuration

Complete reference for all Response Formatting configuration options.

---

ResponseFormattingOptions

Namespace: AspNetConventions.Configuration.Options
Accessed via: options.Response

Controls how successful and error responses are wrapped and formatted.

Disabling Response Formatting

builder.Services.AddControllers()
    .AddAspNetConventions(options =>
    {
        // All responses pass through as-is — no envelope wrapping
        options.Response.IsEnabled = false;
    });

Disabling Metadata

builder.Services.AddControllers()
    .AddAspNetConventions(options =>
    {
        // Responses will not include the "metadata" block
        options.Response.IncludeMetadata = false;

        // Responses will not include the "pagination" block
        options.Response.Pagination.IncludeMetadata = false;
    });

---

PaginationOptions

Namespace: AspNetConventions.Configuration.Options.Response
Accessed via: options.Response.Pagination

Controls how paginated and collection responses are formatted.

Example:

options.Response.Pagination.IncludeLinks = true;
options.Response.Pagination.IncludeNavigationFlags = true;
options.Response.Pagination.PageNumberParameterName = "p";
options.Response.Pagination.PageSizeParameterName = "size";
options.Response.Pagination.DefaultPageSize = 50;

---

ErrorResponseOptions

Namespace: AspNetConventions.Configuration.Options.Response
Accessed via: options.Response.ErrorResponse

Controls error-specific response formatting behaviour.

Example:

options.Response.ErrorResponse.DefaultErrorType = "INTERNAL_ERROR";
options.Response.ErrorResponse.DefaultErrorMessage = "Something went wrong.";
options.Response.ErrorResponse.DefaultValidationType = "INVALID_INPUT";
options.Response.ErrorResponse.DefaultValidationMessage = "Please check your input.";

// Include exception details (not recommended for production)
options.Response.ErrorResponse.IncludeExceptionDetails = true;
options.Response.ErrorResponse.MaxStackTraceDepth = 20;

// Allow specific ProblemDetails extensions
options.Response.ErrorResponse.AllowedProblemDetailsExtensions.Add("correlationId");
options.Response.ErrorResponse.AllowedProblemDetailsExtensions.Add("helpUrl");

Exception Details Behavior

The IncludeExceptionDetails property controls whether stack traces and inner exception information are included:

---

ResponseFormattingHooks

Namespace: AspNetConventions.Core.Hooks
Accessed via: options.Response.Hooks

Hooks provide fine-grained control over the response formatting pipeline. All hooks are asynchronous.

Examples - Skip wrapping for specific routes and logging response format:

options.Response.Hooks.ShouldWrapResponseAsync = async (apiResult, request) =>
{
    // Skip wrapping for health checks
    if (request.Path.StartsWith("/health"))
        return false;

    // Skip wrapping for metrics endpoints
    if (request.Path.StartsWith("/metrics"))
        return false;

    return true;
};

options.Response.Hooks.AfterResponseWrapAsync = async (wrappedResponse, apiResult, request) =>
{
    _logger.LogInformation(
        "Response: {Method} {Path} → {StatusCode}",
        request.Method,
        request.Path,
        (int)apiResult.StatusCode);
};

options.Response.Hooks.BeforeResponseWrapAsync = async (apiResult, request) =>
{
    // Add custom processing before wrapping
    if (!apiResult.IsSuccess)
    {
        // Log error responses
        _logger.LogWarning(
            "Error response: {Type} - {Message}",
            apiResult.Type,
            apiResult.Message);
    }
};

options.Response.Hooks.CustomizeMetadata = (metadata, request) =>
{
    // Add custom entries
    metadata["userId"] = request.UserId;

    // Remove a standard entry
    metadata.Remove(Metadata.PathKey);
};

ApiResult

Encapsulates the standard execution result structure for an HTTP request. This is the abstract base class for all API responses.

ApiResult<T>

The generic version adds type safety and is the recommended way to return responses in your controllers.

public sealed class ApiResult<TValue> : ApiResult

Implicit Conversions

ApiResult<T> can be implicitly converted to:

• ActionResult<T> — For MVC controller return types
• ActionResult — For non-generic action returns
• HttpApiResult<T> — For Minimal API endpoints

RequestDescriptor

Provides a comprehensive snapshot of the current HTTP request and its associated metadata within the application context. This class is useful for logging, error handling, and response formatting.

---

Default Values Reference