Erstellen von Web-APIs mit ASP.NET CoreCreate web APIs with ASP.NET Core

Von Scott Addie und Tom DykstraBy Scott Addie and Tom Dykstra

ASP.NET Core unterstützt das Erstellen von RESTful-Diensten, die auch als Web-APIs bezeichnet werden, unter Verwendung von C#.ASP.NET Core supports creating RESTful services, also known as web APIs, using C#. Eine Web-API verwendet Controller, um Anforderungen zu verarbeiten.To handle requests, a web API uses controllers. Controller in einer Web-API sind von ControllerBase abgeleitete Klassen.Controllers in a web API are classes that derive from ControllerBase. In diesem Artikel wird beschrieben, wie Sie Controller für die Verarbeitung von Web-API-Anforderungen verwenden.This article shows how to use controllers for handling web API requests.

Anzeigen oder Herunterladen von BeispielcodeView or download sample code. (Informationen zum Herunterladen)(How to download).

ControllerBase-KlasseControllerBase class

Eine Web-API besteht aus mindestens einer Controllerklasse, die von ControllerBase abgeleitet ist.A web API consists of one or more controller classes that derive from ControllerBase. Die Web-API-Projektvorlage stellt einen Startercontroller bereit:The web API project template provides a starter controller:

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

Erstellen Sie einen Web-API-Controller nicht durch Ableitung aus der Controller-Klasse.Don't create a web API controller by deriving from the Controller class. Controller wird von ControllerBase abgeleitet und fügt Unterstützung für Ansichten hinzu, wird also für die Verarbeitung von Webseiten verwendet und nicht für Web-API-Anforderungen.Controller derives from ControllerBase and adds support for views, so it's for handling web pages, not web API requests. Es gibt eine Ausnahme von dieser Regel: Wenn Sie denselben Controller sowohl für Ansichten als auch für Web-APIs verwenden möchten, leiten Sie ihn von Controller ab.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.

Die ControllerBase-Klasse bietet viele Eigenschaften und Methoden, die für die Verarbeitung von HTTP-Anforderungen hilfreich sind.The ControllerBase class provides many properties and methods that are useful for handling HTTP requests. ControllerBase.CreatedAtAction gibt beispielsweise Statuscode 201 zurück: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);
}

Hier einige weitere Beispiele für die von ControllerBase bereitgestellten Methoden.Here are some more examples of methods that ControllerBase provides.

MethodeMethod HinweiseNotes
BadRequest Gibt Statuscode 400 zurück.Returns 400 status code.
NotFound Gibt Statuscode 404 zurück.Returns 404 status code.
PhysicalFile Gibt eine Datei zurück.Returns a file.
TryUpdateModelAsync Ruft die Modellbindung auf.Invokes model binding.
TryValidateModel Ruft die Modellvalidierung auf.Invokes model validation.

Eine Liste aller verfügbaren Methoden und Eigenschaften finden Sie unter ControllerBase.For a list of all available methods and properties, see ControllerBase.

AttributeAttributes

Der Microsoft.AspNetCore.Mvc-Namespace enthält Attribute, mit denen das Verhalten von Web-API-Controllern und Aktionsmethoden konfiguriert werden kann.The Microsoft.AspNetCore.Mvc namespace provides attributes that can be used to configure the behavior of web API controllers and action methods. Im folgenden Beispiel werden Attribute verwendet, um das unterstützte HTTP-Aktionsverb und alle bekannten HTTP-Statuscodes, die zurückgegeben werden können, anzugeben: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);
}

Hier einige weitere Beispiele für die verfügbaren Attribute.Here are some more examples of attributes that are available.

AttributAttribute HinweiseNotes
[Route] Gibt ein URL-Muster für einen Controller oder eine Aktion an.Specifies URL pattern for a controller or action.
[Bind] Gibt Präfixe und Eigenschaften an, die in die Modellbindung einbezogen werden sollen.Specifies prefix and properties to include for model binding.
[HttpGet] Identifiziert eine Aktion, die das HTTP GET-Aktionsverb unterstützt.Identifies an action that supports the HTTP GET action verb.
[Consumes] Gibt die von einer Aktion akzeptierten Datentypen an.Specifies data types that an action accepts.
[Produces] Gibt die von einer Aktion zurückgegebenen Datentypen an.Specifies data types that an action returns.

Eine Liste mit den verfügbaren Attributen finden Sie im Microsoft.AspNetCore.Mvc-Namespace.For a list that includes the available attributes, see the Microsoft.AspNetCore.Mvc namespace.

