Webes API-k létrehozása a ASP.NET Core használatával

ASP.NET Core támogatja a webes API-k vezérlőkkel vagy minimális API-k használatával történő létrehozását. A webes API-k vezérlői olyan osztályok, amelyek a következőből ControllerBaseszármaznak: . A vezérlők aktiválása és megsemmisítése kérésenként történik.

Ez a cikk bemutatja, hogyan használhat vezérlőket a webes API-kérések kezeléséhez. A webes API-k vezérlők nélküli létrehozásáról a következő oktatóanyagban olvashat: Minimális API létrehozása ASP.NET Core használatával.

Fontos

A ASP.NET Core 10-től kezdve az ismert API-végpontok már nem lesznek átirányítva a bejelentkezési lapokra hitelesítés használatakor cookie . Ehelyett 401/403 állapotkódokat adnak vissza. További részletekért lásd az API-végpontok hitelesítési viselkedését a ASP.NET Core-ban.

ControllerBase-osztály

A vezérlőalapú webes API egy vagy több vezérlőosztályból áll, amelyek ControllerBaseszármaznak. A webes API-projektsablon egy kezdővezérlőt biztosít:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

A webes API-vezérlőknek általában a ControllerBase-ból kell származniuk, nem pedig a Controller-ből. Controller ControllerBase származik, és támogatja a nézeteket, így a weblapok kezelésére szolgál, nem a webes API-kérelmekre. Ha ugyanannak a vezérlőnek támogatnia kell a nézeteket és a webes API-kat, akkor a következőből Controllerszármazik: .

A ControllerBase osztály számos olyan tulajdonságot és metódust biztosít, amelyek hasznosak a HTTP-kérések kezeléséhez. Például a CreatedAtAction egy 201-es állapotkódot ad vissza.

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Az alábbi táblázat példákat tartalmaz a metódusokra a következőben ControllerBase: .

Method	Notes
BadRequest	400 állapotkódot ad vissza.
NotFound	404-es állapotkódot ad vissza.
PhysicalFile	Egy fájlt ad vissza.
TryUpdateModelAsync	Modellkötés meghívása.
TryValidateModel	Modellérvényesítést hív meg.

Az összes elérhető metódus és tulajdonság listáját lásd ControllerBase: .

Attributes

A Microsoft.AspNetCore.Mvc névtér olyan attribútumokat biztosít, amelyek a webes API-vezérlők és műveleti módszerek viselkedésének konfigurálására használhatók. Az alábbi példa attribútumokkal adja meg a támogatott HTTP-műveleti parancsot és az esetlegesen visszaadható ismert HTTP-állapotkódokat:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{
    pet.Id = _petsInMemoryStore.Any() ? 
             _petsInMemoryStore.Max(p => p.Id) + 1 : 1;
    _petsInMemoryStore.Add(pet);

    return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}

Íme néhány további példa az elérhető attribútumokra.

Attribute	Notes
[Route]	Egy vezérlő vagy művelet URL-mintázatát adja meg.
[Bind]	Megadja a modellkötéshez felvenni kívánt előtagot és tulajdonságokat.
[HttpGet]	A HTTP GET művelet igét támogató műveletet azonosít.
[Consumes]	Megadja azokat az adattípusokat, amelyeket egy művelet elfogad.
[Produces]	Megadja a művelet által visszaadott adattípusokat.

Az elérhető attribútumokat tartalmazó listákért tekintse meg a Microsoft.AspNetCore.Mvc névteret.

ApiController attribútum

Az [ApiController] attribútum egy vezérlőosztályra alkalmazható a következő véleményezett, API-specifikus viselkedések engedélyezéséhez:

• Attribútum-útválasztási követelmény
• Automatikus HTTP 400-válaszok
• Kötés forrásparaméterének következtetése
• Többrészes/űrlapadat kérés megállapítása
• Hibaállapot-kódokkal kapcsolatos probléma részletei

Adott vezérlők attribútuma

Az [ApiController] attribútum adott vezérlőkre alkalmazható, ahogyan a projektsablon alábbi példájában is látható:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

Attribútum több vezérlőn

Az attribútumot egynél több vezérlőn is használhatja, ha létrehoz egy egyéni alapvezérlőosztályt, amely az [ApiController] attribútummal van eljegyzve. Az alábbi példa egy egyéni alaposztályt és egy belőle származó vezérlőt mutat be:

[ApiController]
public class MyControllerBase : ControllerBase
{
}

[Produces(MediaTypeNames.Application.Json)]
[Route("[controller]")]
public class PetsController : MyControllerBase

Attribútum egy összeállításban

