Table of Contents

Services

Besides module-specific services (Subscription, Identity, and so on), CodeBlock DevKit registers general-purpose contracts you can inject from application services, use cases, Blazor components, or infrastructure code.

Each section below shows the namespace, a short description, and the full contract source via DocFX. For module interfaces (Identity, Subscription, Settings, and so on), see Dependency injection and the Modules documentation. For email and SMS, see Email service and SMS service.

IRequestDispatcher.cs

IRequestDispatcher is the façade your code uses to send BaseCommand and BaseQuery<T> instances through MediatR and receive Result / Result<T> without referencing the pipeline directly. Application services and use cases typically depend on this type so dispatch, validation behaviors, and INotificationService integration stay consistent.

  • Namespace: CodeBlock.DevKit.Application.Services
// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

using CodeBlock.DevKit.Application.Commands;
using CodeBlock.DevKit.Application.Queries;
using CodeBlock.DevKit.Core.Helpers;
using CodeBlock.DevKit.Domain.Events;

namespace CodeBlock.DevKit.Application.Services;

/// <summary>
/// Service interface for dispatching commands, queries, and domain events within the application.
/// Provides centralized request handling and event publishing capabilities.
/// </summary>
public interface IRequestDispatcher
{
    /// <summary>
    /// Sends a command for execution and returns the result.
    /// </summary>
    /// <typeparam name="TCommand">The type of command to execute.</typeparam>
    /// <param name="cmd">The command instance to execute.</param>
    /// <param name="cancellationToken">Optional cancellation token.</param>
    /// <returns>A task containing the command execution result.</returns>

    Task<Result<CommandResult>> SendCommand<TCommand>(TCommand cmd, CancellationToken cancellationToken = default)
        where TCommand : BaseCommand;

    /// <summary>
    /// Sends a query for execution and returns the result.
    /// </summary>
    /// <typeparam name="TQueryResult">The type of result returned by the query.</typeparam>
    /// <param name="query">The query instance to execute.</param>
    /// <param name="cancellationToken">Optional cancellation token.</param>
    /// <returns>A task containing the query result.</returns>

    Task<Result<TQueryResult>> SendQuery<TQueryResult>(BaseQuery<TQueryResult> query, CancellationToken cancellationToken = default);

    /// <summary>
    /// Publishes a domain event for handling by registered event handlers.
    /// </summary>
    /// <param name="event">The domain event to publish.</param>
    /// <param name="cancellationToken">Optional cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>

    Task PublishEvent(IDomainEvent @event, CancellationToken cancellationToken = default);
}

ICurrentUser.cs

ICurrentUser exposes the authenticated caller in a host-agnostic way: user id, name, email, roles, and permission helpers. Use it anywhere you need authorization or auditing context without reaching for HTTP types.

  • Namespace: CodeBlock.DevKit.Application.Services
// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

namespace CodeBlock.DevKit.Application.Services;

/// <summary>
/// Service interface for accessing current user information and permissions.
/// Provides user identity, roles, and permission checking capabilities.
/// </summary>
public interface ICurrentUser
{
    /// <summary>
    /// Determines whether the current user is authenticated.
    /// </summary>
    /// <returns>True if the user is authenticated; otherwise, false.</returns>

    bool IsAuthenticated();

    /// <summary>
    /// Gets the unique identifier of the current user.
    /// </summary>
    /// <returns>The user's unique identifier.</returns>

    string GetUserId();

    /// <summary>
    /// Gets the display name of the current user.
    /// </summary>
    /// <returns>The user's display name.</returns>

    string GetUserName();

    /// <summary>
    /// Gets the email address of the current user.
    /// </summary>
    /// <returns>The user's email address.</returns>

    string GetEmail();

    /// <summary>
    /// Gets all roles assigned to the current user.
    /// </summary>
    /// <returns>Collection of role names assigned to the user.</returns>

    IEnumerable<string> GetRoles();

    /// <summary>
    /// Checks if the current user is in the specified role.
    /// </summary>
    /// <param name="roleName">The name of the role to check.</param>
    /// <returns>True if the user is in the specified role; otherwise, false.</returns>