ApiController-AttributApiController attribute

Das [ApiController]-Attribut kann auf eine Controllerklasse angewendet werden, um folgende API-spezifische Verhalten mit einigen vordefinierten Konfigurationen zu aktivieren:The [ApiController] attribute can be applied to a controller class to enable the following opinionated, API-specific behaviors:

Das Feature Problemdetails für Fehlerstatuscodes erfordert mindestens die Kompatibilitätsversion 2.2.The Problem details for error status codes feature requires a compatibility version of 2.2 or later. Die anderen Features erfordern mindestens Kompatibilitätsversion 2.1.The other features require a compatibility version of 2.1 or later.

Diese Features erfordern mindestens Kompatibilitätsversion 2.1.These features require a compatibility version of 2.1 or later.

Attribut für bestimmte ControllerAttribute on specific controllers

Das [ApiController]-Attribut kann, wie im folgenden Beispiel der Projektvorlage ersichtlich, auf bestimmte Controller angewendet werden: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

Attribut für mehrere ControllerAttribute on multiple controllers

Eine Möglichkeit, das Attribut für mehr als einen Controller zu verwenden, besteht darin, eine benutzerdefinierte Basiscontrollerklasse zu erstellen, die mit dem [ApiController]-Attribut kommentiert ist.One approach to using the attribute on more than one controller is to create a custom base controller class annotated with the [ApiController] attribute. Im folgenden Beispiel wird eine benutzerdefinierte Basisklasse und ein Controller, der von ihr abgeleitet wird, gezeigt: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

Attribut für eine AssemblyAttribute on an assembly

Wenn die Kompatibilitätsversion auf 2.2 oder höher festgelegt ist, kann das [ApiController]-Attribut auf eine Assembly angewendet werden.If compatibility version is set to 2.2 or later, the [ApiController] attribute can be applied to an assembly. Auf diese Weise wendet die Anmerkung das Web-API-Verhalten auf alle Controller in der Assembly an.Annotation in this manner applies web API behavior to all controllers in the assembly. Es gibt keine Möglichkeit, einzelne Controller auszuschließen.There's no way to opt out for individual controllers. Wenden Sie das Attribut auf Assemblyebene auf die Namespacedeklaration an, die die Startup-Klasse umgibt:Apply the assembly-level attribute to the namespace declaration surrounding the Startup class:

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

Anforderung für das AttributroutingAttribute routing requirement

Durch das [ApiController]-Attribut wird das Attributrouting zu einer Anforderung.The [ApiController] attribute makes attribute routing a requirement. Zum Beispiel:For example:

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

Sie können über konventionelle Routen, die durch UseEndpoints, UseMvc oder UseMvcWithDefaultRoute in Startup.Configure definiert sind, nicht auf Aktionen zugreifen.Actions are inaccessible via conventional routes defined by UseEndpoints, UseMvc, or UseMvcWithDefaultRoute in Startup.Configure.

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

Sie können über konventionelle Routen, die durch UseMvc oder UseMvcWithDefaultRoute in Startup.Configure definiert sind, nicht auf Aktionen zugreifen.Actions are inaccessible via conventional routes defined by UseMvc or UseMvcWithDefaultRoute in Startup.Configure.

Automatische HTTP 400-AntwortAutomatic HTTP 400 responses

Durch das [ApiController]-Attribut wird bei Modellvalidierungsfehlern automatisch eine HTTP 400-Antwort ausgelöst.The [ApiController] attribute makes model validation errors automatically trigger an HTTP 400 response. Deshalb ist der folgende Code in einer Aktionsmethode überflüssig:Consequently, the following code is unnecessary in an action method:

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

ASP.NET Core MVC verwendet den ModelStateInvalidFilter-Aktionsfilter, um die vorherige Überprüfung durchzuführen.ASP.NET Core MVC uses the ModelStateInvalidFilter action filter to do the preceding check.

Standardmäßige BadRequest-AntwortDefault BadRequest response

Bei Kompatibilitätsversion 2.1 wird für eine HTTP 400-Antwort standardmäßig der Antworttyp SerializableError verwendet.With a compatibility version of 2.1, the default response type for an HTTP 400 response is SerializableError. Der folgende Anforderungstext ist ein Beispiel für den serialisierten Typ:The following request body is an example of the serialized type:

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

