WebApiToolkit

Wissance.Webapitoolkit

Diese LIB hilft, REST API mit C# und AspNet einfach zu erstellen, als sie in verschiedenen Projekten immer wieder von Grund auf neu zu schreiben.

1. Schlüsselmerkmale

• REST API Controller mit vollem CRUD enthält nur 20 Codezeilen (~ 10 sind Importe)
  • Methoden GET , haben ein integrierte Paging- Unterstützung.
  • Methoden GET , haben integrierte Sortierungen und Filter durch Abfrageparameter.
• Unterstützen Sie Massenoperationen mit Objekten (Bulk Create , Update und Delete ) auf einer Controller && Interface -Ebene
• Unterstützung bei der Arbeit mit einem anhaltenden Speicher ( IModelManager -Schnittstelle); Gute Unterstützung für eingebaute EntityFramework (siehe EfModelManager Klasse). Siehe Weathercontrol App mit 2 Web -API -Projekten:
  • Wissance.WeatherControl.WebApi verwendet EntityFramework ;
  • Wissance.WeatherControl.WebApi.V2 verwendet EdgeDb .

Schlüsselkonzepte:

1. Controller ist eine Klasse, die HTTP-requests zur REST Resource übernimmt.
2. REST Resource entspricht der Entity class / Database Table
3. Jede Operation auf REST Resource erzeugt JSON mit DTO als Ausgabe. Wir gehen davon aus, dass nur eine DTO -Klasse mit allen REST verwendet wird.

2. API -Vertrag

• DTO -Klassen:

  • OperationResultDto stellt das Ergebnis des Betriebs dar, der die Daten in DB ändert.
  • PagedDataDto repräsentiert Teil (Seite) derselben Objekte (jeder Typ);

• Controllers -Klassen - abstrakte Klassen

  • Basic Read Controller ( BasicReadController ) enthält 2 Methoden:
    • GET /api/[controller]/?[page={page}&size={size}&sort={sort}&order={order}] EfModelManager PagedDataDto<T> zu erhalten. Jetzt haben wir auch Möglichkeiten, eine beliebige Anzahl von Abfragenparameten zu senden. Wir übergeben auch Sortier (Spaltenname) && Order ( asc oder desc ) an Manager -Klassen. EfModelManager erlaubt es, nach einer Spalte zu sortieren. Leider haben wir hier einen Nachteil - wir sollten Swagger -Informationen überschreiben, um Abfragungsparameter zu zeigen !!! Ab 1.6.0 ist es möglich, alle Parameter in Swagger anzuzeigen und zu verwenden.
    • GET /api/[controller]/{id} um ein Objekt per id zu erhalten
  • Full CRUD Controller ( BasicCrudController ) = Basic Read Controller ( BasicReadController ) + Create , Update und Delete Vorgängen:
    • POST /api/[controller] - Für die Erstellung neuer Objekte
    • PUT /api/[controller]/{id} - für bearbeitungsobjekt durch id bearbeiten
    • DELETE /api/[controller]/{id} - Für das Löschen von Objekt durch ID
  • Voller CRUD mit Bulk -Operationen (Operationen über mehrere Objekte gleichzeitig), Basisklasse - BasicBulkCrudController = Basic Lesecontroller ( BasicReadController ) + BulkCreate , BulkUpdate und BulkDelete -Operationen:
    • POST /api/bulk/[controller] - Für die Erstellung neuer Objekte
    • PUT /api/bulk/[controller] - Für Bearbeiten von Objekten, die in eine Anforderungsbehörde geleitet werden
    • DELETE /api/bulk/[controller]/{idList} - Für das Löschen mehrerer Objekte durch ID löschen.

  Controllers -Klassen erwarten, dass der gesamte Betrieb mit Managerklassen durchgeführt wird (jeder Controller muss seinen eigenen Manager haben).