    bool IsInRole(string roleName);

    /// <summary>
    /// Checks if the current user has the specified permission.
    /// </summary>
    /// <param name="permission">The permission to check.</param>
    /// <returns>True if the user has the specified permission; otherwise, false.</returns>

    bool HasPermission(string permission);

    /// <summary>
    /// Checks if the current user is an administrator.
    /// </summary>
    /// <returns>True if the user is an administrator; otherwise, false.</returns>

    bool IsAdminUser();

    /// <summary>
    /// Checks if the current user is an operator.
    /// </summary>
    /// <returns>True if the user is an operator; otherwise, false.</returns>

    bool IsOperator();
}

INotificationService.cs

INotificationService collects user-facing messages during a request (validation, business rules, warnings). The dispatcher merges those messages into Result.Errors so callers get a single envelope. Pair this with Exception handling for the full picture.

  • Namespace: CodeBlock.DevKit.Application.Services
// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

namespace CodeBlock.DevKit.Application.Services;

/// <summary>
/// Service interface for managing in-memory notifications and messages.
/// Provides functionality to collect, retrieve, and manage notification messages during request processing.
/// </summary>
public interface INotificationService
{
    /// <summary>
    /// Adds a single notification message to the collection.
    /// </summary>
    /// <param name="notification">The notification message to add.</param>

    void Add(string notification);

    /// <summary>
    /// Adds multiple notification messages to the collection.
    /// </summary>
    /// <param name="notifications">The list of notification messages to add.</param>

    void AddRange(List<string> notifications);

    /// <summary>
    /// Gets all current notification messages without clearing them.
    /// </summary>
    /// <returns>List of all notification messages.</returns>

    List<string> GetList();

    /// <summary>
    /// Gets all current notification messages and then clears the collection.
    /// </summary>
    /// <returns>List of all notification messages before clearing.</returns>

    List<string> GetListAndReset();

    /// <summary>
    /// Checks if there are any notification messages in the collection.
    /// </summary>
    /// <returns>True if there are notifications; otherwise, false.</returns>

    bool HasAny();

    /// <summary>
    /// Clears all notification messages from the collection.
    /// </summary>

    void Reset();
}

IEncryptionService.cs

IEncryptionService centralizes cryptographic operations your application needs: hashing, salt generation, encrypt/decrypt, and related helpers so secrets and sensitive values are handled through one abstraction instead of ad hoc APIs.

  • Namespace: CodeBlock.DevKit.Application.Services
// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

namespace CodeBlock.DevKit.Application.Services;

/// <summary>
/// Service interface for cryptographic operations including encryption, hashing, and digital signatures.
/// Provides security functionality for data protection and integrity verification.
/// </summary>
public interface IEncryptionService
{
    /// <summary>
    /// Creates a cryptographic hash of the plain text using the specified salt.
    /// </summary>
    /// <param name="plainText">The text to hash.</param>
    /// <param name="salt">The salt value to use for hashing.</param>
    /// <returns>The hashed value as a string.</returns>

    string CreateHash(string plainText, string salt);

    /// <summary>
    /// Generates a cryptographically secure random salt of the specified size.
    /// </summary>
    /// <param name="size">The size of the salt in bytes.</param>
    /// <returns>A random salt string.</returns>

    string CreateSalt(int size);

    /// <summary>
    /// Decrypts the specified cipher text to its original plain text.
    /// </summary>
    /// <param name="cipherText">The encrypted text to decrypt.</param>
    /// <returns>The decrypted plain text.</returns>

    string DecryptText(string cipherText);

    /// <summary>
    /// Encrypts the specified plain text to cipher text.
    /// </summary>
    /// <param name="plainText">The plain text to encrypt.</param>
    /// <returns>The encrypted cipher text.</returns>

    string EncryptText(string plainText);

    /// <summary>
    /// Creates a digital signature for the specified data.
    /// </summary>
    /// <param name="data">The data to sign.</param>
    /// <returns>The digital signature as a string.</returns>