Bei Kompatibilitätsversion 2.2 oder höher wird für eine HTTP 400-Antwort standardmäßig der Antworttyp ValidationProblemDetails verwendet.With a compatibility version of 2.2 or later, the default response type for an HTTP 400 response is ValidationProblemDetails. Der folgende Anforderungstext ist ein Beispiel für den serialisierten Typ: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."
    ]
  }
}

Der ValidationProblemDetails-Typ:The ValidationProblemDetails type:

  • Bietet ein vom Computer lesbares Format zum Angeben von Fehlern in Web-API-Antworten.Provides a machine-readable format for specifying errors in web API responses.
  • Entspricht der RFC 7807-Spezifikation.Complies with the RFC 7807 specification.

Rufen Sie die ValidationProblem-Methode anstelle von BadRequest auf, um automatische und benutzerdefinierte Antworten konsistent zu machen.To make automatic and custom responses consistent, call the ValidationProblem method instead of BadRequest. ValidationProblem gibt sowohl ein ValidationProblemDetails-Objekt als auch die automatische Antwort zurück.ValidationProblem returns a ValidationProblemDetails object as well as the automatic response.

Protokollieren automatischer 400-AntwortenLog automatic 400 responses

Informationen finden Sie unter Protokollieren automatischer 400-Antworten auf Modellvalidierungsfehler, (dotnet/AspNetCore.Docs#12157).See How to log automatic 400 responses on model validation errors (dotnet/AspNetCore.Docs#12157).

Deaktivieren automatischer 400-AntwortDisable automatic 400 response

Um das automatische Verhalten bei Statuscode 400 zu deaktivieren, legen Sie die SuppressModelStateInvalidFilter-Eigenschaft auf true fest.To disable the automatic 400 behavior, set the SuppressModelStateInvalidFilter property to true. Fügen Sie folgenden hervorgehobenen Code in Startup.ConfigureServices hinzu: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;
});

Rückschluss auf BindungsquellparameterBinding source parameter inference

Ein Bindungsquellenattribut definiert den Speicherort, an dem der Wert eines Aktionsparameters vorhanden ist.A binding source attribute defines the location at which an action parameter's value is found. Es gibt die folgenden Bindungsquellattribute:The following binding source attributes exist:

AttributAttribute BindungsquelleBinding source
[FromBody] AnforderungstextRequest body
[FromForm] Formulardaten im AnforderungstextForm data in the request body
[FromHeader] AnforderungsheaderRequest header
[FromQuery] Abfragezeichenfolge-Parameter der AnforderungRequest query string parameter
[FromRoute] Routendaten aus aktuellen AnforderungenRoute data from the current request
[FromServices] Der als Aktionsparameter eingefügte Anforderungsdienst.The request service injected as an action parameter

Warnung

Verwenden Sie [FromRoute] nicht, wenn Werte möglicherweise %2f enthalten (d.h. /).Don't use [FromRoute] when values might contain %2f (that is /). %2f wird nicht durch Entfernen von Escapezeichen zu /.%2f won't be unescaped to /. Verwenden Sie [FromQuery], wenn der Wert %2f enthalten könnte.Use [FromQuery] if the value might contain %2f.

Ohne das [ApiController]-Attribut oder Bindungsquellenattribute wie [FromQuery] versucht die ASP.NET Core-Runtime, die Modellbindung für komplexe Objekte zu verwenden.Without the [ApiController] attribute or binding source attributes like [FromQuery], the ASP.NET Core runtime attempts to use the complex object model binder. Bei der Modellbindung für komplexe Objekte werden Daten aus Wertanbietern in einer festgelegten Reihenfolge abgerufen.The complex object model binder pulls data from value providers in a defined order.

Im folgenden Beispiel gibt das [FromQuery]-Attribut an, dass der Parameterwert discontinuedOnly in der Abfragezeichenfolge der Anforderungs-URL bereitgestellt wird: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;
}