• Manager Klassen - Klassen, die die Geschäftslogik der Anwendung implementiert

  • IModelManager - Schnittstelle, die grundlegende Operationen beschreibt
  • EfModelManager - ist eine abstrakte Klasse, die die Implementierung von Get & Delete von Operationen enthält
  • EfSoftRemovableModelManager ist eine abstrakte Klasse, die die Implementierung von Get und Delete Operationen mit weichen abnehmbaren Modellen enthält ( IsDeleted = true Means -Modell wurde entfernt)

Beispiel dafür, wie schneller Masse gegenüber Nicht-Bulk:

 Elapsed time in Non-Bulk REST API with EF is 0.9759984016418457 secs.
Elapsed time in Bulk API with EF is 0.004002094268798828 secs.

Infolgedessen haben wir fast ~ 250 x schneller API .

3. Anforderungen

Es gibt nur eine Anforderung : Alle Entitätsklassen für jede Persistenzspeicherung, die mit Controllern und Managern verwendet werden, müssen IModelIdentifiable<T> aus Wissance.WebApiToolkit.Data.Entity implementiert. Wenn dieses Toolkit mit EntityFramework verwendet werden sollte, sollten Sie Ihren Ressourcenmanager von EfModelManager abgeben. Es verfügt über integrierte Methoden für:

• get many Artikel
• get one Artikel by id
• Element by id delete

4. Toolkit -Nutzungsalgorithmus mit EntityFramework

Das vollständige Beispiel wird in Abschnitt 6 erwähnt (siehe unten). Wenn Sie jedoch anfangen, eine neue REST Resource API zu erstellen, sollten Sie folgen:

1. Erstellen Sie eine model ( entity ) implementieren IModelIdentifiable<T> und DTO -Klasse für die IT -Darstellung ( für weiche Entfernen fügen auch IModelSoftRemovable -Implementierung hinzu), dh:

 public class BookEntity : IModelIdentifiable < int >
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } // for simplicity
    public DateTimeOffset Created { get ; set ; }
    public DateTimeOffset Updated { get ; set ; }
}

public class BookDto
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } 
}

2. Erstellen Sie eine Fabrikfunktion (dh statische Funktion einer statischen Klasse), die Model in DTO umwandelt, dh:

 public static class BookFactory
{
    public static BookDto Create ( BookEntity entity )
    {
        return new BookDto
        {
            Id = entity . Id ,
            Title = entity . Title ,
            Authors = entity . Authors ;
        } ;
    }
}

3. Erstellen Sie die IModelContext -Schnittstelle, in der Sie als DbSet und IT IS Implementierungsklasse BookEntity , die auch von DbContext ( EF -Abstract -Klasse ) abgeleitet ist:

 public interface IModelContext
{
    DbSet < BookEntity > Books { get ; set ; }
}

public MoidelContext : DbContext < ModelContext > , IModelContext
{
    // todo: not mrntioned here constructor, entity mapping and so on
    public DbSet < BookEntity > Books { get ; set ; }
}

4. Konfigurieren Sie, um ModelContext als DbContext über DI zu injizieren, siehe Start -up -Klasse
5. Erstellen Sie Controller -Klasse und ein Managerklassenpaar, dh hier in Betracht ziehen Full CRUD

 [ ApiController ]
public class BookController : BasicCrudController < BookDto , BookEntity , int , EmptyAdditionalFilters >
{
    public BookController ( BookManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private BookManager _manager ;
}

public class BookManager : EfModelManager < BookEntity , BookDto , int , EmptyAdditionalFilters >
{
    public BookManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , BookFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }
    
    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        // todo: implement
    }
    
    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        // todo: implement
    }
    
    private readonly ModelContext _modelContext ;
}

