Oktatóanyag: Vezérlőalapú webes API létrehozása a ASP.NET Core használatával

Készítette: Tim Deschryver és Rick Anderson

Ez az oktatóanyag az adatbázist használó vezérlőalapú webes API létrehozásának alapjait mutatja be. Az API-k ASP.NET Core-ban való létrehozásának másik módszere a minimális API-k létrehozása. Ha segítségre van szüksége a minimális API-k és a vezérlőalapú API-k közötti választáshoz, tekintse meg API-k áttekintését. A minimális API-k létrehozásáról a következő oktatóanyagban olvashat: Minimális API létrehozása ASP.NET Core használatával.

Overview

Ez az oktatóanyag a következő API-t hozza létre:

API	Description	A kérés tartalma	Válasz törzse
GET /api/todoitems	Az összes to-do elem lekérése	None	teendők tömbje
GET /api/todoitems/{id}	Elem lekérése azonosító alapján	None	Teendő elem
POST /api/todoitems	Új elem hozzáadása	Teendő elem	Teendő elem
PUT /api/todoitems/{id}	Meglévő elem frissítése	Teendő elem	None
DELETE /api/todoitems/{id}	Elem törlése	None	None

Az alábbi ábrán az alkalmazás tervezése látható.

Prerequisites

Visual Studio

• Visual Studio 2022 az ASP.NET és webfejlesztési feladatokkal.

  

Visual Studio Code

• Visual Studio Code
• C# fejlesztőkészlet a Visual Studio Code-hoz
• .NET 9 SDK

A Visual Studio Code utasításait macOS, Linux vagy Windows rendszeren is követheti. A Visual Studio Code-tól eltérő integrált fejlesztési környezet (IDE) használata esetén szükség lehet módosításokra.

Webes API-projekt létrehozása

Visual Studio

• A Fájl menüben válassza a Új>Projektlehetőséget.
• A keresőmezőbe írja be a Web API.
• Válassza a ASP.NET Core Web API sablont, majd válassza a Következőlehetőséget.
• Az új projekt konfigurálása párbeszédpanelen nevezze el a todoApi nevű projektet, és válassza a Tovább gombot.
• A További információk párbeszédpanelen:
  • Győződjön meg arról, hogy a keretrendszer.NET 9.0 (standard kifejezéstámogatás).
  • Ellenőrizze, hogy be van-e jelölve az OpenAPI-támogatás engedélyezése jelölőnégyzet.
  • Győződjön meg arról, hogy a Vezérlők használata (a minimális API-k használatához való törlés) jelölőnégyzet be van jelölve, be van jelölve.
  • Válassza a Create gombot.

NuGet-csomag hozzáadása

Az oktatóanyagban használt adatbázis támogatásához NuGet-csomagot kell hozzáadni.

• Az Eszközök menüben válassza a NuGet Package Manager > Megoldáshoz készült NuGet-csomagok kezeléselehetőséget.
• Válassza a Tallózás lapot.
• Írja be Microsoft.EntityFrameworkCore.InMemory a keresőmezőbe, majd válassza a Microsoft.EntityFrameworkCore.InMemory.
• Jelölje be a Project jelölőnégyzetet a jobb oldali panelen, majd válassza a Telepítéslehetőséget.

Visual Studio Code

• Nyissa meg a integrált terminál.

• Változtassa meg a könyvtárat (cd) arra a mappára, amely tartalmazni fogja a projektmappát.

• Futtassa az alábbi parancsot:

  dotnet new webapi --use-controllers -o TodoApi
  cd TodoApi
  dotnet add package Microsoft.EntityFrameworkCore.InMemory
  code -r .
  

  Ezek a parancsok:

  • Hozzon létre egy új webes API-projektet, és nyissa meg a Visual Studio Code-ban.
  • Adjon hozzá egy NuGet-csomagot, amely a következő szakaszhoz szükséges.
  • Nyissa meg a TodoApi mappát a Visual Studio Code aktuális példányában.

A Visual Studio Code megjeleníthet egy párbeszédpanelt, amely a következő kérdést teszi fel: Megbízik a mappában lévő fájlok szerzőiben?