Das [ApiController]-Attribut wendet Rückschlussregeln auf die Standarddatenquellen von Aktionsparametern an.The [ApiController] attribute applies inference rules for the default data sources of action parameters. Da durch diese Regeln Attribute auf die Aktionsparameter angewendet werden, müssen Sie Bindungsquellen nicht manuell identifizieren.These rules save you from having to identify binding sources manually by applying attributes to the action parameters. Die Rückschlussregeln für Bindungsquellen verhalten sich wie folgt:The binding source inference rules behave as follows:

  • [FromBody] wird für komplexe Typparameter abgeleitet.[FromBody] is inferred for complex type parameters. Jeder komplexe integrierte Typ mit spezieller Bedeutung, z. B. IFormCollection und CancellationToken, stellt eine Ausnahme von der [FromBody]-Rückschlussregel dar.An exception to the [FromBody] inference rule is any complex, built-in type with a special meaning, such as IFormCollection and CancellationToken. Der Rückschlusscode der Bindungsquelle ignoriert diese Typen.The binding source inference code ignores those special types.
  • [FromForm] wird für Aktionsparameter des Typs IFormFile und IFormFileCollection abgeleitet.[FromForm] is inferred for action parameters of type IFormFile and IFormFileCollection. Es wird für keine einfachen oder benutzerdefinierte Typen abgeleitet.It's not inferred for any simple or user-defined types.
  • [FromRoute] wird für jeden Namen von Aktionsparametern abgeleitet, der mit einem Parameter in der Routenvorlage übereinstimmt.[FromRoute] is inferred for any action parameter name matching a parameter in the route template. Wenn mehr als eine Route mit einem Aktionsparameter übereinstimmt, gilt jeder Routenwert als [FromRoute].When more than one route matches an action parameter, any route value is considered [FromRoute].
  • [FromQuery] wird für alle anderen Aktionsparameter abgeleitet.[FromQuery] is inferred for any other action parameters.

Hinweise zum FromBody-RückschlussFromBody inference notes

[FromBody] wird für einfache Typen wie string oder int nicht abgeleitet.[FromBody] isn't inferred for simple types such as string or int. Deshalb sollte das [FromBody]-Attribut für einfache Typen verwendet werden, wenn diese Funktionsweise benötigt wird.Therefore, the [FromBody] attribute should be used for simple types when that functionality is needed.

Wenn an eine Aktion mehr als ein Parameter aus dem Anforderungstext gebunden ist, wird eine Ausnahme ausgelöst.When an action has more than one parameter bound from the request body, an exception is thrown. Beispielsweise lösen alle Signaturen der folgenden Aktionsmethoden eine Ausnahme aus:For example, all of the following action method signatures cause an exception:

  • [FromBody] wird für beide abgeleitet, da sie komplexe Typen darstellen.[FromBody] inferred on both because they're complex types.

    [HttpPost]
    public IActionResult Action1(Product product, Order order)
    
  • Das [FromBody]-Attribut für einen Typ wird für den anderen abgeleitet, da es sich um einen komplexen Typ handelt.[FromBody] attribute on one, inferred on the other because it's a complex type.

    [HttpPost]
    public IActionResult Action2(Product product, [FromBody] Order order)
    
  • Das [FromBody]-Attribut für beide.[FromBody] attribute on both.

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

Hinweis

In ASP.NET Core 2.1 werden Sammlungstypparameter wie Listen und Arrays fälschlicherweise als [FromQuery] abgeleitet.In ASP.NET Core 2.1, collection type parameters such as lists and arrays are incorrectly inferred as [FromQuery]. Für diese Parameter sollte das [FromBody]-Attribut verwendet werden, wenn sie aus dem Anforderungstext gebunden werden sollen.The [FromBody] attribute should be used for these parameters if they are to be bound from the request body. Dieses Verhalten wurde bei ASP.NET Core 2.2 oder höher behoben. Hier werden Sammlungstypparameter standardmäßig als „[FromBody]“ abgeleitet.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.

Deaktivieren von RückschlussregelnDisable inference rules

Legen Sie SuppressInferBindingSourcesForParameters auf true fest, um den Rückschluss auf Bindungsquellen zu deaktivieren.To disable binding source inference, set SuppressInferBindingSourcesForParameters to true. Fügen Sie den folgenden Code zu Startup.ConfigureServices hinzu: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;
});

Ableiten der Multipart/form-data-AnforderungMultipart/form-data request inference

Das [ApiController]-Attribut wendet eine Rückschlussregel an, wenn ein Aktionsparameter mit dem [FromForm]-Attribut kommentiert ist.The [ApiController] attribute applies an inference rule when an action parameter is annotated with the [FromForm] attribute. Der multipart/form-data-Anforderungsinhaltstyp wird abgeleitet.The multipart/form-data request content type is inferred.

Legen Sie die SuppressConsumesConstraintForFormFileParameters-Eigenschaft auf true in Startup.ConfigureServices fest, um das Standardverhalten zu deaktivieren.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;
});

Problemdetails für FehlerstatuscodesProblem details for error status codes