Az [ApiController] attribútum alkalmazható egy szerelvényre. Amikor az [ApiController] attribútumot egy szerelvényre alkalmazza, a szerelvény összes vezérlője alkalmazza az [ApiController] attribútumot. Az egyes vezérlők nem választhatók ki. Alkalmazza a szerelvényszintű attribútumot a Program.cs fájlra:

using Microsoft.AspNetCore.Mvc;
[assembly: ApiController]

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Attribútum alapú útválasztás követelmény

Az [ApiController] attribútum követelménysé teszi az attribútum-útválasztást. Például:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

A műveletek nem érhetők el a , UseEndpoints és UseMvc által meghatározott hagyományos útvonalakon keresztül.

Automatikus HTTP 400-válaszok

Az [ApiController] attribútum automatikusan elindít egy HTTP 400-választ a modellérvényesítési hibák miatt. Ezért a következő kód szükségtelen egy műveletmetódusban:

if (!ModelState.IsValid)
{
    return BadRequest(ModelState);
}

ASP.NET Core MVC a ModelStateInvalidFilter műveletszűrővel hajtja végre az előző ellenőrzést.

Alapértelmezett BadRequest-válasz

A HTTP 400-válaszok alapértelmezett választípusa a következő ValidationProblemDetails. A szerializált típusra az alábbi választörzs mutat példát:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "|7fb5e16a-4c8f23bbfc974667.",
  "errors": {
    "": [
      "A non-empty request body is required."
    ]
  }
}

A ValidationProblemDetails típus:

• Géppel olvasható formátumot biztosít a webes API-válaszok hibáinak megadásához.
• Megfelel az RFC 7807 specifikációnak.

Az automatikus és egyéni válaszok konzisztenssé tétele érdekében a ValidationProblem metódust hívja meg ahelyett, hogy BadRequest. ValidationProblem objektumot ad vissza ValidationProblemDetails -ként, valamint az automatikus választ is.

Automatikus 400 válasz naplózása

Az automatikus 400 válasz naplózásához állítsa be a InvalidModelStateResponseFactory delegált tulajdonságot egyéni feldolgozásra. Alapértelmezés szerint InvalidModelStateResponseFactory a ProblemDetailsFactory létrehozásához a ValidationProblemDetails használja.

Az alábbi példa bemutatja, hogyan kérhető le egy ILogger<TCategoryName> példány, hogy naplózza egy automatikus 400-válasz adatait.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
      // To preserve the default behavior, capture the original delegate to call later.
        var builtInFactory = options.InvalidModelStateResponseFactory;

        options.InvalidModelStateResponseFactory = context =>
        {
            var logger = context.HttpContext.RequestServices
                                .GetRequiredService<ILogger<Program>>();

            // Perform logging here.
            // ...

            // Invoke the default behavior, which produces a ValidationProblemDetails
            // response.
            // To produce a custom response, return a different implementation of 
            // IActionResult instead.
            return builtInFactory(context);
        };
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Automatikus 400-válasz letiltása

Az automatikus 400 viselkedés letiltásához állítsa a SuppressModelStateInvalidFilter tulajdonságot a következőre: true. Adja hozzá a következő kiemelt kódot:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Kötés forrásparaméterének következtetése

A kötési forrásattribútum határozza meg azt a helyet, ahol egy műveleti paraméter értéke található. A következő kötési forrásattribútumok léteznek:

Attribute	Kötés forrása
[FromBody]	A kérés tartalma
[FromForm]	Űrlap adat a kérelem törzsében
[FromHeader]	Kérelem fejléce
[FromQuery]	Lekérdezési sztring paraméter kérése
[FromRoute]	Adatok átirányítása az aktuális kérelemből
[FromServices]	A kérelemszolgáltatás műveletparaméterként injektálva
[AsParameters]	Metódusparaméterek

Warning

Ne használja [FromRoute] , ha az értékek tartalmazhatnak %2f (azaz /). %2f nem lesz feloldva / formátumra. Akkor használja [FromQuery] , ha az érték tartalmazhat %2f.

Az ASP.NET Core futtatókörnyezet az [ApiController] vagy a kötési forrásattribútumok, mint [FromQuery], hiányában próbálja meg az összetett objektummodell-kötőt használni. Az összetett objektummodell-iratgyűjtő meghatározott sorrendben kér le adatokat az értékszolgáltatóktól.

Az alábbi példában az [FromQuery] attribútum azt jelzi, hogy a discontinuedOnly paraméter értéke a kérelem URL-címének lekérdezési sztringjében van megadva:

[HttpGet]
public ActionResult<List<Product>> Get(
    [FromQuery] bool discontinuedOnly = false)
{
    List<Product> products = null;

    if (discontinuedOnly)
    {
        products = _productsInMemoryStore.Where(p => p.IsDiscontinued).ToList();
    }
    else
    {
        products = _productsInMemoryStore;
    }

    return products;
}

