Services

This page lists the types you throw, inherit, or import when you work with DevKit’s exception model. The pipeline that catches them and exposes Result is automatic; see Introduction for the narrative and Tutorials for patterns.

ManagedException and ValidationException

ManagedException is the abstract base for localized and plain-string managed errors. ValidationException is thrown by the validation pipeline when data annotations or FluentValidation fail before your command handler runs.

• ManagedException — CodeBlock.DevKit.Core.Exceptions (includes MessagePlaceholder and MessagePlaceholderType).

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

using CodeBlock.DevKit.Core.Extensions;

namespace CodeBlock.DevKit.Core.Exceptions;

/// <summary>
/// Base exception class for managed application errors with support for localized messages.
/// Provides structured error handling with resource keys and placeholder values for internationalization.
/// </summary>

public abstract class ManagedException : Exception
{
    public string MessageResourceKey { get; }
    public Type MessageResourceType { get; }
    public IEnumerable<MessagePlaceholder> MessagePlaceholders { get; }

    public ManagedException(string messageResourceKey, Type messageResourceType, IEnumerable<MessagePlaceholder> messagePlaceholders = null)
        : base()
    {
        MessageResourceKey = messageResourceKey;
        MessageResourceType = messageResourceType;
        MessagePlaceholders = messagePlaceholders ?? new List<MessagePlaceholder>();
    }

    public ManagedException()
    {
        MessagePlaceholders = new List<MessagePlaceholder>();
    }

    public ManagedException(string message)
        : base(message)
    {
        MessagePlaceholders = new List<MessagePlaceholder>();
    }

    public bool HasResourceMessage()
    {
        return !MessageResourceKey.IsNullOrEmptyOrWhiteSpace() && MessageResourceType != null;
    }
}

/// <summary>
/// Represents a placeholder value for exception messages, supporting both plain text and localized resources.
/// Used to dynamically insert values into localized error messages.
/// </summary>
public class MessagePlaceholder
{
    private MessagePlaceholder(string plainText)
    {
        Type = MessagePlaceholderType.PlainText;
        PlainText = plainText;
    }

    private MessagePlaceholder(string resourceKey, Type resourceType)
    {
        Type = MessagePlaceholderType.Resource;
        ResourceKey = resourceKey;
        ResourceType = resourceType;
    }

    public static MessagePlaceholder CreatePlainText(string plainText)
    {
        return new MessagePlaceholder(plainText);
    }

    public static MessagePlaceholder CreateResource(string resourceKey, Type resourceType)
    {
        return new MessagePlaceholder(resourceKey, resourceType);
    }

    public MessagePlaceholderType Type { get; }
    public string ResourceKey { get; }
    public Type ResourceType { get; }
    public string PlainText { get; }
}

/// <summary>
/// Defines the type of placeholder value in exception messages.
/// </summary>
public enum MessagePlaceholderType
{
    Resource,
    PlainText,
}

• ValidationException — CodeBlock.DevKit.Application.Exceptions

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

using CodeBlock.DevKit.Core.Exceptions;

namespace CodeBlock.DevKit.Application.Exceptions;

/// <summary>
/// Exception thrown when validation errors occur during command or query processing.
/// Extends ManagedException to provide structured error handling for validation failures.
/// </summary>
public class ValidationException : ManagedException
{
    #region Ctors

    /// <summary>
    /// Initializes a new instance of ValidationException.
    /// </summary>

    public ValidationException()
        : base() { }

    #endregion
}

DomainException and ApplicationException

Throw these for expected failures: broken invariants (domain) or application rules such as “not found” (application). Both extend ManagedException. Use resource-based constructors in production so messages stay localized; ApplicationException lives in CodeBlock.DevKit.Application.Exceptions (not System.ApplicationException).

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

using CodeBlock.DevKit.Core.Exceptions;

namespace CodeBlock.DevKit.Domain.Exceptions;

/// <summary>
/// Exception thrown when domain business rules or invariants are violated.
/// Extends ManagedException to provide localized error messages and structured error handling.
/// </summary>
public class DomainException : ManagedException
{
    /// <summary>
    /// Initializes a new instance of DomainException with localized message support.
    /// </summary>
    /// <param name="messageResourceKey">Resource key for the localized error message.</param>
    /// <param name="messageResourceType">Type containing the resource definitions.</param>
    /// <param name="messagePlaceholders">Optional placeholders for dynamic message content.</param>

    public DomainException(string messageResourceKey, Type messageResourceType, IEnumerable<MessagePlaceholder> messagePlaceholders = null)
        : base(messageResourceKey, messageResourceType, messagePlaceholders) { }

    /// <summary>
    /// Initializes a new instance of DomainException with a plain text message.
    /// </summary>
    /// <param name="message">Plain text error message.</param>

    public DomainException(string message)
        : base(message) { }
}

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

using CodeBlock.DevKit.Core.Exceptions;

namespace CodeBlock.DevKit.Application.Exceptions;

/// <summary>
/// Exception thrown when application-level errors occur during command or query processing.
/// Extends ManagedException to provide localized error messages and structured error handling.
/// </summary>
public class ApplicationException : ManagedException
{
    /// <summary>
    /// Initializes a new instance of ApplicationException with localized message support.
    /// </summary>
    /// <param name="messageResourceKey">Resource key for the localized error message.</param>
    /// <param name="messageResourceType">Type containing the resource definitions.</param>
    /// <param name="messagePlaceholders">Optional placeholders for dynamic message content.</param>

    public ApplicationException(string messageResourceKey, Type messageResourceType, IEnumerable<MessagePlaceholder> messagePlaceholders = null)
        : base(messageResourceKey, messageResourceType, messagePlaceholders) { }

    /// <summary>
    /// Initializes a new instance of ApplicationException with a plain text message.
    /// </summary>
    /// <param name="message">Plain text error message.</param>

    public ApplicationException(string message)
        : base(message) { }
}

Dispatcher, notifications, and Result

IRequestDispatcher (implemented by MediatRDispatcher) cooperates with INotificationService to collect messages and return Result.Failure with Errors populated. For injectable contracts and typical usage, see General services.