Letzter generischer Parameter im obigen Beispiel - EmptyAdditionalFilters ist eine Klasse, die zusätzliche Parameter für die Suche in Swagger enthält. Geben Sie einfach eine neue Klasse an, die IReadFilterable IE implementiert, dh:

 public class BooksFilterable : IReadFilterable
{
    public IDictionary < string , string > SelectFilters ( )
    {
            IDictionary < string , string > additionalFilters = new Dictionary < string , string > ( ) ;
            if ( ! string . IsNullOrEmpty ( Title ) )
            {
                additionalFilters . Add ( FilterParamsNames . TitleParameter , Title ) ;
            }

            if ( Authors != null && Authors . Length > 0 )
            {
                additionalFilters . Add ( FilterParamsNames . AuthorsParameter , string . Join ( "," , Authors ) ) ;
            }

            return additionalFilters ;
    }
        
    [ FromQuery ( Name = "title" ) ] public string Title { get ; set ; }
    [ FromQuery ( Name = "author" ) ] public string [ ] Authors { get ; set ; }
}

5. Nuget -Paket

Hier finden Sie Nuget-Package

6. Beispiele

Hier betrachten wir nur vollständige CRUD -Controller, da Full CRUD = LEAD + zusätzliche Vorgänge (erstellen, aktualisieren, löschen) , eine vollständige Beispiele = Vollständiger Anwendung, die mit Wissance erstellt wurde.

 [ ApiController ]
public class StationController : BasicCrudController < StationDto , StationEntity , int , EmptyAdditionalFilters >
{
    public StationController ( StationManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private StationManager _manager ;
} 

 public class StationManager : EfModelManager < StationEntity , StationDto , int >
{
    public StationManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , StationFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }

    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            await _modelContext . Stations . AddAsync ( entity ) ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . Created , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station creation" , null ) ;

            }
        catch ( Exception e )
        {
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station creation: { e . Message } " , null ) ;
        }
    }

    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            StationEntity existingEntity = await _modelContext . Stations . FirstOrDefaultAsync ( s => s . Id == id ) ;
            if ( existingEntity == null )
            {
                return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . NotFound , $ "Station with id: { id } does not exists" , null ) ;
            }

            // Copy only name, description and positions, create measurements if necessary from MeasurementsManager
            existingEntity . Name = entity . Name ;
            existingEntity . Description = existingEntity . Description ;
            existingEntity . Latitude = existingEntity . Latitude ;
            existingEntity . Longitude = existingEntity . Longitude ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . OK , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station update" , null ) ;

        }
        catch ( Exception e )
        {
             return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station update: { e . Message } " , null ) ;
        }
            
    }

    private readonly ModelContext _modelContext ;
}

Nur 2 sehr einfache Klassen ^^ Verwenden von WebApitoolkit

7. API erweitern

7.1 Fügen Sie dem vorhandenen Controller neue Methoden hinzu

Bedenken Sie, dass wir unserem Controller Methodensuche hinzufügen möchten:

 [ HttpGet ]
[ Route ( "api/[controller]/search" ) ]
public async Task < PagedDataDto < BookDto > > > SearchAsync ( [ FromQuery ] string query , [ FromQuery ] int page , [ FromQuery ] int size )
{ 
    OperationResultDto < Tuple < IList < BookDto > , long > > result = await Manager . GetAsync ( page , size , query ) ;
    if ( result == null )
    {
        HttpContext . Response . StatusCode = ( int ) HttpStatusCode . InternalServerError ;
    }

    HttpContext . Response . StatusCode = result . Status ;
    return new PagedDataDto < TRes > ( pageNumber , result . Data . Item2 , GetTotalPages ( result . Data . Item2 , pageSize ) , result . Data . Item1 ) ;
} 

7.2 Fügen Sie Sicherheit hinzu, um Ihre API zu schützen

Wir haben ein zusätzliches Projekt zum Schutz API mit Keycloak OpenId-Connect . Übergeben Sie IHttpContextAccessor an die Manager und überprüfen Sie so etwas: ClaimsPrincipal principal = _httpContext.HttpContext.User;

8. Zusätzliche Materialien

Sie konnten unsere Artikel über die Verwendung von Toolkit sehen:

• Medium Artikel über v1.0.x Nutzung
• Dev.TO Artikel über v1.0.x Nutzung

9. Mitwirkende