• Ha megbízik a szülőmappában lévő összes fájlban, válassza a Bízzon meg a szülőmappában lévő összes fájl szerzőiben.
• Válassza Igen, bízom a szerzőkben mivel a projektmappában a .NET által létrehozott fájlok találhatók.
• Amikor a Visual Studio Code azt kéri, hogy adjon hozzá eszközöket a projekt létrehozásához és hibakereséséhez, válassza az Igenlehetőséget. Ha a Visual Studio Code nem kínál buildelési és hibakeresési eszközök hozzáadását, válassza a Nézet>Parancskatalógus lehetőséget, és írja be a ".NET" kifejezést a keresőmezőbe. A parancsok listájában válassza ki a .NET: Generate Assets for Build and Debug parancsot.

A Visual Studio Code egy .vscode mappát ad hozzá a létrehozott launch.json és tasks.json fájlokkal.

Note

A csomagok .NET-alkalmazásokhoz való hozzáadásáról a Csomagok telepítése és kezeléseCsomaghasználati munkafolyamat (NuGet-dokumentáció)című cikkben talál útmutatást. Ellenőrizze a megfelelő csomagverziókat a NuGet.org.

A projekt futtatása

A projektsablon létrehoz egy WeatherForecast API-t az OpenAPI támogatásával.

Visual Studio

Nyomja le a Ctrl+F5 billentyűkombinációt a hibakereső nélküli futtatáshoz.

A Visual Studio az alábbi párbeszédpanelt jeleníti meg, ha egy projekt még nincs ssl használatára konfigurálva:

Válassza Igen lehetőséget, ha megbízik az IIS Express SSL-tanúsítványban.

A következő párbeszédpanel jelenik meg:

Válassza Igen lehetőséget, ha elfogadja, hogy megbízik a fejlesztési tanúsítványban.

A Firefox böngésző megbízhatóságáról további információt a Firefox SEC_ERROR_INADEQUATE_KEY_USAGE tanúsítványhibacímű témakörben talál.

A Visual Studio elindít egy terminálablakot, és megjeleníti a futó alkalmazás URL-címét. Az API a https://localhost:<port> címen van elhelyezve, ahol a projekt létrehozásakor a <port> véletlenszerűen kiválasztott portszám.

...
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: https://localhost:7260
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: http://localhost:7261
info: Microsoft.Hosting.Lifetime[0]
   Application started. Press Ctrl+C to shut down.
...

Ctrl+kattintson a kimenetben található HTTPS URL-címre a webalkalmazás böngészőben való teszteléséhez. Nincs végpont, https://localhost:<port>ezért a böngésző a HTTP 404 Not Found értéket adja vissza.

Fűzze hozzá /weatherforecast az URL-címet a WeatherForecast API teszteléséhez. A böngésző a következő példához hasonlóan jeleníti meg a JSON-t:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Visual Studio Code

• Az alábbi parancs futtatásával bízza meg a HTTPS-fejlesztési tanúsítványt:

  dotnet dev-certs https --trust
  

  Az előző parancs a következő párbeszédpanelt jeleníti meg, feltéve, hogy a tanúsítvány korábban nem volt megbízható:

  

• Válassza Igen lehetőséget, ha elfogadja, hogy megbízik a fejlesztési tanúsítványban.

  További információt a SSL- kényszerítése című cikk szakaszában talál, amely a ASP.NET core HTTPS-fejlesztési tanúsítvány megbízhatóságát ismerteti.

A Firefox böngésző megbízhatóságáról további információt a Firefox SEC_ERROR_INADEQUATE_KEY_USAGE tanúsítványhibacímű témakörben talál.

Futtassa az alkalmazást:

• Futtassa a következő parancsot az alkalmazás elindításához a https profilban:

  dotnet run --launch-profile https
  

A kimenet az alábbihoz hasonló üzeneteket jelenít meg, amelyek azt jelzik, hogy az alkalmazás fut, és várja a kéréseket:

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

• Ctrl+kattintson a kimenetben található HTTPS URL-címre a webalkalmazás böngészőben való teszteléséhez.

• A rendszer elindítja az alapértelmezett böngészőt a https://localhost:<port> URL-re, ahol a <port> a véletlenszerűen kiválasztott portszám, amely a kimenetben jelenik meg. Nincs végpont, https://localhost:<port>ezért a böngésző a HTTP 404 Not Found értéket adja vissza.

• Fűzze hozzá /weatherforecast az URL-címet a WeatherForecast API teszteléséhez. A böngésző a következő példához hasonlóan jeleníti meg a JSON-t:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

• Miután az alábbi utasítással tesztelte a webalkalmazást, zárja be a CtrlC+ az integrált terminálban.

A projekt tesztelése

Visual Studio

