Tworzenie internetowych interfejsów API za pomocą platformy ASP.NET CoreCreate web APIs with ASP.NET Core

Przez Scott Addie i Tomasz DykstraBy Scott Addie and Tom Dykstra

Platforma ASP.NET Core obsługuje tworzenie usług RESTful, znanych także jako internetowe interfejsy API, za pomocą języka C#.ASP.NET Core supports creating RESTful services, also known as web APIs, using C#. Aby obsługiwać żądania, interfejs API sieci Web używa kontrolerów.To handle requests, a web API uses controllers. Kontrolery w INTERNETowym interfejsie API są klasami pochodnymi od ControllerBase .Controllers in a web API are classes that derive from ControllerBase. W tym artykule pokazano, jak używać kontrolerów do obsługi żądań interfejsu API sieci Web.This article shows how to use controllers for handling web API requests.

Wyświetlanie lub Pobieranie przykładowego kodu.View or download sample code. (Jak pobrać).(How to download).

Klasa ControllerBaseControllerBase class

Internetowy interfejs API składa się z co najmniej jednej klasy kontrolera, która pochodzi od ControllerBase .A web API consists of one or more controller classes that derive from ControllerBase. Szablon projektu internetowego interfejsu API zawiera kontroler początkowy:The web API project template provides a starter controller:

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

Nie twórz kontrolera interfejsu API sieci Web, pobierając z Controller klasy.Don't create a web API controller by deriving from the Controller class. Controller Program dziedziczy z ControllerBase i dodaje obsługę widoków, dlatego służy do obsługi stron sieci Web, a nie żądań interfejsu API sieci Web.Controller derives from ControllerBase and adds support for views, so it's for handling web pages, not web API requests. Wystąpił wyjątek dla tej reguły: Jeśli planujesz używać tego samego kontrolera dla widoków i interfejsów API sieci Web, utwórz go z Controller .There's an exception to this rule: if you plan to use the same controller for both views and web APIs, derive it from Controller.

ControllerBaseKlasa zawiera wiele właściwości i metod, które są przydatne do obsługi żądań HTTP.The ControllerBase class provides many properties and methods that are useful for handling HTTP requests. Na przykład ControllerBase.CreatedAtAction zwraca kod stanu 201:For example, ControllerBase.CreatedAtAction returns a 201 status code:

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

Poniżej przedstawiono kilka przykładów metod, które ControllerBase zapewnia.Here are some more examples of methods that ControllerBase provides.

MetodaMethod UwagiNotes
BadRequest Zwraca kod stanu 400.Returns 400 status code.
NotFound Zwraca kod stanu 404.Returns 404 status code.
PhysicalFile Zwraca plik.Returns a file.
TryUpdateModelAsync Wywołuje powiązanie modelu.Invokes model binding.
TryValidateModel Wywołuje walidację modelu.Invokes model validation.

Listę wszystkich dostępnych metod i właściwości można znaleźć w temacie ControllerBase .For a list of all available methods and properties, see ControllerBase.

AtrybutyAttributes

Microsoft.AspNetCore.MvcPrzestrzeń nazw zawiera atrybuty, których można użyć do skonfigurowania zachowania kontrolerów internetowego interfejsu API i metod akcji.The Microsoft.AspNetCore.Mvc namespace provides attributes that can be used to configure the behavior of web API controllers and action methods. Poniższy przykład używa atrybutów, aby określić obsługiwane zlecenie akcji HTTP i wszystkie znane kody stanu HTTP, które mogą zostać zwrócone:The following example uses attributes to specify the supported HTTP action verb and any known HTTP status codes that could be returned:

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

Poniżej przedstawiono kilka przykładów dostępnych atrybutów.Here are some more examples of attributes that are available.

AtrybutAttribute UwagiNotes
[Route] Określa wzorzec adresu URL dla kontrolera lub akcji.Specifies URL pattern for a controller or action.
[Bind] Określa prefiks i właściwości, które mają zostać dołączone do powiązania modelu.Specifies prefix and properties to include for model binding.
[HttpGet] Identyfikuje akcję, która obsługuje czasownik HTTP GET.Identifies an action that supports the HTTP GET action verb.
[Consumes] Określa typy danych, które akcja akceptuje.Specifies data types that an action accepts.
[Produces] Określa typy danych, które zwraca akcja.Specifies data types that an action returns.

Aby zapoznać się z listą zawierającą dostępne atrybuty, zobacz Microsoft.AspNetCore.Mvc przestrzeń nazw.For a list that includes the available attributes, see the Microsoft.AspNetCore.Mvc namespace.