Az [ApiController] attribútum következtetési szabályokat alkalmaz a műveleti paraméterek alapértelmezett adatforrásaira. Ezekkel a szabályokkal nem kell manuálisan azonosítania a kötési forrásokat, ha attribútumokat alkalmaz a műveleti paraméterekre. A kötési forrás következtetési szabályai az alábbiak szerint működnek:

• [FromServices] a DI-tárolóban regisztrált összetett típusú paraméterekre következtet.
• [FromBody] A rendszer a DI-tárolóban nem regisztrált összetett típusú paraméterekre következtet. A következtetési szabály alól kivételt [FromBody] képez minden összetett, beépített típus, amely speciális jelentéssel rendelkezik, például IFormCollection és CancellationToken. A kötés forráskódja figyelmen kívül hagyja ezeket a speciális típusokat.
• [FromForm] a függvény a következő típusú IFormFileIFormFileCollectionműveletparaméterekre következtet: Az egyszerű vagy felhasználó által definiált típusok esetében ez nem következik be.
• [FromRoute] következtetés vonható le bármely műveletparaméter-névre, amely megfelel egy paraméternek az útvonalsablonban. Ha egynél több útvonal megfelel egy műveleti paraméternek, a rendszer minden útvonalértéket figyelembe veszi [FromRoute].
• [FromQuery] következtetésre jut bármely más műveleti paraméter esetén.

FromBody következtetési megjegyzések

[FromBody] nem kerül kikövetkeztetésre egyszerű típusok esetén, mint például string vagy int. Ezért az [FromBody] attribútumot egyszerű típusokhoz kell használni, ha erre a funkcióra van szükség.

Ha egy művelethez egynél több paraméter van kötve a kérelemtörzsből, kivétel lép fel. Az alábbi műveletmetódus-aláírások például kivételt okoznak:

• [FromBody] mindkettőre egyel következtetett, mert ezek összetett adattípusok.

  [HttpPost]
  public IActionResult Action1(Product product, Order order)
  

• [FromBody] attribútum az egyiken, a másik pedig inferált, mert összetett típus.

  [HttpPost]
  public IActionResult Action2(Product product, [FromBody] Order order)
  

• [FromBody] attribútum mindkét elemen található.

  [HttpPost]
  public IActionResult Action3([FromBody] Product product, [FromBody] Order order)
  

FromServices következtetési megjegyzések

A paraméterkötés függőséginjektáláson keresztül köti meg a paramétereket, ha a típus szolgáltatásként van konfigurálva. Ez azt jelenti, hogy nem szükséges explicit módon alkalmazni az [FromServices] attribútumot egy paraméterre. A következő kódban mindkét művelet az időt adja vissza:

[Route("[controller]")]
[ApiController]
public class MyController : ControllerBase
{
    public ActionResult GetWithAttribute([FromServices] IDateTime dateTime) 
                                                        => Ok(dateTime.Now);

    [Route("noAttribute")]
    public ActionResult Get(IDateTime dateTime) => Ok(dateTime.Now);
}

Ritkán előfordulhat, hogy az automatikus DI megszakítja azokat az alkalmazásokat, amelyek a DI-ben olyan típusúak, amelyeket az API-vezérlő műveleti módszerei is elfogadnak. Nem gyakori, hogy egy típus szerepel a DI-ben, és argumentumként egy API-vezérlő műveletben.

Egy műveletparaméter következtetésének letiltásához alkalmazza a paraméterre a kívánt kötésforrás-attribútumot. Alkalmazza például az [FromBody] attribútumot egy olyan műveleti paraméterre, amelyet a kérelem törzsétől kell kötni.

Ha globálisan szeretné letiltani [FromServices] a következtetést, állítsa a DisableImplicitFromServicesParameters beállítást a következőre true:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddSingleton<IDateTime, SystemDateTime>();

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

var app = builder.Build();

app.MapControllers();

app.Run();

Az alkalmazás indításakor IServiceProviderIsService a rendszer ellenőrzi a típusokat annak megállapításához, hogy egy API-vezérlő művelet argumentuma a DI-ből vagy a többi forrásból származik-e.

Az API Controller műveleti paramétereinek kötési forrásának következtetésére szolgáló mechanizmus a következő szabályokat használja:

• A korábban megadott BindingInfo.BindingSource soha nem lesz felülírva.
• A di-tárolóban regisztrált összetett típusparaméter van hozzárendelve BindingSource.Services.
• A rendszer egy összetett típusparamétert rendel hozzá BindingSource.Body, amely nincs regisztrálva a DI-tárolóban.
• A rendszer hozzárendel egy olyan paramétert, amelynek neve útvonalértékként jelenik meg bármely útvonalsablonban BindingSource.Path.
• Az összes többi paraméter a következő BindingSource.Query: .