Ez az oktatóanyag az Endpoints Explorer-t és a .http fájlokat használja az API teszteléséhez.

Visual Studio Code

API-tesztelési felhasználói felület létrehozása a Swaggerrel

Számos elérhető webes API-tesztelési eszköz közül választhat, és az oktatóanyag bevezető API-tesztelési lépéseit az előnyben részesített eszközzel követheti.

Ez az oktatóanyag az NSwag.AspNetCore .NET-csomagot használja, amely integrálja a Swagger-eszközöket az OpenAPI-specifikációhoz tartozó tesztelési felhasználói felület létrehozásához:

• NSwag: .NET-kódtár, amely közvetlenül integrálja a Swaggert ASP.NET Core-alkalmazásokba, köztes szoftvereket és konfigurációt biztosítva.
• Swagger: Olyan nyílt forráskódú eszközök készlete, mint az OpenAPIGenerator és a SwaggerUI, amelyek az OpenAPI-specifikációt követő API-tesztoldalakat hoznak létre.
• OpenAPI-specifikáció: Az API képességeit leíró dokumentum a vezérlők és modellek XML- és attribútumjegyzetei alapján.

Az OpenAPI és az NSwag ASP.NET-tel való használatával kapcsolatos további információkért tekintse meg az ASP.NET Core webes API-dokumentációját a Swagger/OpenAPI-val.

A Swagger eszközkészlet telepítése

• Futtassa a következő parancsot:

  dotnet add package NSwag.AspNetCore
  

Az előző parancs hozzáadja az NSwag.AspNetCore csomagot, amely swagger-dokumentumok és felhasználói felület létrehozásához szükséges eszközöket tartalmaz. Mivel a projektünk az OpenAPI-t használja, csak az NSwag csomagot használjuk a Swagger UI generálásához.

Swagger köztes szoftver konfigurálása

• A Program.cs elemen belül adja hozzá a következő kiemelt kódot:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}

A korábbi kód bekapcsolja a Swagger middleware-t a generált JSON dokumentum szolgáltatásához a Swagger UI segítségével. A Swagger csak fejlesztési környezetben engedélyezett. A Swagger éles környezetben való engedélyezése potenciálisan bizalmas részleteket tehet közzé az API szerkezetéről és implementációjáról.

Az alkalmazás az OpenApi által generált és a /openapi/v1.json helyen található OpenAPI dokumentumot használja a felhasználói felület előállításához. Tekintse meg a projekt futása közben a WeatherForecast API generált OpenAPI specifikációját a böngészőjében a https://localhost:<port>/openapi/v1.json oldalra navigálva.

Az OpenAPI specifikáció egy JSON formátumú dokumentum, amely leírja az API struktúráját és képességeit, beleértve a végpontokat, a kérések/válaszok formátumait, a paramétereket és egyebeket. Alapvetően az API-jának tervrajza, amelyet különféle eszközök használhatnak az API megértéséhez és azzal való interakcióhoz.

Modellosztály hozzáadása

A modell olyan osztályok készlete, amelyek az alkalmazás által kezelt adatokat képviselik. Az alkalmazás modellje az TodoItem osztály.

Visual Studio

• A Megoldáskezelő-ben kattintson a jobb gombbal a projektre. Válassza >Új mappa hozzáadásalehetőséget. Nevezze el a mappát Models.
• Kattintson a jobb gombbal a Models mappára, és válassza a Hozzáadás>Osztályt lehetőséget. Nevezze el a TodoItem osztályt, és válassza a Hozzáadás lehetőséget.
• Cserélje le a sablonkódot a következőre:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Visual Studio Code

• Adjon hozzá egy Modelsnevű mappát.
• Adjon hozzá egy TodoItem.cs fájlt a Models mappához a következő kóddal:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

A Id tulajdonság egy relációs adatbázis egyedi kulcsaként működik.

Modelosztályok bárhová elhelyezhetők a projektben, de a Models mappát hagyományosan az előírások szerint használják.

Adatbázis-környezet hozzáadása

Az adatbázis-környezet az a fő osztály, amely koordinálja az entitás-keretrendszer funkcióit egy adatmodellhez. Ez az osztály az osztályból Microsoft.EntityFrameworkCore.DbContext származtatva jön létre.

Visual Studio

• Kattintson a jobb gombbal a Models mappára, és válassza a Hozzáadás>Osztályt lehetőséget. Nevezze el a TodoContext osztályt, és kattintson a Hozzáadás gombra.

