FractalDataWorks.Services.Abstractions 0.4.0-preview.6

FractalDataWorks.Services.Abstractions

Contracts and base implementations for domain services in the FractalDataWorks framework. This package provides service interfaces, command builders, configuration contracts, factory and provider patterns, and health checking infrastructure.

Installation

dotnet add package FractalDataWorks.Services.Abstractions

Target Framework: netstandard2.0

Package Contents

This package contains:

• IGenericService<TCommand> - Service interface with command execution
• IGenericService<TCommand, TConfiguration> - Service interface with configuration access
• IGenericService<TCommand, TConfiguration, TService> - Full service interface with type identification
• ServiceBase<TCommand, TConfiguration, TService> - Base class for service implementations
• IFdwServiceProvider / IFdwServiceProvider<TService> - Service resolution contracts
• IServiceFactoryProvider - Factory registry for dynamic service creation
• IGenericCommandBuilder<TCommand> - Fluent command construction
• IGenericValidator<T> - Validation contracts with FluentValidation integration
• IServiceConfiguration - Service-specific configuration contract
• IServiceLifetime / ServiceLifetimes - DI lifetime management
• IHealthCheckable / HealthStates - Health monitoring infrastructure
• ServiceBaseLogger - MessageLogging integration for services

Service Interface Hierarchy

The framework provides a progressive interface hierarchy. Base interface IGenericService is defined in FractalDataWorks.Abstractions; this package extends it with command support.

From IGenericService.cs:20-31:

public interface IGenericService<TCommand> : IGenericService
    where TCommand : IGenericCommand
{
    // Id, ServiceType, and IsAvailable are inherited from IGenericService base interface

    /// <summary>
    /// Executes a command using the service.
    /// </summary>
    /// <param name="command">The command to execute.</param>
    /// <returns>A task containing the execution result.</returns>
    Task<IGenericResult> Execute(TCommand command);
}

From IGenericService.cs:44-92:

public interface IGenericService<TCommand, TConfiguration> : IGenericService<TCommand>
    where TCommand : IGenericCommand
    where TConfiguration : IGenericConfiguration
{
    /// <summary>
    /// Gets the service name for display purposes.
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Gets the configuration instance for this service.
    /// </summary>
    TConfiguration Configuration { get; }

    /// <summary>
    /// Executes a command with generic return type.
    /// </summary>
    Task<IGenericResult<T>> Execute<T>(TCommand command);

    /// <summary>
    /// Executes a command with generic return type and cancellation support.
    /// </summary>
    Task<IGenericResult<TOut>> Execute<TOut>(TCommand command, CancellationToken cancellationToken);

    /// <summary>
    /// Executes a command with cancellation support.
    /// </summary>
    Task<IGenericResult> Execute(TCommand command, CancellationToken cancellationToken);
}

From IGenericService.cs:106-113:

public interface IGenericService<TCommand, TConfiguration, TService> : IGenericService<TCommand, TConfiguration>
    where TCommand : IGenericCommand
    where TConfiguration : IGenericConfiguration
    where TService : class
{
    // No additional members - the TService is used for type identification and logging
}

ServiceBase Implementation

ServiceBase provides the foundation for all service implementations with command type checking and logging integration.

From ServiceBase.cs:26-70:

public abstract class ServiceBase<TCommand, TConfiguration, TService> : IGenericService, IDisposable
    where TCommand : IGenericCommand
    where TConfiguration : IGenericConfiguration
    where TService : class
{
    private readonly ILogger _logger;
    private bool _disposed;

    /// <summary>
    /// Gets the unique identifier for this service instance.
    /// </summary>
    public string Id { get; }

    /// <summary>
    /// Gets the display name of the service.
    /// </summary>
    public string ServiceType { get; }

    /// <summary>
    /// Gets a value indicating whether the service is currently available for use.
    /// </summary>
    public virtual bool IsAvailable { get; protected set; } = true;

    /// <summary>
    /// Gets the service name for display purposes.
    /// </summary>
    public string Name => Configuration?.Name ?? typeof(TService).Name;

    /// <summary>
    /// Gets the configuration instance for this service.
    /// </summary>
    public TConfiguration Configuration { get; }

    protected ServiceBase(ILogger logger, TConfiguration configuration)
    {
        _logger = logger ?? NullLogger.Instance;
        Configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
        Id = Guid.NewGuid().ToString();
        ServiceType = typeof(TService).Name;
    }

Command execution with type checking from ServiceBase.cs:80-107:

public async Task<IGenericResult<T>> Execute<T>(IGenericCommand command, CancellationToken cancellationToken)
{
    if (command is TCommand typedCommand)
    {
        return await Execute<T>(typedCommand, cancellationToken).ConfigureAwait(false);
    }

    return GenericResult<T>.Failure(
        ServiceBaseLogger.CommandTypeMismatch(Logger, typeof(TCommand).Name, command?.GetType().Name ?? "null"));
}

public async Task<IGenericResult> Execute(IGenericCommand command, CancellationToken cancellationToken)
{
    if (command is TCommand typedCommand)
    {
        return await Execute(typedCommand, cancellationToken).ConfigureAwait(false);
    }

    return GenericResult.Failure(
        ServiceBaseLogger.CommandTypeMismatch(Logger, typeof(TCommand).Name, command?.GetType().Name ?? "null"));
}

Service Provider Contracts

From IFdwServiceProvider.cs:12-40:

public interface IFdwServiceProvider
{
    /// <summary>
    /// Gets a service instance by configuration.
    /// </summary>
    IGenericResult<TService> Get<TService>(IGenericConfiguration configuration)
        where TService : IGenericService;

    /// <summary>
    /// Gets a service instance by configuration ID.
    /// </summary>
    IGenericResult<TService> Get<TService>(int configurationId)
        where TService : IGenericService;

    /// <summary>
    /// Gets a service instance by service type name.
    /// </summary>
    Task<IGenericResult<TService>> Get<TService>(string serviceTypeName)
        where TService : IGenericService;
}

Typed provider from IFdwServiceProvider.cs:47-70:

public interface IFdwServiceProvider<TService>
    where TService : IGenericService
{
    IGenericResult<TService> Get(IGenericConfiguration configuration);
    IGenericResult<TService> Get(int configurationId);
    Task<IGenericResult<TService>> Get(string serviceTypeName);
}

Service Factory Provider

The IServiceFactoryProvider acts as a registry for service factories.

From IServiceFactoryProvider.cs:18-74:

public interface IServiceFactoryProvider
{
    /// <summary>
    /// Registers a service factory for the specified service type name.
    /// </summary>
    IGenericResult RegisterFactory(string typeName, IServiceFactory factory);

    /// <summary>
    /// Registers a factory with the specified lifetime.
    /// </summary>
    IGenericResult RegisterFactory(string typeName, IServiceFactory factory, IServiceLifetime lifetime);

    /// <summary>
    /// Gets the service factory for the specified service type name.
    /// </summary>
    IGenericResult<IServiceFactory> GetFactory(string typeName);

    /// <summary>
    /// Gets the service factory with generic type safety.
    /// </summary>
    IGenericResult<IServiceFactory<TService, TConfiguration>> GetFactory<TService, TConfiguration>(string typeName)
        where TService : class
        where TConfiguration : IGenericConfiguration;

    /// <summary>
    /// Checks whether a factory is registered for the specified service type name.
    /// </summary>
    bool IsRegistered(string typeName);

    /// <summary>
    /// Gets all registered service type names.
    /// </summary>
    IEnumerable<string> GetRegisteredTypeNames();
}

Command Builder Interface

From Commands/IGenericCommandBuilder.cs:19-65:

public interface IGenericCommandBuilder<TCommand>
{
    IGenericCommandBuilder<TCommand> WithTarget(string target);
    IGenericCommandBuilder<TCommand> WithTimeout(TimeSpan timeout);
    IGenericCommandBuilder<TCommand> WithParameter(string name, object? value);
    IGenericCommandBuilder<TCommand> WithParameters(IReadOnlyDictionary<string, object?> parameters);
    IGenericCommandBuilder<TCommand> WithMetadata(string key, object value);
    IGenericCommandBuilder<TCommand> WithMetadata(IReadOnlyDictionary<string, object> metadata);
    IGenericCommandBuilder<TCommand> WithExpectedResultType(Type resultType);
    IGenericCommandBuilder<TCommand> WithExpectedResultType<TResult>();
    IGenericCommandBuilder<TCommand> WithDataModifying(bool isDataModifying);
    IGenericResult ValidateBuilder();
    IGenericResult<TCommand> Build();
    IGenericCommandBuilder<TCommand> Reset();
}

Service Configuration

From IServiceConfiguration.cs:1-24:

public interface IServiceConfiguration : IGenericConfiguration
{
    /// <summary>
    /// Gets the service type this configuration is for.
    /// </summary>
    string ServiceType { get; }

    /// <summary>
    /// Gets the timeout in milliseconds.
    /// </summary>
    int TimeoutMs { get; }
}

Service Lifetimes

The ServiceLifetimes static class provides typed lifetime options for DI registration.

From ServiceLifetimes.cs:1-41:

public static class ServiceLifetimes
{
    /// <summary>
    /// Transient lifetime - new instance created each time the service is requested.
    /// </summary>
    public static IServiceLifetime Transient { get; } = new TransientServiceLifetimeOption();

    /// <summary>
    /// Scoped lifetime - new instance created once per scope (typically per request).
    /// </summary>
    public static IServiceLifetime Scoped { get; } = new ScopedServiceLifetimeOption();

    /// <summary>
    /// Singleton lifetime - single instance created once for the entire application lifetime.
    /// </summary>
    public static IServiceLifetime Singleton { get; } = new SingletonServiceLifetimeOption();

    /// <summary>
    /// Gets a service lifetime by name.
    /// </summary>
    public static IServiceLifetime? ByName(string? name);
}

Validation

From IGenericValidator.cs:1-26:

public interface IGenericValidator<T>
{
    /// <summary>
    /// Validates the specified instance.
    /// </summary>
    Task<ValidationResult> Validate(T instance);

    /// <summary>
    /// Validates the specified instance and returns a GenericResult.
    /// </summary>
    Task<IGenericResult<T>> ValidateToResult(T instance);
}

Health Checks

The package includes health check infrastructure using TypeCollections.

From HealthChecks/IHealthCheckable.cs:15-35:

public interface IHealthCheckable
{
    /// <summary>
    /// Performs a health check for this service.
    /// </summary>
    Task<IGenericResult<IHealthCheckResult>> CheckHealth(
        IServiceProvider serviceProvider,
        CancellationToken cancellationToken = default);
}

From HealthChecks/HealthStates/HealthStates.cs:1-14:

[TypeCollection(typeof(HealthStateBase), typeof(IHealthState), typeof(HealthStates))]
public abstract partial class HealthStates : TypeCollectionBase<HealthStateBase, IHealthState>
{
}

Health states include:

• HealthyState - Service is operating normally
• DegradedState - Service is operational but with reduced capability
• UnhealthyState - Service is not operational

MessageLogging Integration

Services use the MessageLogging source generator for structured logging that returns messages for Railway-Oriented Programming.

From Logging/ServiceBaseLogger.cs:1-24:

public static partial class ServiceBaseLogger
{
    /// <summary>
    /// Logs when a command type mismatch occurs during execution.
    /// </summary>
    [MessageLogging(
        EventId = 100,
        Level = LogLevel.Error,
        Message = "Command type mismatch: expected {expectedType}, received {actualType}")]
    public static partial IGenericMessage CommandTypeMismatch(ILogger logger, string expectedType, string actualType);
}

Dependencies

This package depends on:

• FractalDataWorks.Abstractions - Base interfaces (IGenericService, IGenericCommand, IServiceFactory)
• FractalDataWorks.Results - Railway-Oriented Programming (IGenericResult<T>)
• FractalDataWorks.Messages - Messaging infrastructure (IGenericMessage)
• FractalDataWorks.MessageLogging.Abstractions - MessageLogging attributes
• FractalDataWorks.Collections - TypeCollection infrastructure
• FluentValidation - Validation framework
• Microsoft.Extensions.DependencyInjection.Abstractions - DI abstractions
• Microsoft.Extensions.Logging.Abstractions - Logging abstractions
• Microsoft.Extensions.Configuration - Configuration abstractions

Related Packages

• FractalDataWorks.Abstractions - Core framework contracts
• FractalDataWorks.Results - Railway-Oriented Programming
• FractalDataWorks.Messages - Messaging infrastructure
• FractalDataWorks.Collections - TypeCollection infrastructure