Table of Contents

General services

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

Each subsection below gives the namespace and full source of the contract via DocFX so you can use the type without browsing a private repo. For module interfaces, see Pre-built module services and the Modules documentation.

Application layer (CodeBlock.DevKit.Application.Services)

Interface Typical use
IRequestDispatcher Send BaseCommand / BaseQuery<T> through MediatR and receive Result / Result<T> (see Application services).
ICurrentUser Read the signed-in user id, name, email, roles, and permission checks in use cases or UI.
INotificationService Collect user-facing messages during a request; the dispatcher merges them into Result.Errors (see Exception handling).
IEmailService Send email through the configured provider (implementation supplied by hosting/modules).
ISmsService Send SMS through the configured provider.
IEncryptionService Hashing, salt generation, encrypt/decrypt, and related crypto helpers for application code.
IModuleRegistry Register and query DevKit UI/API/base module assemblies at startup.

IRequestDispatcher.cs

  • 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

  • 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

  • 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();
}

IEmailService.cs

  • 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 sending email messages.
/// Provides email delivery functionality for notifications and communications.
/// </summary>
public interface IEmailService
{
    /// <summary>
    /// Sends an email message to the specified recipient.
    /// </summary>
    /// <param name="to">The email address of the recipient.</param>
    /// <param name="subject">The subject line of the email.</param>
    /// <param name="body">The content body of the email.</param>
    /// <param name="isBodyHtml">Whether the body content is HTML format (default: true).</param>
    /// <returns>A task representing the asynchronous email sending operation.</returns>

    Task Send(string to, string subject, string body, bool isBodyHtml = true);
}

ISmsService.cs

  • 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 sending SMS messages.
/// Provides SMS delivery functionality for notifications and communications.
/// </summary>
public interface ISmsService
{
    /// <summary>
    /// Sends an SMS message to the specified phone number.
    /// </summary>
    /// <param name="to">The phone number of the recipient (should be in E.164 format).</param>
    /// <param name="message">The text message content to send.</param>
    /// <returns>A task representing the asynchronous SMS sending operation.</returns>

    Task Send(string to, string message);
}

IEncryptionService.cs

  • 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);
}

IModuleRegistry.cs

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

using System.Reflection;

namespace CodeBlock.DevKit.Application.Services;

/// <summary>
/// Service interface for managing module registration and dependency tracking.
/// Provides functionality to register different types of modules and query their registration status.
/// </summary>
public interface IModuleRegistry
{
    /// <summary>
    /// Registers a UI module assembly with the registry.
    /// </summary>
    /// <param name="moduleAssembly">The assembly containing the UI module.</param>

    void RegisterUIModule(Assembly moduleAssembly);

    /// <summary>
    /// Registers an API module assembly with the registry.
    /// </summary>
    /// <param name="moduleAssembly">The assembly containing the API module.</param>

    void RegisterApiModule(Assembly moduleAssembly);

    /// <summary>
    /// Registers a base module assembly with the registry.
    /// </summary>
    /// <param name="moduleAssembly">The assembly containing the base module.</param>

    void RegisterBaseModule(Assembly moduleAssembly);

    /// <summary>
    /// Gets all registered UI module assemblies.
    /// </summary>
    /// <returns>Collection of registered UI module assemblies.</returns>

    IEnumerable<Assembly> GetUIModuleAssemblies();

    /// <summary>
    /// Gets all registered API module assemblies.
    /// </summary>
    /// <returns>Collection of registered API module assemblies.</returns>

    IEnumerable<Assembly> GetApiModuleAssemblies();

    /// <summary>
    /// Checks if a module with the specified name is registered.
    /// </summary>
    /// <param name="moduleName">The name of the module to check.</param>
    /// <returns>True if the module is registered; otherwise, false.</returns>

    bool IsModuleRegistered(string moduleName);
}

Contracts (CodeBlock.DevKit.Contracts.Services)

IFileService.cs

  • 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

  • General interfaces (this page) cover cross-cutting behavior: identity context, dispatch, notifications, email/SMS, crypto, files, module assembly registration.
  • Module interfaces cover product domains (billing, identity admin, AI, and so on). Combine both in the same use case when needed.

See Pre-built module services for discovery patterns and examples.