• Írja be a következő kódot:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Visual Studio Code

• Adjon hozzá egy TodoContext.cs fájlt a Models mappához.

• Írja be a következő kódot:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Az adatbázis-környezet regisztrálása

Az ASP.NET Core-ban az olyan szolgáltatásokat, mint a DB-környezet, regisztrálni kell a függőséginjektálási (DI) tárolóban. A tároló biztosítja a szolgáltatást a vezérlők számára.

Frissítse Program.cs a következő kiemelt kóddal:

Visual Studio

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));

// <snippet_UseSwagger>
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}
// </snippet_UseSwagger>

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Az előző kód:

• using irányelveket ad hozzá.
• Hozzáadja az adatbázis-környezetet a DI-tárolóhoz.
• Megadja, hogy az adatbázis-környezet memórián belüli adatbázist használjon.

Vezérlő állványzata

Visual Studio

• Kattintson a jobb gombbal a Controllers mappára.

• Válassza a Hozzáadás lehetőséget>New Scaffolded Item.

• Válassza a műveletekkel rendelkező API-vezérlőt az Entity Framework használatával, majd válassza a Hozzáadás lehetőséget.

• Az Api Controller hozzáadása műveletekkel az Entity Framework párbeszédpanelen :

  • Válassza a TodoItem (TodoApi.Models) lehetőséget a Modell osztályban.
  • Válassza a TodoContext (TodoApi.Models) lehetőséget az Adatkörnyezet osztályban.
  • Válassza a Hozzáadás lehetőséget.

  Ha az állványozási művelet sikertelen, kattintson a Hozzáadás gombra, hogy újra megpróbálja az állványozást.

Ez a lépés hozzáadja a Microsoft.VisualStudio.Web.CodeGeneration.Design és a Microsoft.EntityFrameworkCore.Tools NuGet-csomagokat a projekthez. Ezek a csomagok az állványozáshoz szükségesek.

Visual Studio Code

Győződjön meg arról, hogy az összes eddigi módosítás mentése megtörtént.

• Kattintson a jobb gombbal (vagy kattintson a macOS parancsra) a TodoAPI-projektre , és válassza a Megnyitás a terminálban lehetőséget. A terminál megnyílik a TodoAPI projektmappában. Futtassa az alábbi parancsot:

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

Az előző parancsok:

• Adja hozzá az állványzathoz szükséges NuGet-csomagokat.
• Telepítse az állványozási mechanizmust (dotnet-aspnet-codegenerator) az esetleges korábbi verziók eltávolítása után.

Linux esetén adja hozzá a .NET-eszközök könyvtárát a rendszerútvonalhoz a következő paranccsal:

echo 'export PATH=$HOME/.dotnet/tools:$PATH' >> ~/.bashrc
source ~/.bashrc

Note

Alapértelmezés szerint a telepíteni kívánt .NET bináris fájlok architektúrája a jelenleg futó operációsrendszer-architektúrát jelöli. Ha másik operációsrendszer-architektúrát szeretne megadni, tekintse meg dotnet eszköz telepítését, az --arch lehetőséget. További információ: GitHub-probléma dotnet/AspNetCore.Docs #29262.

Készítse el a projektet.

Futtassa a következő parancsot:

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

Az előző parancs felépíti a TodoItemsController.

A létrehozott kód:

• Az osztály megjelölése az [ApiController] attribútummal. Ez az attribútum azt jelzi, hogy a vezérlő válaszol a webes API-kérésekre. Az attribútum által lehetővé tetső konkrét viselkedésekkel kapcsolatos információkért lásd: Webes API-k létrehozása ASP.NET Core használatával.
• A DI használatával injektálja az adatbázis-környezetet (TodoContext) a vezérlőbe. Az adatbázis-környezet a vezérlőben található CRUD-metódusok mindegyikében használatos.

A ASP.NET Core-sablonok a következőhöz:

• A nézetekkel rendelkező vezérlők szerepelnek [action] az útvonalsablonban.
• Az API-vezérlők nem szerepelnek [action] az útvonalsablonban.

Ha a [action] jogkivonat nem szerepel az útvonalsablonban, a művelet neve (metódus neve) nem szerepel a végpontban. Vagyis a művelet társított metódusneve nem szerepel az egyező útvonalban.

A PostTodoItem létrehozási metódus frissítése

Frissítse a visszatérési utasítást a PostTodoItem úgy, hogy a nameof operátort használja:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Az előző kód egy HTTP POST metódus, amelyet az [HttpPost] attribútum jelez. A metódus lekéri a TodoItem értékét a HTTP-kérés törzséből.

