MinimalHelpers

Minimale APIS -Helfer

Eine Sammlung von Helferbibliotheken für minimale API -Projekte.

MinimalHelpers.routing

Eine Bibliothek, die Routing -Helfer für minimale API -Projekte für die Registrierung automatischer Endpunkte mithilfe von Reflexion bietet.

Installation

Die Bibliothek ist auf Nuget erhältlich. Suchen Sie einfach nach minimalHelpers.routing in der Paket -Manager -GUI oder führen Sie den folgenden Befehl in der .NET -CLI aus:

dotnet add package MinimalHelpers.Routing

Verwendung

Erstellen Sie eine Klasse, um die Registrierung Ihrer Routenhandler zu halten und die Implementierung der IEndpointRouteHandlerBuilder -Schnittstelle zu ermöglichen:

 public class PeopleEndpoints : MinimalHelpers . Routing . IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints ( IEndpointRouteBuilder endpoints )
    {
        endpoints . MapGet ( "/api/people" , GetList ) ;
        endpoints . MapGet ( "/api/people/{id:guid}" , Get ) ;
        endpoints . MapPost ( "/api/people" , Insert ) ;
        endpoints . MapPut ( "/api/people/{id:guid}" , Update ) ;
        endpoints . MapDelete ( "/api/people/{id:guid}" , Delete ) ;
    }

    // ...
}

Rufen Sie die Erweiterungsmethode MapEndpoints() auf das Webapplication -Objekt im Program.cs vor dem Run() -Methode -Aufruf auf:

 // using MinimalHelpers.Routing;
app . MapEndpoints ( ) ;

app . Run ( ) ;

Standardmäßig scannen MapEndpoints() die aufrufende Montage, um nach Klassen zu suchen, in denen die Schnittstelle IEndpointRouteHandlerBuilder implementiert wird. Wenn Ihre Routenhandler in einer anderen Versammlung definiert sind, haben Sie zwei Alternativen:

• Verwenden Sie die Überlastung des MapEndpoints() , die die Montage zum Argument scannen müssen
• Verwenden Sie die MapEndpointsFromAssemblyContaining<T>() Erweiterungsmethode und geben Sie einen Typ an, der in der Baugruppe enthalten ist, die Sie scannen möchten

Sie können auch explizit entscheiden, welche Typen (unter denjenigen, die die IRouteEndpointHandlerBuilder -Schnittstelle implementieren), die Sie tatsächlich zuordnen möchten, und ein Prädikat an die MapEndpoints -Methode weitergeben:

 app . MapEndpoints ( type =>
{
    if ( type . Name . StartsWith ( "Products" ) )
    {
        return false ;
    }

    return true ;
} ) ;

Beachten Sie, dass diese Methoden auf Reflexion beruhen, um die Baugruppe zu scannen und die Klassen zu finden, die die IEndpointRouteHandlerBuilder -Schnittstelle implementieren. Dies kann eine Leistungswirkung haben, insbesondere in großen Projekten. Wenn Sie Leistungsprobleme haben, sollten Sie die explizite Registrierungsmethode verwenden. Darüber hinaus ist diese Lösung inkompatibilisch mit nativem AOT.

MinimalHelpers.routing.Analyzers

Eine Bibliothek, die einen Quellgenerator für die Registrierung der automatischen Endpunkte in minimalen API -Projekten bietet.

Installation

Die Bibliothek ist auf Nuget erhältlich. Suchen Sie einfach nach minimalHelpers.routing in der Paket -Manager -GUI oder führen Sie den folgenden Befehl in der .NET -CLI aus:

dotnet add package MinimalHelpers.Routing.Analyzers

Verwendung

Erstellen Sie eine Klasse, um die Registrierung Ihrer Routenhandler zu halten und die Implementierung der IEndpointRouteHandlerBuilder -Schnittstelle zu ermöglichen:

 public class PeopleEndpoints : IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints ( IEndpointRouteBuilder endpoints )
    {
        endpoints . MapGet ( "/api/people" , GetList ) ;
        endpoints . MapGet ( "/api/people/{id:guid}" , Get ) ;
        endpoints . MapPost ( "/api/people" , Insert ) ;
        endpoints . MapPut ( "/api/people/{id:guid}" , Update ) ;
        endpoints . MapDelete ( "/api/people/{id:guid}" , Delete ) ;
    }

    // ...
}

Beachten Sie, dass Sie nur das Paket minimalHelpers.routing.Analyzers verwenden müssen. Mit diesem Quellgenerator ist die Schnittstelle IEndpointRouteHandlerBuilder automatisch generiert.