    string Sign(string data);
}

Contracts (CodeBlock.DevKit.Contracts.Services)

IFileService.cs

IFileService handles file I/O used across features: read a file under the web root as base64, save one or many base64 payloads to disk under path segments you supply (with optional image compression), and return FileInformation (name, URL, detected type). Implementations typically live in infrastructure and respect your hosting layout.

  • Namespace: CodeBlock.DevKit.Contracts.Services
using CodeBlock.DevKit.Contracts.Models;

namespace CodeBlock.DevKit.Contracts.Services;

/// <summary>
/// Service interface for file operations including reading, saving, and processing files.
/// Provides methods to convert files to base64, save files to disk, and process multiple files with automatic type detection.
/// </summary>
public interface IFileService
{
    /// <summary>
    /// Reads a file from the specified relative URL and converts it to a base64 string.
    /// The file path is resolved relative to the web root directory.
    /// </summary>
    /// <param name="fileRelativeUrl">Relative URL path to the file (e.g., "/uploads/image.jpg")</param>
    /// <returns>Base64 encoded string representation of the file</returns>
    /// <exception cref="FileNotFoundException">Thrown when the file does not exist at the specified path</exception>
    Task<string> GetBase64FromFileUrl(string fileRelativeUrl);

    /// <summary>
    /// Saves a single base64-encoded file to disk and returns file information.
    /// Creates the directory structure if it doesn't exist based on the provided paths.
    /// If the file is an image, it will be compressed before saving to reduce file size.
    /// </summary>
    /// <param name="fileName">Name of the file to save (query strings are automatically removed). If null or empty, a file name will be automatically generated based on the detected file type.</param>
    /// <param name="base64Image">Base64-encoded string representation of the file content</param>
    /// <param name="imageCompressionQuality">Compression quality for images (0-100, where 100 is best quality). Default is 75 for good quality/size balance. Only applies to image files.</param>
    /// <param name="paths">Variable number of path segments to create the directory structure (e.g., "bots", "botId", "input")</param>
    /// <returns><see cref="FileInformation"/> object containing file name, URL, and detected file type</returns>
    Task<FileInformation> SaveFileAsync(string? fileName, string base64Image, int imageCompressionQuality = 75, params string[] paths);

    /// <summary>
    /// Processes multiple base64-encoded files, automatically detects their types, saves them to disk, and returns file information.
    /// Detects file types using magic number signatures (file headers) for images, videos, PDFs, audio, and text files.
    /// Invalid or empty base64 strings are skipped with a warning logged.
    /// If files are images, they will be compressed before saving to reduce file size.
    /// </summary>
    /// <param name="base64Files">Collection of base64-encoded file strings to process</param>
    /// <param name="imageCompressionQuality">Compression quality for images (0-100, where 100 is best quality). Default is 75 for good quality/size balance. Only applies to image files.</param>
    /// <param name="paths">Variable number of path segments to create the directory structure for saved files (e.g., "bots", "botId", "input")</param>
    /// <returns>Collection of <see cref="FileInformation"/> objects containing file name, URL, and detected file type for each successfully processed file</returns>
    /// <remarks>
    /// Supported file type detection includes:
    /// - Images: JPEG, PNG, GIF, BMP, WebP
    /// - Videos: MP4, AVI
    /// - Documents: PDF
    /// - Audio: MP3, WAV
    /// - Text files (detected by ASCII content analysis)
    /// Files with invalid base64 encoding or empty data are skipped and not included in the result.
    /// </remarks>
    Task<IEnumerable<FileInformation>> SaveFilesAsync(IEnumerable<string> base64Files, int imageCompressionQuality = 75, params string[] paths);
}

How this fits with modules

  • Services (this page) cover cross-cutting behavior: command/query dispatch, current user context, request-scoped notifications, encryption, and file helpers.
  • Module interfaces cover product domains (billing, identity admin, AI, and so on). Combine both in the same use case when needed.

See Dependency injection for how module services are registered and discovered.