További információ: Attribútum-útválasztás Http[Verb] attribútumokkal.

A CreatedAtAction módszer:

• Ha sikeres, egy HTTP 201-állapotkódot ad vissza. HTTP 201 egy olyan metódus szokásos válasza HTTP POST , amely új erőforrást hoz létre a kiszolgálón.
• Hely fejlécet ad hozzá a válaszhoz. A Location fejléc az újonnan létrehozott to-do elem URI-ját adja meg. További információ: 10.2.2 201 Létrehozás.
• A GetTodoItem fejléc URI-jának létrehozásához a Location műveletre hivatkozik. A C# nameof -kulcsszóval elkerülhető, hogy a hívásban CreatedAtAction a művelet neve nehezen kódolódjon.

PostTodoItem tesztelése

Visual Studio

• Válassza a Nézet>Egyéb ablakok>Endpoints Explorer.

• Kattintson a jobb gombbal a POST végpontra, és válassza a Kérés létrehozásalehetőséget.

  

  Egy új fájl jön létre a TodoApi.httpnevű projektmappában, amely a következő példához hasonló tartalommal rendelkezik:

  @TodoApi_HostAddress = https://localhost:49738
  
  POST {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

  • Az első sor létrehoz egy változót, amelyet az összes végponthoz használnak.
  • A következő sor egy POST-kérést határoz meg.
  • A POST kérelemsor utáni sorok határozzák meg a fejléceket és a kérelem törzsének helyőrzőit.
  • A tripla hashtag (###) sor egy kérések közötti elválasztó jel: ami utána következik, az egy másik kéréshez tartozik.

• A POST-kérelem elvár egy TodoItem. A teendő definiálásához cserélje le a //TodoItem megjegyzést az alábbi JSON-ra:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

  A TodoApi.http fájlnak most az alábbi példához hasonlóan kell kinéznie, de a portszámmal:

  @TodoApi_HostAddress = https://localhost:7260
  
  Post {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    "name": "walk dog",
    "isComplete": true
  }
  
  ###
  

• Nyisd meg az alkalmazást.

• Válassza a Kérés küldése hivatkozást, amely a POST kérelemsor felett található.

  

  A POST kérést a rendszer elküldi az alkalmazásnak, és a válasz megjelenik a Válasz panelen.

  

Visual Studio Code

• Ha az alkalmazás még mindig fut, a böngészőben navigáljon a https://localhost:<port>/swagger oldalra, hogy megjelenítse a Swagger által létrehozott API-tesztelő oldalt. Kattintson a TodoItems elemre a műveletek kibontásához.

  

• A Swagger API tesztelési oldalán válassza a Post /api/todoitems>Try it out lehetőséget.

• Vegye figyelembe, hogy a Kérelem törzs mező egy létrehozott példaformátumot tartalmaz, amely az API paramétereit tükrözi.

• A kérelem törzsében adja meg a JSON-t egy to-do elemhez az opcionális idmegadása nélkül:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

• Válassza a Végrehajtás lehetőséget.

  

• A Swagger Válaszok panelt biztosít a Végrehajtás gomb alatt.

  

Jegyezze fel néhány hasznos részletet:

• cURL: A Swagger egy példa cURL-parancsot biztosít a Unix/Linux szintaxisban, amely futtatható a parancssorban bármilyen Unix/Linux szintaxist használó Bash-felülettel, beleértve a Git Basht Git for Windows.
• Kérelem URL-címe: A Swagger UI JavaScript-kódja által az API-híváshoz küldött HTTP-kérés egyszerűsített ábrázolása. A tényleges kérések tartalmazhatnak olyan részleteket, mint a fejlécek és a lekérdezési paraméterek, valamint a kérelem törzse.
• Kiszolgáló válasza: Tartalmazza a válasz törzsét és fejléceit. A válasz törzse azt mutatja, hogy a id1 értékre lett állítva.
• Válaszkód: A rendszer egy 201-HTTP állapotkódot adott vissza, amely azt jelzi, hogy a kérés feldolgozása sikeresen megtörtént, és egy új erőforrás létrehozását eredményezte.

A hely fejlécének URI-jának tesztelése

Visual Studio

Tesztelje az alkalmazást a GET végpontok böngészőből való meghívásával vagy Endpoints Explorerhasználatával. Az alábbi lépések a Endpoints Explorer-hez tartoznak.

• Az Endpoints Explorerterületen kattintson a jobb gombbal az első GET végpontra, és válassza a Kérés létrehozásalehetőséget.

  A következő tartalom lesz hozzáadva a TodoApi.http fájlhoz:

  GET {{TodoApi_HostAddress}}/api/todoitems
  
  ###
  

• Válassza a Kérés küldése hivatkozást, amely az új GET kérelemsor felett található.

  A GET kérést a rendszer elküldi az alkalmazásnak, és a válasz megjelenik a Válasz panelen.

• A válasz törzse a következő JSON-hoz hasonló:

  [
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true
    }
  ]
  

• Az Endpoints Explorerterületen kattintson a jobb gombbal a /api/todoitems/{id}GET végpontra, és válassza a Kérés létrehozásalehetőséget. A következő tartalom lesz hozzáadva a TodoApi.http fájlhoz:

  @id=0
  GET {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Rendeld hozzá a {@id}-t a 1-hoz (a 0 helyett).

• Válassza a Kérés küldése hivatkozást, amely az új GET kérelemsor felett található.

  A GET kérést a rendszer elküldi az alkalmazásnak, és a válasz megjelenik a Válasz panelen.

• A válasz törzse a következő JSON-hoz hasonló:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

Visual Studio Code

Tesztelje az alkalmazást úgy, hogy meghívja a végpontokat egy böngészőből vagy egy Swaggerből.

• A Swaggerben válassza a GET /api/todoitems>Try it out>Execute (Végrehajtás) lehetőséget.

• Másik lehetőségként hívja meg a GET /api/todoitems parancsot egy böngészőből az URI https://localhost:<port>/api/todoitemsbeírásával. Például: https://localhost:7260/api/todoitems

A GET /api/todoitems hívása a következőhöz hasonló választ ad:

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

• Hívja meg a GET /api/todoitems/{id} függvényt a Swaggerben egy adott azonosító adatainak visszaadásához:

  • Válassza a GET /api/todoitems>Kipróbálás lehetőséget.
  • Állítsa be a azonosító mezőt 1-re, és válassza a Végrehajtáslehetőséget.

• Másik lehetőségként hívja meg a GET /api/todoitems parancsot egy böngészőből az URI https://localhost:<port>/api/todoitems/1beírásával. Például: https://localhost:7260/api/todoitems/1

• A válasz a következőhöz hasonló:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

A GET metódusok vizsgálata

Két GET-végpont implementálva van:

• GET /api/todoitems
• GET /api/todoitems/{id}

Az előző szakasz egy példát mutatott az útvonalra /api/todoitems/{id} .

Kövesse a POST utasításait egy másik teendőelem hozzáadásához, majd tesztelje az útvonalat a /api/todoitems Swagger használatával.

Ez az alkalmazás memórián belüli adatbázist használ. Ha az alkalmazás le van állítva és elindult, az előző GET kérés nem ad vissza adatokat. Ha az alkalmazás nem ad vissza adatot, küldjön POST adatokat az alkalmazásnak.

Útválasztás és URL-útvonalak

Az [HttpGet] attribútum egy kérésre válaszoló metódust HTTP GET jelöl. Az egyes metódusok URL-elérési útja a következőképpen jön létre:

• Kezdje a sablonsztringgel a vezérlő attribútumában Route :

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Cserélje le [controller] a vezérlő nevét, amely konvenció szerint a vezérlőosztály neve mínusz a "Controller" utótag. Ebben a mintában a vezérlőosztály neve TodoItemsController, így a vezérlő neve "TodoItems". ASP.NET Core útválasztás nem érzékeny a kis- és nagybetűkre.

• Ha az [HttpGet] attribútum rendelkezik útvonalsablonnal (például [HttpGet("products")]), fűzze hozzá az elérési úthoz. Ez a minta nem használ sablont. További információ: Attribútum-útválasztás Http[Verb] attribútumokkal.

Az alábbi GetTodoItem metódus "{id}" a to-do elem egyedi azonosítójának helyőrző változója. Amikor meghívják GetTodoItem, az URL-címben "{id}" értéke megadva a metódus id paraméterében.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Visszaadott értékek

A `GetTodoItems` és `GetTodoItem` metódusok visszatérési típusa ActionResult<T> típusú. ASP.NET Core automatikusan szerializálja az objektumot JSON formátumra, és beírja a JSON-t a válaszüzenet törzsébe. A visszatérési típus válaszkódja 200 OK, feltéve, hogy nincsenek kezeletlen kivételek. A nem kezelt kivételek 5xx-hibákká lesznek lefordítva.

ActionResult A visszatérési típusok a HTTP-állapotkódok széles skáláját jelölhetik. A GetTodoItem például két különböző állapotértéket adhat vissza:

• Ha egyetlen elem sem felel meg a kért azonosítónak, a metódus egy 404-NotFound hibakódot ad vissza.
• Ellenkező esetben a metódus egy JSON-válasz törzsével adja vissza a 200-t. Az item eredmény visszaadása esetén HTTP 200 választ kapunk.

A PutTodoItem metódus

Vizsgálja meg a PutTodoItem metódust:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem hasonló PostTodoItem-hoz/-hez, kivéve, hogy HTTP PUT-t használ. A válasz 204 (nincs tartalom). A HTTP-specifikáció szerint a PUT kéréshez az ügyfélnek a teljes frissített entitást kell elküldenie, nem csak a módosításokat. A részleges frissítések támogatásához használja HTTP PATCH.

A PutTodoItem metódus tesztelése

Ez a minta egy memórián belüli adatbázist használ, amelyet az alkalmazás minden indításakor inicializálni kell. Az adatbázisnak tartalmaznia kell egy elemet, mielőtt PUT-hívást kezdeményezne. A GET hívásával győződjön meg arról, hogy van egy elem az adatbázisban, mielőtt PUT-hívást kezdeményez.

Használja a PUT metódust az TodoItem azonosítóval rendelkező elem frissítéséhez, amelynek Id = 1, és állítsa be a nevét "feed fish". Vegye figyelembe, hogy a válasz HTTP 204 No Content.

Visual Studio

• Az Endpoints Explorer-ben kattintson a jobb gombbal a PUT végpontra, és válassza a Kérés létrehozásalehetőséget.

  A következő tartalom lesz hozzáadva a TodoApi.http fájlhoz:

  PUT {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

• A PUT kérelemsorban cserélje le a {{id}}1.

• Cserélje le a //TodoItem helyőrzőt a következő sorokra:

  PUT {{TodoApi_HostAddress}}/api/todoitems/1
  Content-Type: application/json
  
  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Válassza a Kérés küldése hivatkozást, amely az új PUT kérelemsor felett található.

  A PUT kérést a rendszer elküldi az alkalmazásnak, és a válasz megjelenik a Válasz panelen. A válasz törzse üres, az állapotkód pedig 204.

Visual Studio Code

PUT-kérés küldése a Swagger használatával:

• Válassza a Put /api/todoitems/{id}>Próbálja ki.

• Állítsa be a azonosító mezőjét 1értékre.

• Állítsa a kérelem törzsét a következő JSON-ra:

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Válassza a Végrehajtás lehetőséget.

A DeleteTodoItem metódus

Vizsgálja meg a DeleteTodoItem metódust:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

A DeleteTodoItem metódus tesztelése

DELETE A metódus használatával törölheti az TodoItem azonosító = 1 azonosítót. Vegye figyelembe, hogy a válasz HTTP 204 No Content.

Visual Studio

• Az Endpoints Explorerterületen kattintson a jobb gombbal a DELETE végpontra, és válassza a Kérés létrehozásalehetőséget.

  Hozzá van adva egy DELETE kérés a TodoApi.http-hoz.

• A {{id}} helyett 1-et használjon a DELETE kérelemsorban. A DELETE kérésnek a következő példához hasonlóan kell kinéznie:

  DELETE {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Válassza a Küldési kérelem hivatkozást a DELETE kéréshez.

  A DELETE kérést a rendszer elküldi az alkalmazásnak, és a válasz megjelenik a Válasz panelen. A válasz törzse üres, az állapotkód pedig 204.

Visual Studio Code

DELETE-kérés küldése a Swagger használatával:

• Válassza a DELETE /api/todoitems/{id}>Próbálja ki.

• Állítsa be a azonosító mezőt 1, és válassza a Végrehajtáslehetőséget.

  A DELETE kérést elküldik az alkalmazásnak, és a válasz megjelenik a Válaszok panelen. A válasz törzse üres, és a kiszolgáló válasza állapotkódja 204.

Tesztelés más eszközökkel

Számos más eszköz is használható a webes API-k tesztelésére, például:

• http-repl
• curl. Swagger a(z) curl használja, és megjeleníti az curl parancsokat, amelyeket elküld.
• Fiddler

Túlküldés megakadályozása

A mintaalkalmazás jelenleg a teljes TodoItem objektumot teszi elérhetővé. Az éles alkalmazások általában szabályozzák az adatok bevitelét és visszaadását a modell egy részhalmazával. Ennek több oka is van, és a biztonság a legfontosabb. A modell részhalmazát általában adatátviteli objektumnak (DTO), bemeneti modellnek vagy nézetmodellnek nevezzük. Ebben az oktatóanyagban DTO-t használunk.

A DTO a következő célra használható:

• A túlküldés megakadályozása.
• Elrejtheti az ügyfelek által nem megtekinteni kívánt tulajdonságokat.
• Kihagy néhány tulajdonságot a hasznos adat méretének csökkentése érdekében.
• Beágyazott objektumokat tartalmazó objektumdiagramok simítása. Az egyszerűsített objektum gráfok kényelmesebbek lehetnek az ügyfelek számára.

A DTO-megközelítés bemutatásához frissítse a TodoItem osztályt egy titkos mezőre:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
    public string? Secret { get; set; }
}

A titkos mezőt el kell rejteni az alkalmazás elől, de egy felügyeleti alkalmazás dönthet úgy, hogy közzéteszi.

Ellenőrizze, hogy közzéteheti és lekérheti-e a titkos kód mezőt.

DTO-modell létrehozása Modellek/TodoItemsDTO.cs fájlban:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Frissítse a TodoItemsController használatát a TodoItemDTO-ra:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Ellenőrizze, hogy nem tudja-e közzétenni vagy lekérni a titkos kód mezőt.

A webes API meghívása JavaScript használatával

Lásd az oktatóanyagot: ASP.NET Core webes API meghívása JavaScript használatával.

Webes API videósorozat

Lásd Videó: Webes API-k kezdők számára.

Vállalati webalkalmazás-minták

A megbízható, biztonságos, teljesíthető, tesztelhető és méretezhető ASP.NET Core-alkalmazás létrehozásával kapcsolatos útmutatásért tekintse meg Vállalati webalkalmazás-mintákcímű témakört. Rendelkezésre áll egy teljesen felhasználásra kész példawebalkalmazás, amely implementálja a mintákat.

Hitelesítési támogatás hozzáadása webes API-hoz

ASP.NET Core Identity felhasználói felület (UI) bejelentkezési funkciót ad hozzá ASP.NET Core-webalkalmazásokhoz. A webes API-k és SPA-k védelméhez használja az alábbiak egyikét:

• Microsoft Entra-azonosító
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Szerver

A Duende Identity Server egy OpenID Connect- és OAuth 2.0-keretrendszer ASP.NET Core-hoz. A Duende Identity Server a következő biztonsági funkciókat teszi lehetővé:

• Hitelesítés szolgáltatásként (AaaS)
• Egyszeri bejelentkezés/kijelentkezés (SSO) több alkalmazástípuson keresztül
• Hozzáférés-vezérlés API-khoz
• Szövetségi átjáró

Important

Duende Software esetleg licencdíjat kérhet a Duende Identity Server üzemeltetési használatáért. További információ: Migrálás ASP.NET Core-ból .NET 5-ről .NET 6-ra.

További információ: Duende Identity Server dokumentációja (Duende Software webhely).

Közzététel az Azure-ban

Az Azure-ban való üzembe helyezésről további információért lásd: Gyorsútmutató: ASP.NET webalkalmazás üzembe helyezése.

További erőforrások

Az oktatóanyag mintakódjának megtekintése vagy letöltése. Tekintse meg , hogyan töltheti le.

További információt a következő források tartalmaznak:

• Webes API-k létrehozása az ASP.NET Core segítségével
• Oktatóanyag: Minimális API létrehozása ASP.NET Core
• A létrehozott OpenAPI-dokumentumok használata
• ASP.NET Core webes API dokumentáció Swaggerrel / OpenAPI-val
• Razor Az Entity Framework Core lapjai a ASP.NET Core-ban – 1. oktatóanyag a 8-ból
• ASP.NET Core vezérlőműveleteinek útválasztása
• A vezérlőműveletek visszatérési típusai az ASP.NET Core webes API-ban
• ASP.NET Core-alkalmazások üzembe helyezése az Azure App Service-
• ASP.NET Core tárhely létrehozása és üzembe helyezése
• Webes API létrehozása a ASP.NET Core használatával