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

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 with Attributes

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

Request Validator (sync)

This request validator shows a sample without attribute validation.

public static class AddCreateFormsConfigurationRequestValidatorExtension
{
    internal static void AddCreateFormsConfigurationRequestValidator(this IServiceCollection services,
                                                                        IConfiguration configuration)
    {       
        services.AddFormsConfigurationSettings(configuration);

        services.AddSingletonIfNotExists<CreateFormsConfigurationRequestValidator>();
    }
}

internal sealed class CreateFormsConfigurationRequestValidator : RequestValidator<CreateFormsConfigurationRequest>
{
    protected override IEnumerable<PropertyValidationResult> GetValidationErrors(CreateFormsConfigurationRequest request)
    {
        // Your validation code here
        if (request.FormsId.IsNull())
        {
            var errorDetails = new ValidationErrorDetails
                                {
                                    CurrentValue = request.FormsId,
                                    Errors = [$"{nameof(request.FormsId)} must not be null. Only GUID or a long is valid for the {nameof(request.FormsId)}"],
                                    Samples = ["a1b2c3d4-e5f6-7890-1234-567890abcdef", "1"]
                                };

            yield return new PropertyValidationResult(nameof(request.FormsId), errorDetails);
        }
    }
}

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

Injectable Endpoint

The Injectable Endpoint feature introduces a clean, modular way to register Minimal API endpoints directly through dependency injection. Instead of mapping endpoints manually inside Program.cs, you can now inject them into your application as services.

This makes your API endpoints:

• Discoverable – any registered IEndpoint implementation will be automatically picked up.
• Modular – endpoints are defined in self-contained classes.
• No application.Map calls necessary in Program.cs or somewhere else → resolved automatically
• Provides the option in future to configure which endpoints are available and which not.

Interface:

public interface IEndpoint
{
    void Map(IEndpointRouteBuilder versionBasePath);
}

Sample:

internal static class AddCreateCapabilityEndpointExtension
{
    internal static void AddCreateCapabilityEndpoint(this IServiceCollection services)
    {
        services.AddSingletonIfNotExists<IEndpoint, CreateCapabilityEndpoint>();
    }
}
    
internal class CreateCapabilityEndpoint(CapabilityProvider capabilityProvider) : IEndpoint
{
    public void Map(IEndpointRouteBuilder endpoints)
    {
        // Your endpoint registration logic here :)
        endpoints.MapPost("/capabilities", async (CreateCapabilityRequest request, CancellationToken cancellationToken) =>
        {
            var capability = await capabilityProvider.CreateAsync(request, cancellationToken);
            return Results.Created($"/capabilities/{capability.Id}", capability);
        })
    }
}

Registration:

As you can see no Map necessary. We just register the endpoint

namespace Sdc.Console.Api.Capabilities.V1
{
    internal static class CreateStartup
    {
        internal static void AddCreate(this IServiceCollection services,
                                       IConfiguration configuration)
        {
            services.AddCreateCapabilityCommand(configuration);
            services.AddCreateCapabilityEndpoint();
        }
    }
}

AWS DynamoDB Custom Converters

The Siemens.AspNet.MinimalApi.Sdk already provides out of the box some helpers for the most common types. You can use them directly or implement your own converters.

Sample:

[DynamoDBTable("Capability")]
public record CapabilityEntity
{
    [DynamoDBHashKey]
    public required Guid Id { get; init; }

    [DynamoDBRangeKey]
    public required string DeploymentId { get; init; } = CapabilityConstants.DefaultDeploymentId;

    [DynamoDBProperty(typeof(DateTimeOffsetConverter))]
    public required DateTimeOffset LastUpdatedDate { get; init; } = DateTimeOffset.UtcNow;
}

AWS Dynamo Entity Mapper (POC)

The IDynamoEntityMapper brings already most common converter with it (Siemens.AspNet.MinimalApi.Sdk). You can just use it. In exception cases, you can implement your own converter by implementing IDynamoTypeConverter or IAsyncDynamoTypeConverter.

public sealed class MyHandler(IDynamoEntityMapper mapper)
{
    public async Task<MyDto> HandleAsync(object rawData, CancellationToken cancellationToken)
    {
        return await mapper.ConvertAsync<MyDto>(rawData, cancellationToken);
    }
}

Custom property converter example:

internal static class AddTimeSpanToStringConverterExtension
{
    internal static void AddTimeSpanToStringConverter(this IServiceCollection services)
    {
        services.AddSingletonIfNotExists<IDynamoTypeConverter, TimeSpanToStringConverter>();
    }
}

internal sealed class TimeSpanToStringConverter : IDynamoTypeConverter
{
    public bool CanConvert(Type source,
                            Type target)
    {
        var canConvert = source == typeof(TimeSpan) &&
                            target == typeof(string);

        return canConvert;
    }

    public object? ConvertObject(object? source,
                                    Type targetType)
    {
        return source?.ToString();
    }
}

📌 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.
• Use IDynamoTypeConverter or IAsyncDynamoTypeConverter to encapsulate DynamoDB-safe conversions.
• Register custom converters and provide an implementation of IDynamoEntityMapper to centralize conversion logic.

📚 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.