ApiController — atrybutApiController attribute

Ten [ApiController] atrybut może być stosowany do klasy kontrolera w celu włączenia następujących zachowań ceniona, specyficznych dla interfejsu API:The [ApiController] attribute can be applied to a controller class to enable the following opinionated, API-specific behaviors:

Szczegóły problemu dotyczącego kodów stanu błędu wymagają wersji 2,2 lub nowszej.The Problem details for error status codes feature requires a compatibility version of 2.2 or later. Inne funkcje wymagają wersji 2,1 lub nowszej.The other features require a compatibility version of 2.1 or later.

Te funkcje wymagają wersji 2,1 lub nowszej.These features require a compatibility version of 2.1 or later.

Atrybut na określonych kontrolerachAttribute on specific controllers

Ten [ApiController] atrybut może być stosowany do określonych kontrolerów, jak w poniższym przykładzie z szablonu projektu:The [ApiController] attribute can be applied to specific controllers, as in the following example from the project template:

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

Atrybut na wielu kontrolerachAttribute on multiple controllers

Jednym z metod używania atrybutu na więcej niż jednym kontrolerze jest utworzenie niestandardowej klasy kontrolera podstawowego z adnotacją z [ApiController] atrybutem.One approach to using the attribute on more than one controller is to create a custom base controller class annotated with the [ApiController] attribute. Poniższy przykład przedstawia niestandardową klasę bazową i kontroler, który pochodzi od niego:The following example shows a custom base class and a controller that derives from it:

[ApiController]
public class MyControllerBase : ControllerBase
{
}
[Produces(MediaTypeNames.Application.Json)]
[Route("[controller]")]
public class PetsController : MyControllerBase
[Produces(MediaTypeNames.Application.Json)]
[Route("api/[controller]")]
public class PetsController : MyControllerBase

Atrybut w zestawieAttribute on an assembly

Jeśli wersja zgodności jest ustawiona na 2,2 lub nowsza, [ApiController] atrybut może być stosowany do zestawu.If compatibility version is set to 2.2 or later, the [ApiController] attribute can be applied to an assembly. Adnotacja w ten sposób stosuje zachowanie internetowego interfejsu API do wszystkich kontrolerów w zestawie.Annotation in this manner applies web API behavior to all controllers in the assembly. Nie ma możliwości rezygnacji z poszczególnych kontrolerów.There's no way to opt out for individual controllers. Zastosuj atrybut poziomu zestawu do deklaracji przestrzeni nazw otaczającej Startup klasę:Apply the assembly-level attribute to the namespace declaration surrounding the Startup class:

[assembly: ApiController]
namespace WebApiSample
{
    public class Startup
    {
        ...
    }
}

Wymagania dotyczące routingu atrybutówAttribute routing requirement

[ApiController]Atrybut powoduje, że atrybut routingu wymaga.The [ApiController] attribute makes attribute routing a requirement. Przykład:For example:

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

Akcje są niedostępne za pośrednictwem konwencjonalnych tras zdefiniowanych przez UseEndpoints , UseMvc lub UseMvcWithDefaultRoute w Startup.Configure .Actions are inaccessible via conventional routes defined by UseEndpoints, UseMvc, or UseMvcWithDefaultRoute in Startup.Configure.

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

Akcje są niedostępne za pośrednictwem konwencjonalnych tras zdefiniowanych przez UseMvc lub UseMvcWithDefaultRoute w Startup.Configure .Actions are inaccessible via conventional routes defined by UseMvc or UseMvcWithDefaultRoute in Startup.Configure.

Automatyczne odpowiedzi HTTP 400Automatic HTTP 400 responses

Ten [ApiController] atrybut sprawia, że błędy walidacji modelu automatycznie wyzwalają odpowiedź HTTP 400.The [ApiController] attribute makes model validation errors automatically trigger an HTTP 400 response. W związku z tym Poniższy kod jest zbędny w metodzie akcji:Consequently, the following code is unnecessary in an action method:

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

ASP.NET Core MVC używa ModelStateInvalidFilter filtru akcji, aby wykonać poprzednią kontrolę.ASP.NET Core MVC uses the ModelStateInvalidFilter action filter to do the preceding check.

Domyślna odpowiedź nieprawidłowego żądaniaDefault BadRequest response

W przypadku zgodności z wersją 2,1, domyślny typ odpowiedzi dla odpowiedzi HTTP 400 to SerializableError .With a compatibility version of 2.1, the default response type for an HTTP 400 response is SerializableError. Następująca treść żądania jest przykładem serializowanego typu:The following request body is an example of the serialized type:

{
  "": [
    "A non-empty request body is required."
  ]
}

W przypadku zgodności z wersją 2,2 lub nowszą domyślny typ odpowiedzi dla odpowiedzi HTTP 400 to ValidationProblemDetails .With a compatibility version of 2.2 or later, the default response type for an HTTP 400 response is ValidationProblemDetails. Następująca treść żądania jest przykładem serializowanego typu:The following request body is an example of the serialized type:

{
  "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."
    ]
  }
}

ValidationProblemDetailsTyp:The ValidationProblemDetails type:

  • Zapewnia czytelny dla maszyn format służący do określania błędów w odpowiedziach interfejsu API sieci Web.Provides a machine-readable format for specifying errors in web API responses.
  • Jest zgodna ze specyfikacją RFC 7807.Complies with the RFC 7807 specification.

Aby zapewnić spójność automatycznych i niestandardowych odpowiedzi, wywołaj ValidationProblem metodę zamiast BadRequest .To make automatic and custom responses consistent, call the ValidationProblem method instead of BadRequest. ValidationProblem zwraca ValidationProblemDetails obiekt, a także odpowiedź automatyczną.ValidationProblem returns a ValidationProblemDetails object as well as the automatic response.

Rejestruj automatyczne odpowiedzi 400Log automatic 400 responses

Zobacz jak rejestrować 400 automatyczne odpowiedzi na błędy walidacji modelu (dotnet/AspNetCore.Docs # 12157).See How to log automatic 400 responses on model validation errors (dotnet/AspNetCore.Docs#12157).

Wyłącz automatyczną odpowiedź 400Disable automatic 400 response

Aby wyłączyć zachowanie automatycznego 400, należy ustawić SuppressModelStateInvalidFilter Właściwość na true .To disable the automatic 400 behavior, set the SuppressModelStateInvalidFilter property to true. Dodaj następujący wyróżniony kod w Startup.ConfigureServices :Add the following highlighted code in Startup.ConfigureServices:

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";
    });
services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });
services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Wnioskowanie parametru źródła powiązaniaBinding source parameter inference

Atrybut źródłowy powiązania definiuje lokalizację, w której zostanie znaleziona wartość parametru akcji.A binding source attribute defines the location at which an action parameter's value is found. Istnieją następujące atrybuty źródła powiązania:The following binding source attributes exist:

AtrybutAttribute Źródło powiązaniaBinding source
[FromBody] Treść żądaniaRequest body
[FromForm] Formularz danych w treści żądaniaForm data in the request body
[FromHeader] Nagłówek żądaniaRequest header
[FromQuery] Parametr ciągu zapytania żądaniaRequest query string parameter
[FromRoute] Kierowanie danych z bieżącego żądaniaRoute data from the current request
[FromServices] Usługa żądania wstrzykiwana jako parametr akcjiThe request service injected as an action parameter

Ostrzeżenie

Nie należy używać [FromRoute] , gdy wartości mogą zawierać %2f (to oznacza / ).Don't use [FromRoute] when values might contain %2f (that is /). %2f nie zostanie wywyprowadzane do / .%2f won't be unescaped to /. Użyj [FromQuery] , jeśli wartość może zawierać %2f .Use [FromQuery] if the value might contain %2f.

Bez [ApiController] atrybutów źródła atrybutów ani powiązań, takich jak [FromQuery] , środowisko uruchomieniowe ASP.NET Core próbuje użyć spinacza modelu obiektów złożonych.Without the [ApiController] attribute or binding source attributes like [FromQuery], the ASP.NET Core runtime attempts to use the complex object model binder. Segregator modelu obiektów złożonych pobiera dane od dostawców wartości w zdefiniowanej kolejności.The complex object model binder pulls data from value providers in a defined order.

W poniższym przykładzie [FromQuery] atrybut wskazuje, że discontinuedOnly wartość parametru jest podana w ciągu zapytania adresu URL żądania:In the following example, the [FromQuery] attribute indicates that the discontinuedOnly parameter value is provided in the request URL's query string:

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

