Siemens.AspNet.MinimalApi.Sdk.Contracts 0.1.0-alpha.97

Siemens.AspNet.MinimalApi.Sdk.Contracts

The Siemens.AspNet.MinimalApi.Sdk.Contracts NuGet package defines essential interfaces, attributes, and base classes designed to standardize common functionalities required for building Minimal APIs. These abstractions support dependency injection, JSON serialization, difference tracking, and advanced validation scenarios.

📖 Overview

This package provides foundational contracts that facilitate a structured, extensible, and maintainable Minimal API architecture.

✅ Key Abstractions

• 📐 Activators

  • IActivator
  • IAsyncActivator<T>
  • ICustomActivator<T>

• 📦 JSON Serialization & Differencing

  • IJsonSerializer for robust serialization and deserialization.
  • IJsonDiffer for detailed JSON comparison and difference detection.

• ✔️ Advanced Validation

  • IAttributeValidator for recursive and attribute-driven validation.

  • CustomValidatorBase<T, TAttribute> for custom synchronous validation logic.

  • AsyncCustomValidatorBase<T, TAttribute> for asynchronous custom validation.

  • Request validation abstractions:

    • RequestValidator<TRequest> and AsyncRequestValidator<TRequest> for complete object validation.
    • PatchRequestValidator<TRequest> and AsyncPatchRequestValidator<TRequest> specifically tailored for PATCH scenarios.

📦 Installation

Using the .NET CLI

dotnet add package Siemens.AspNet.MinimalApi.Sdk.Contracts

⚡ Examples

Activator Usage

public class ExampleService
{
    private readonly IActivator _activator;

    public ExampleService(IActivator activator)
    {
        _activator = activator;
    }

    public async Task<MyClass> CreateMyClassAsync()
    {
        return await _activator.CreateInstanceAsync<MyClass>();
    }
}

JSON Differ Example

public void CheckJsonDifferences(IJsonDiffer jsonDiffer)
{
    var differences = jsonDiffer.FindDifferences("{\"name\":\"John\"}", "{\"name\":\"Jane\"}");
    foreach (var diff in differences)
    {
        Console.WriteLine($"Property: {diff.MemberPath}, Difference: {diff.MismatchType}");
    }
}

Custom Validation

internal static class AddAlphaNumericValidatorExtension
{
    internal static void AddAlphaNumericValidator(this IServiceCollection services)
    {
        services.AddSingletonIfNotExists<ICustomValidator, AlphaNumericValidator>();
    }
}

public class AlphaNumericAttribute(params string[] sampleValues) : CustomValidationAttribute<AlphaNumericValidator>(string.Empty, sampleValues);

public sealed class AlphaNumericValidator : CustomValidatorBase<string, AlphaNumericAttribute>
{
    protected override IEnumerable<ValidationErrorDetailsBase> Validate(PropertyInfo propertyInfo,
                                                                        AlphaNumericAttribute attribute,
                                                                        string? source)
    {
        if (source == null)
        {
            yield break;
        }

        if (source.Any(ch => !char.IsLetterOrDigit(ch)))
        {
            var sampleValues = attribute.SampleValues.Any() ? attribute.SampleValues : ["sample123"];

            yield return new ValidationErrorDetailsBase
            {
                Errors = [$"{propertyInfo.Name} must be alphanumeric."],
                Samples = sampleValues
            };
        }
    }
}

Async Request Validator

In this sample the async validator is used to validate a CreateDeploymentRequest object. The validator checks for the presence of required properties and validates them using the IAttributeValidator interface.

public sealed record CreateDeploymentRequest
{
    [ValidEnum]
    public required Stage Stage { get; init; }
};

internal static class AddCreateDeploymentRequestValidatorExtension
{
    internal static void AddCreateDeploymentRequestValidator(this IServiceCollection services)
    {
        services.AddSingletonIfNotExists<CreateDeploymentRequestValidator>();
    }
}

internal sealed class CreateDeploymentRequestValidator(IAttributeValidator attributeValidator) : AsyncRequestValidator<CreateDeploymentRequest>
{
    protected override async IAsyncEnumerable<PropertyValidationResult> GetValidationErrorsAsync(CreateDeploymentRequest request,
                                                                                                    [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var errors = await attributeValidator.ValidateAsync(request, cancellationToken).ConfigureAwait(false);
        foreach (var propertyValidationResult in errors)
        {
            yield return propertyValidationResult;
        }
    }
}

📌 Usage & Best Practices

• Leverage IActivator for instance creation with dependency injection.
• Leverage IAsyncActivator for instance creation with dependency injection in asynchronous contexts.
• Utilize IJsonDiffer for tracking JSON changes in PATCH requests.
• Implement custom validation logic by extending provided base validator classes.
• Implement IAttributeValidator custom for attribute-driven validation scenarios.
• Simplified attribut-based validation by the IAttributeValidator interface.

📚 Documentation

Additional details and examples are available in the repository documentation and upcoming online resources.

📢 Contributing

Your contributions and feedback are welcomed! Please create issues or pull requests to enhance this package.