Következtetési szabályok letiltása

A kötési forrás következtetésének letiltásához állítsa a SuppressInferBindingSourcesForParameters következőre true:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
        options.DisableImplicitFromServicesParameters = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Többrészes/űrlapadat-kérelem következtetése

Az [ApiController] attribútum következtetési szabályt alkalmaz az IFormFile és IFormFileCollection típusú akcióparaméterekre. A multipart/form-data kérelem tartalomtípusa ezekre a típusokra következtet.

Az alapértelmezett viselkedés letiltásához állítsa a SuppressConsumesConstraintForFormFileParameters tulajdonságot a(z) true értékre:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Hibaállapot-kódokkal kapcsolatos probléma részletei

Az MVC egy hibaeredményt (a 400-os vagy újabb állapotkódú eredményt) a következő ProblemDetailseredményre alakítja át: . A ProblemDetails típus az RFC 7807 specifikáción alapul, amely géppel olvasható hibaadatokat biztosít egy HTTP-válaszban.

Vegye figyelembe a következő kódot egy vezérlőműveletben:

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

A NotFound metódus egy HTTP 404-állapotkódot hoz létre egy ProblemDetails törzstel. Például:

{
  type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  title: "Not Found",
  status: 404,
  traceId: "0HLHLV31KRN83:00000001"
}

ProblemDetails-válasz letiltása

A ProblemDetails hibaállapot-kódok automatikus létrehozása le van tiltva, ha a SuppressMapClientErrors tulajdonság true értékre van állítva. Adja hozzá a következő kódot:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Támogatott kérés tartalomtípusainak definiálása a [Felhasználások] attribútummal

Alapértelmezés szerint egy művelet támogatja az összes elérhető kérelemtartalomtípust. Ha például egy alkalmazás úgy van konfigurálva, hogy támogatja a JSON- és XML-bemeneti formátumkészítőket is, egy művelet több tartalomtípust is támogat, köztük application/json és application/xml.

A [Felhasználás] attribútum lehetővé teszi, hogy egy művelet korlátozza a támogatott kérelem tartalomtípusait. Alkalmazza az [Consumes] attribútumot egy műveletre vagy vezérlőre egy vagy több tartalomtípus megadásával:

[HttpPost]
[Consumes("application/xml")]
public IActionResult CreateProduct(Product product)

Az előző kódban a CreateProduct művelet megadja a tartalom típusát application/xml. Az ehhez a művelethez irányított kérelmeknek meg kell adniuk a Content-Type fejlécet.application/xml Azok a kérések, amelyek nem adnak meg Content-Typeapplication/xml fejlécet, 415 Nem támogatott médiatípus válasz eredményeznek.

Az [Consumes] attribútum azt is lehetővé teszi, hogy egy művelet egy típuskényszer alkalmazásával egy bejövő kérelem tartalomtípusa alapján befolyásolja a kijelölést. Vegye figyelembe a következő példát:

[ApiController]
[Route("api/[controller]")]
public class ConsumesController : ControllerBase
{
    [HttpPost]
    [Consumes("application/json")]
    public IActionResult PostJson(IEnumerable<int> values) =>
        Ok(new { Consumes = "application/json", Values = values });

    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    public IActionResult PostForm([FromForm] IEnumerable<int> values) =>
        Ok(new { Consumes = "application/x-www-form-urlencoded", Values = values });
}

Az előző kódban ConsumesController az URL-címre küldött https://localhost:5001/api/Consumes kérelmek kezelésére van konfigurálva. A vezérlő mindkét művelete, PostJson és PostForm, ugyanazzal az URL-címmel POST kéréseket kezel. [Consumes] A típuskorlátozást alkalmazó attribútum nélkül a rendszer nem egyértelmű egyezés-kivételt vet ki.

Az [Consumes] attribútum mindkét műveletre érvényes. A PostJson művelet a következő fejléccel Content-Typeapplication/jsonküldött kéréseket kezeli: . A PostForm művelet a következő fejléccel Content-Typeapplication/x-www-form-urlencodedküldött kéréseket kezeli: .

További erőforrások

• Mintakód megtekintése vagy letöltése. (A letöltés módja).
• A vezérlőműveletek visszatérési típusai az ASP.NET Core webes API-ban
• ASP.NET Core API-k hibáinak kezelése
• Egyéni formázók a ASP.NET Core Web API-ban
• Válaszadatok formázása a ASP.NET Core Web API-ban
• ASP.NET Core webes API dokumentáció Swaggerrel / OpenAPI-val
• ASP.NET Core vezérlőműveleteinek útválasztása
• Használja a porttunnelinget a Visual Studioban webes API-k hibakereséséhez
• Webes API létrehozása a ASP.NET Core használatával