Ten [ApiController] atrybut stosuje reguły wnioskowania dla domyślnych źródeł danych parametrów akcji.The [ApiController] attribute applies inference rules for the default data sources of action parameters. Te reguły zapisują nie trzeba ręcznie identyfikować źródeł powiązań przez zastosowanie atrybutów do parametrów akcji.These rules save you from having to identify binding sources manually by applying attributes to the action parameters. Reguły wnioskowania źródła powiązań zachowują się w następujący sposób:The binding source inference rules behave as follows:

  • [FromBody] jest wywnioskowany dla parametrów typu złożonego.[FromBody] is inferred for complex type parameters. Wyjątek od [FromBody] reguły wnioskowania jest dowolnego złożonego, wbudowanego typu z specjalnym znaczeniem, takim jak IFormCollection i CancellationToken .An exception to the [FromBody] inference rule is any complex, built-in type with a special meaning, such as IFormCollection and CancellationToken. Kod wnioskowania źródła powiązania ignoruje te typy specjalne.The binding source inference code ignores those special types.
  • [FromForm] jest wywnioskowany dla parametrów akcji typu IFormFile i IFormFileCollection .[FromForm] is inferred for action parameters of type IFormFile and IFormFileCollection. Nie jest wywnioskowane dla żadnego prostego lub zdefiniowanego przez użytkownika typu.It's not inferred for any simple or user-defined types.
  • [FromRoute] jest wywnioskowany dla każdej nazwy parametru akcji pasującej do parametru w szablonie trasy.[FromRoute] is inferred for any action parameter name matching a parameter in the route template. W przypadku, gdy więcej niż jedna trasa pasuje do parametru akcji, uwzględniana jest jakakolwiek wartość trasy [FromRoute] .When more than one route matches an action parameter, any route value is considered [FromRoute].
  • [FromQuery] jest wywnioskowany dla wszystkich innych parametrów akcji.[FromQuery] is inferred for any other action parameters.

FromBody informacje o wnioskachFromBody inference notes

[FromBody] nie jest wywnioskowane dla typów prostych, takich jak string lub int .[FromBody] isn't inferred for simple types such as string or int. W związku z tym [FromBody] atrybut powinien być używany dla typów prostych, gdy ta funkcja jest wymagana.Therefore, the [FromBody] attribute should be used for simple types when that functionality is needed.

Gdy akcja ma więcej niż jeden parametr powiązany z treścią żądania, zgłaszany jest wyjątek.When an action has more than one parameter bound from the request body, an exception is thrown. Na przykład, wszystkie następujące sygnatury metody akcji powodują wyjątek:For example, all of the following action method signatures cause an exception:

  • [FromBody] wywnioskowane na obu, ponieważ są to typy złożone.[FromBody] inferred on both because they're complex types.

    [HttpPost]
    public IActionResult Action1(Product product, Order order)
    
  • [FromBody] atrybut na jeden, wywnioskowany na drugim, ponieważ jest typem złożonym.[FromBody] attribute on one, inferred on the other because it's a complex type.

    [HttpPost]
    public IActionResult Action2(Product product, [FromBody] Order order)
    
  • [FromBody] atrybut na obu.[FromBody] attribute on both.

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

Uwaga

W ASP.NET Core 2,1 parametry typu kolekcji, takie jak listy i tablice, są nieprawidłowo wnioskowane jako [FromQuery] .In ASP.NET Core 2.1, collection type parameters such as lists and arrays are incorrectly inferred as [FromQuery]. Ten [FromBody] atrybut powinien być używany dla tych parametrów, jeśli mają być powiązane z treścią żądania.The [FromBody] attribute should be used for these parameters if they are to be bound from the request body. To zachowanie jest korygowane w ASP.NET Core 2,2 lub nowszych, gdzie parametry typu kolekcji są wyrzucane jako powiązane z treścią domyślnie.This behavior is corrected in ASP.NET Core 2.2 or later, where collection type parameters are inferred to be bound from the body by default.

Wyłącz reguły wnioskowaniaDisable inference rules

Aby wyłączyć wnioskowanie źródeł powiązań, ustaw SuppressInferBindingSourcesForParameters wartość true .To disable binding source inference, set SuppressInferBindingSourcesForParameters to true. Dodaj następujący kod w Startup.ConfigureServices :Add the following code in Startup.ConfigureServices:

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";
    });
services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });
services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Wieloczęściowe/formularz-wnioskowanie dotyczące danychMultipart/form-data request inference

Ten [ApiController] atrybut stosuje regułę wnioskowania, gdy parametr akcji ma adnotację z [FromForm] atrybutem.The [ApiController] attribute applies an inference rule when an action parameter is annotated with the [FromForm] attribute. multipart/form-dataTyp zawartości żądania jest wywnioskowany.The multipart/form-data request content type is inferred.

Aby wyłączyć domyślne zachowanie, ustaw SuppressConsumesConstraintForFormFileParameters Właściwość na wartość true w Startup.ConfigureServices :To disable the default behavior, set the SuppressConsumesConstraintForFormFileParameters property to true in Startup.ConfigureServices:

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";
    });