Bei Kompatibilitätsversion 2.2 oder höher wandelt MVC ein Fehlerergebnis (ein Ergebnis mit dem Statuscode 400 oder höher) in ein Ergebnis mit ProblemDetails um.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. Die ProblemDetails-Typ basiert auf der RFC 7807-Spezifikation für die Bereitstellung maschinenlesbarer Fehlerdetails in einer HTTP-Antwort.The ProblemDetails type is based on the RFC 7807 specification for providing machine-readable error details in an HTTP response.

Betrachten Sie den folgenden Code in einer Controlleraktion:Consider the following code in a controller action:

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

Die NotFound-Methode erzeugt einen HTTP-404-Statuscode mit einem ProblemDetails-Text.The NotFound method produces an HTTP 404 status code with a ProblemDetails body. Zum Beispiel:For example:

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

Deaktivieren der ProblemDetails-AntwortDisable ProblemDetails response

Die automatische Erstellung einer ProblemDetails-Antwort für Fehlerstatuscodes ist deaktiviert, wenn die SuppressMapClientErrors-Eigenschaft auf true festgelegt ist.The automatic creation of a ProblemDetails for error status codes is disabled when the SuppressMapClientErrors property is set to true. Fügen Sie den folgenden Code zu Startup.ConfigureServices hinzu: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";
    });

Definieren unterstützter Anforderungsinhaltstypen mit dem [Consumes]-AttributDefine supported request content types with the [Consumes] attribute

Standardmäßig unterstützt eine Aktion alle verfügbaren Anforderungsinhaltstypen.By default, an action supports all available request content types. Wenn eine App beispielsweise zur Unterstützung von JSON- und XML-Eingabeformatierern konfiguriert ist, unterstützt eine Aktion mehrere Inhaltstypen, wie etwa application/json und 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.

Das [Consumes]-Attribut ermöglicht es einer Aktion, die unterstützten Anforderungsinhaltstypen einzuschränken.The [Consumes] attribute allows an action to limit the supported request content types. Wenden Sie das [Consumes]-Attribut auf eine Aktion oder einen Controller an, und geben Sie mindestens einen Inhaltstyp an:Apply the [Consumes] attribute to an action or controller, specifying one or more content types:

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

Im obigen Code gibt die CreateProduct-Aktion den Inhaltstyp application/xml an.In the preceding code, the CreateProduct action specifies the content type application/xml. Anforderungen, die an diese Aktion weitergeleitet werden, müssen den Content-Type-Header application/xml angeben.Requests routed to this action must specify a Content-Type header of application/xml. Für Anforderungen, die den Content-Type-Header application/xml nicht angeben, wird die Antwort 415 – Nicht unterstützter Medientyp zurückgegeben.Requests that don't specify a Content-Type header of application/xml result in a 415 Unsupported Media Type response.

Das [Consumes]-Attribut ermöglicht es einer Aktion auch, eine Typeinschränkung anzuwenden, um die Auswahl basierend auf dem Inhaltstyp einer eingehenden Anforderung zu beeinflussen.The [Consumes] attribute also allows an action to influence its selection based on an incoming request's content type by applying a type constraint. Betrachten Sie das folgende Beispiel: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 });
}

Im obigen Code ist ConsumesController zur Verarbeitung von Anforderungen konfiguriert, die an die URL https://localhost:5001/api/Consumes gesendet werden.In the preceding code, ConsumesController is configured to handle requests sent to the https://localhost:5001/api/Consumes URL. Beide Controlleraktionen – PostJson und PostForm – verarbeiten POST-Anforderungen mit derselben URL.Both of the controller's actions, PostJson and PostForm, handle POST requests with the same URL. Wenn das [Consumes]-Attribut keine Typeinschränkung anwendet, wird eine Ausnahme in Bezug auf eine mehrdeutige Übereinstimmung ausgelöst.Without the [Consumes] attribute applying a type constraint, an ambiguous match exception is thrown.

Das [Consumes]-Attribut wird auf beide Aktionen angewendet.The [Consumes] attribute is applied to both actions. Die PostJson-Aktion verarbeitet Anforderungen, die mit dem Content-Type-Header application/json gesendet werden.The PostJson action handles requests sent with a Content-Type header of application/json. Die PostForm-Aktion verarbeitet Anforderungen, die mit dem Content-Type-Header application/x-www-form-urlencoded gesendet werden.The PostForm action handles requests sent with a Content-Type header of application/x-www-form-urlencoded.

Zusätzliche RessourcenAdditional resources