Siemens.AspNet.MinimalApi.Sdk 0.1.0-alpha.275

Siemens.AspNet.Minimal.Sdk

The Siemens.AspNet.Minimal.Sdk NuGet package offers a streamlined approach to building Minimal APIs in ASP.NET Core. It includes pre-configured defaults, opinionated helpers, and seamless integrations that accelerate development and simplify application setup.

📖 Overview

This SDK is designed to remove boilerplate code and help you focus on what matters: your business logic.

✅ Key Features

• ⚙️ Pre-configured application startup
• ☁️ AWS integration (optional)
• 🗄️ Database connectivity (supports AWS DynamoDB)
• 🔄 Consistent JSON serialization settings
• 🔐 Security best practices (JWT, OAuth2, security headers)
• ✔️ Custom validation support
• 📘 Auto-configured OpenAPI/Swagger

📦 Installation

Using the .NET CLI

dotnet add package Siemens.AspNet.Minimal.Sdk

⚡ Quickstart Example

Below is a minimal setup using ServerlessMinimalWebApi, designed to get you started in seconds:

using Pulse.FieldingTool.Api;
using Siemens.AspNet.MinimalApi.Sdk;

// Create the minimal API host
var webApi = new ServerlessMinimalWebApi();

// Optionally set a global base path for all endpoints
webApi.BasePath = "api/fieldingtool";

// Register application services
webApi.RegisterServices = (services, config) =>
{
    services.AddApi(config);
};

// Map API endpoints
webApi.MapEndpoints = endpoints =>
{
    endpoints.MapApi();
};

// Run the application
webApi.Run(args);

// Enable testing via WebApplicationFactory<Program>
namespace Pulse.FieldingTool
{
    public partial class Program {}
}

🧠 Key Concepts

Helpers and utils

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

Complex-Custom Validation with Attributes

We provide another level of validation if you have an data historie to compare current value against your privious value. (Historical Validation)

internal static class AddIsNotChangeableAfterDeploymentValidatorExtension
    {
        internal static void AddIsNotChangeableAfterDeploymentValidator(this IServiceCollection services)
        {
            services.AddSingletonIfNotExists<IComplexCustomValidator, IsNotChangableAfterDeploymentValidator>();
        }
    }

    internal sealed class IsNotChangeableAfterDeploymentAttribute() : ComplexCustomValidationAttribute<IsNotChangableAfterDeploymentValidator>(string.Empty, [])
    {
    }

    internal sealed class IsNotChangableAfterDeploymentValidator() : ComplexCustomValidator<AwsS3Bucket, string?, IsNotChangeableAfterDeploymentAttribute>
    {
        protected override IEnumerable<ValidationErrorDetailsBase> Validate(PropertyInfo propertyInfo,
                                                                            IsNotChangeableAfterDeploymentAttribute attribute,
                                                                            AwsS3Bucket capability,
                                                                            string? currentValue,
                                                                            string? lastValue)
        {
            if (capability.IsDeployed.IsFalse())
            {
                yield break;
            }

            if (currentValue != lastValue)
            {
                yield return new ValidationErrorDetailsBase
                {
                    Errors = [$"You are not allowed to change the: {propertyInfo.Name} after the capability was deployed ! This would cause in critical male function of your project"],
                    Samples = [currentValue]
                };
            }
        }
    }

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.AddLanguageValidator();
        services.AddFormsConfigurationSettings(configuration);

        services.AddSingletonIfNotExists<CreateFormsConfigurationRequestValidator>();
    }
}

internal sealed class CreateFormsConfigurationRequestValidator(LanguageValidator languageValidator,
                                                               FormsConfigurationSettings formsConfigurationSettings,
                                                               IAttributeValidator attributeValidator) : RequestValidator<CreateFormsConfigurationRequest>(IAttributeValidator attributeValidator)
{
    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.