services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });
services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressConsumesConstraintForFormFileParameters = true;
    options.SuppressInferBindingSourcesForParameters = true;
    options.SuppressModelStateInvalidFilter = true;
});

Szczegóły problemu dotyczące kodów stanu błęduProblem details for error status codes

Gdy wersja zgodności to 2,2 lub nowsza, MVC przeprowadzi wynik błędu (wynik z kodem stanu 400 lub nowszym) do wyniku z ProblemDetails .When the compatibility version is 2.2 or later, MVC transforms an error result (a result with status code 400 or higher) to a result with ProblemDetails. ProblemDetailsTyp jest oparty na specyfikacji RFC 7807 do udostępniania szczegółowych informacji o błędach w odpowiedzi HTTP.The ProblemDetails type is based on the RFC 7807 specification for providing machine-readable error details in an HTTP response.

Rozważmy następujący kod w akcji kontrolera:Consider the following code in a controller action:

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

NotFoundMetoda generuje kod stanu HTTP 404 z ProblemDetails treścią.The NotFound method produces an HTTP 404 status code with a ProblemDetails body. Przykład:For example:

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

Wyłącz odpowiedź ProblemDetailsDisable ProblemDetails response

Automatyczne tworzenie ProblemDetails kodów stanu błędu jest wyłączone, gdy SuppressMapClientErrors Właściwość jest ustawiona na true .The automatic creation of a ProblemDetails for error status codes is disabled when the SuppressMapClientErrors property is set to true. Dodaj następujący kod w Startup.ConfigureServices :Add the following code in Startup.ConfigureServices:

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";
    });
services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2)
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });

Zdefiniuj obsługiwane typy zawartości żądania z atrybutem [Requests]Define supported request content types with the [Consumes] attribute

Domyślnie akcja obsługuje wszystkie dostępne typy zawartości żądania.By default, an action supports all available request content types. Na przykład jeśli aplikacja jest skonfigurowana do obsługi danych wejściowychJSON i XML, Akcja obsługuje wiele typów zawartości, w tym application/json i application/xml .For example, if an app is configured to support both JSON and XML input formatters, an action supports multiple content types, including application/json and application/xml.

Atrybut [ Requests] umożliwia akcja ograniczenia obsługiwanych typów zawartości żądania.The [Consumes] attribute allows an action to limit the supported request content types. Zastosuj [Consumes] atrybut do akcji lub kontrolera, określając jeden lub więcej typów zawartości:Apply the [Consumes] attribute to an action or controller, specifying one or more content types:

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

W poprzednim kodzie CreateProduct Akcja określa typ zawartości application/xml .In the preceding code, the CreateProduct action specifies the content type application/xml. Żądania kierowane do tej akcji muszą określać Content-Type nagłówek application/xml .Requests routed to this action must specify a Content-Type header of application/xml. Żądania, które nie określają Content-Type nagłówka application/xml wyniku w nieobsługiwanej odpowiedzi typu nośnika 415 .Requests that don't specify a Content-Type header of application/xml result in a 415 Unsupported Media Type response.

Ten [Consumes] atrybut umożliwia również akcję, która ma wpływ na wybór w oparciu o typ zawartości przychodzącego żądania przez zastosowanie ograniczenia typu.The [Consumes] attribute also allows an action to influence its selection based on an incoming request's content type by applying a type constraint. Rozpatrzmy następujący przykład:Consider the following example:

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

W poprzednim kodzie program ConsumesController jest skonfigurowany do obsługi żądań wysyłanych do https://localhost:5001/api/Consumes adresu URL.In the preceding code, ConsumesController is configured to handle requests sent to the https://localhost:5001/api/Consumes URL. Oba akcje kontrolera PostJson i PostForm obsługują żądania post z tym samym adresem URL.Both of the controller's actions, PostJson and PostForm, handle POST requests with the same URL. Bez [Consumes] atrybutu stosującego ograniczenie typu jest generowany niejednoznaczny wyjątek dopasowania.Without the [Consumes] attribute applying a type constraint, an ambiguous match exception is thrown.

Ten [Consumes] atrybut jest stosowany do obu akcji.The [Consumes] attribute is applied to both actions. PostJsonAkcja obsługuje żądania wysyłane z Content-Type nagłówkiem application/json .The PostJson action handles requests sent with a Content-Type header of application/json. PostFormAkcja obsługuje żądania wysyłane z Content-Type nagłówkiem application/x-www-form-urlencoded .The PostForm action handles requests sent with a Content-Type header of application/x-www-form-urlencoded.

Dodatkowe zasobyAdditional resources