Rufen Sie die Erweiterungsmethode MapEndpoints() auf das Webapplication -Objekt im Program.cs vor dem Run() -Methode -Aufruf auf:

 app . MapEndpoints ( ) ;

app . Run ( ) ;

Beachten Sie, dass die Methode MapEndpoints vom Quellgenerator generiert wird.

MinimalHelpers.openapi

Eine Bibliothek, die OpenAPI -Helfer für minimale API -Projekte anbietet.

Installation

Die Bibliothek ist auf Nuget erhältlich. Suchen Sie einfach nach minimalHelpers.openapi in der Paket -Manager -GUI oder führen Sie den folgenden Befehl in der .NET -CLI aus:

dotnet add package MinimalHelpers.OpenApi

Verwendung

Erweiterungsmethoden für OpenAPI

Diese Bibliothek bietet einige Erweiterungsmethoden, die die OpenAPI -Konfiguration in minimalen API -Projekten vereinfachen. Beispielsweise ist es möglich, die Beschreibung einer Antwort mit ihrem Statuscode anzupassen:

 endpoints . MapPost ( "login" , LoginAsync )
    . AllowAnonymous ( )
    . WithValidation < LoginRequest > ( )
    . Produces < LoginResponse > ( StatusCodes . Status200OK )
    . Produces < LoginResponse > ( StatusCodes . Status206PartialContent )
    . Produces ( StatusCodes . Status403Forbidden )
    . ProducesValidationProblem ( )
    . WithOpenApi ( operation =>
    {
        operation . Summary = "Performs the login of a user" ;

        operation . Response ( StatusCodes . Status200OK ) . Description = "Login successful" ;
        operation . Response ( StatusCodes . Status206PartialContent ) . Description = "The user is logged in, but the password has expired and must be changed" ;
        operation . Response ( StatusCodes . Status400BadRequest ) . Description = "Incorrect username and/or password" ;
        operation . Response ( StatusCodes . Status403Forbidden ) . Description = "The user was blocked due to too many failed logins" ;

        return operation ;
    } ) ;

Erweiterungsmethoden für Routehandlerbuilder

Oft haben wir Endpunkte mit mehreren 4xx -Rückgabetwerten, von denen jede eine ProblemDetails -Antwort erzeugt:

 endpoints . MapGet ( "/api/people/{id:guid}" , Get )
   . ProducesProblem ( StatusCodes . Status400BadRequest )
   . ProducesProblem ( StatusCodes . Status401Unauthorized )
   . ProducesProblem ( StatusCodes . Status403Forbidden )
   . ProducesProblem ( StatusCodes . Status404NotFound ) ;

Um mehrere Aufrufe zum ProducesProblem zu vermeiden, können wir die von der Bibliothek bereitgestellte Erweiterungsmethode ProducesDefaultProblem verwenden:

 endpoints . MapGet ( "/api/people/{id:guid}" , Get )
   . ProducesDefaultProblem ( StatusCodes . Status400BadRequest , StatusCodes . Status401Unauthorized ,
       StatusCodes . Status403Forbidden , StatusCodes . Status404NotFound ) ; 

MinimalHelpers.Validation

Eine Bibliothek, die einen Endpunktfilter für minimale API -Projekte bereitstellt, um Validierung mit Datenanmerkungen mit der Minivalidationsbibliothek durchzuführen.

Installation

Die Bibliothek ist auf Nuget erhältlich. Suchen Sie einfach nach MinimalHelpers.Validation in der Paket -Manager -GUI oder führen Sie den folgenden Befehl in der .NET -CLI aus:

dotnet add package MinimalHelpers.Validation

Verwendung

Dekoriert eine Klasse mit Attributen, um die Validierungsregeln zu definieren:

 using System . ComponentModel . DataAnnotations ;

public class Person
{
    [ Required ]
    [ MaxLength ( 20 ) ]
    public string ? FirstName { get ; set ; }

    [ Required ]
    [ MaxLength ( 20 ) ]
    public string ? LastName { get ; set ; }

    [ MaxLength ( 50 ) ]
    public string ? City { get ; set ; }
}

Fügen Sie die Erweiterungsmethode WithValidation<T>() hinzu, um den Validierungsfilter zu aktivieren:

 using MinimalHelpers . Validation ;

app . MapPost ( "/api/people" , ( Person person ) =>
    {
        // ...
    } )
    . WithValidation < Person > ( ) ;

Wenn die Validierung fehlschlägt, handelt es sich bei der Antwort um eine 400 Bad Request mit einem ValidationProblemDetails -Objekt, das die Validierungsfehler enthält, zum Beispiel:

{
  "type" : " https://tools.ietf.org/html/rfc9110#section-15.5.1 " ,
  "title" : " One or more validation errors occurred " ,
  "status" : 400 ,
  "instance" : " /api/people " ,
  "traceId" : " 00-009c0162ba678cae2ee391815dbbb59d-0a3a5b0c16d053e6-00 " ,
  "errors" : {
    "FirstName" : [
      " The field FirstName must be a string or array type with a maximum length of '20'. "
    ],
    "LastName" : [
      " The LastName field is required. "
    ]
  }
}

Wenn Sie die Validierung anpassen möchten, können Sie die ConfigureValidation -Erweiterungsmethode verwenden:

 using MinimalHelpers . Validation ;

builder . Services . ConfigureValidation ( options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options . ErrorResponseFormat = ErrorResponseFormat . List ;

    // The default is "One or more validation errors occurred"
    options . ValidationErrorTitleMessageFactory =
        ( context , errors ) => $ "There was { errors . Values . Sum ( v => v . Length ) } error(s)" ;
} ) ;

Sie können die ValidationErrorTitleMessageFactory verwenden, z. B. wenn Sie die title der Antwort mithilfe einer RESX -Datei lokalisieren möchten.

MinimalHelpers.fluentValidation

Eine Bibliothek, die einen Endpunktfilter für minimale API -Projekte zur Durchführung einer Validierung mit Fluentvalidierung bereitstellt.

Installation

Die Bibliothek ist auf Nuget erhältlich. Suchen Sie einfach nach minimalHelpers.fluentValidation in der Paket -Manager -GUI oder führen Sie den folgenden Befehl in der .NET -CLI aus:

dotnet add package MinimalHelpers.FluentValidation

Verwendung

Erstellen Sie eine Klasse, die den AbstractValidator erweitert und die Validierungsregeln definiert:

 using FluentValidation ;

public record class Product ( string Name , string Description , double UnitPrice ) ;

public class ProductValidator : AbstractValidator < Product >
{
    public ProductValidator ( )
    {
        RuleFor ( p => p . Name ) . NotEmpty ( ) . MaximumLength ( 50 ) . EmailAddress ( ) ;
        RuleFor ( p => p . Description ) . MaximumLength ( 500 ) ;
        RuleFor ( p => p . UnitPrice ) . GreaterThan ( 0 ) ;
    }
}

Registrieren Sie Validatoren in der Service -Sammlung:

 using FluentValidation ;

// Assuming the validators are in the same assembly as the Program class
builder . Services . AddValidatorsFromAssemblyContaining < Program > ( ) ;

Fügen Sie die Erweiterungsmethode WithValidation<T>() hinzu, um den Validierungsfilter zu aktivieren:

 using MinimalHelpers . FluentValidation ;

app . MapPost ( "/api/products" , ( Product product ) =>
    {
        // ...
    } )
    . WithValidation < Product > ( ) ;

Wenn die Validierung fehlschlägt, handelt es sich bei der Antwort um eine 400 Bad Request mit einem ValidationProblemDetails -Objekt, das die Validierungsfehler enthält, zum Beispiel:

{
  "type" : " https://tools.ietf.org/html/rfc9110#section-15.5.1 " ,
  "title" : " One or more validation errors occurred " ,
  "status" : 400 ,
  "instance" : " /api/products " ,
  "traceId" : " 00-f4ced0ae470424dd04cbcebe5f232dc5-bbdcc59f310ebfb8-00 " ,
  "errors" : {
    "Name" : [
      " 'Name' cannot be empty. "
    ],
    "UnitPrice" : [
      " 'Unit Price' must be grater than '0'. "
    ]
  }
}

Wenn Sie die Validierung anpassen möchten, können Sie die ConfigureValidation -Erweiterungsmethode verwenden:

 using MinimalHelpers . Validation ;

builder . Services . ConfigureValidation ( options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options . ErrorResponseFormat = ErrorResponseFormat . List ;

    // The default is "One or more validation errors occurred"
    options . ValidationErrorTitleMessageFactory =
        ( context , errors ) => $ "There was { errors . Values . Sum ( v => v . Length ) } error(s)" ;
} ) ;

Sie können die ValidationErrorTitleMessageFactory verwenden, z. B. wenn Sie die title der Antwort mithilfe einer RESX -Datei lokalisieren möchten.

Beitragen

Das Projekt entwickelt sich ständig weiter. Beiträge sind willkommen. Fühlen Sie sich frei, Probleme zu stellen und Anfragen auf das Repo zu ziehen, und wir werden sie so ansprechen, wie wir können.