Freigeben über

Neue Funktionen in ASP.NET-Web-API 2.2

  • Artikel

von Microsoft

In diesem Thema werden die Neuerungen für ASP.NET-Web-API 2.2 beschrieben.

Herunterladen

Die Laufzeitfeatures werden als NuGet-Pakete im NuGet-Katalog veröffentlicht. Alle Laufzeitpakete folgen der Spezifikation für die semantische Versionsverwaltung . Das neueste ASP.NET-Web-API 2.2-Paket weist die folgende Version auf: "5.2.0". Sie können diese Pakete über NuGet installieren oder aktualisieren. Das Release enthält auch entsprechende lokalisierte Pakete in NuGet.

Sie können die veröffentlichten NuGet-Pakete mithilfe der NuGet-Paket-Manager-Konsole installieren oder aktualisieren:

Install-Package Microsoft.AspNet.WebApi -Version 5.2.0

Dokumentation

Tutorials und weitere Informationen zu ASP.NET-Web-API 2.2 sind auf der ASP.NET-Website (https://www.asp.net/web-api) verfügbar.

Neue Features in ASP.NET-Web-API 2.2

OData v4

Dieses Release fügt Unterstützung für das OData v4-Protokoll hinzu. Weitere Informationen finden Sie in der OData v4-Dokumentation der Web-API.

Hier sind einige der wichtigsten Features und Änderungen für OData v4:

Verbesserungen beim Attributrouting

Attributrouting bietet jetzt einen Erweiterbarkeitspunkt namens IDirectRouteProvider, der die vollständige Kontrolle darüber ermöglicht, wie Attributrouten ermittelt und konfiguriert werden. Ein IDirectRouteProvider ist dafür verantwortlich, eine Liste von Aktionen und Controllern zusammen mit zugehörigen Routeninformationen bereitzustellen, um genau anzugeben, welche Routingkonfiguration für diese Aktionen gewünscht wird. Beim Aufrufen von MapAttributes/MapHttpAttributeRoutes kann eine IDirectRouteProvider-Implementierung angegeben werden.

Das Anpassen von IDirectRouteProvider ist am einfachsten, indem wir unsere Standardimplementierung DefaultDirectRouteProvider erweitern. Diese Klasse stellt separate überschreibbare virtuelle Methoden bereit, um die Logik zum Ermitteln von Attributen, zum Erstellen von Routeneinträgen und zum Ermitteln von Routenpräfixen und Bereichspräfixen zu ändern.

Im Folgenden sind einige Beispiele für die Möglichkeiten dieses neuen Erweiterbarkeitspunkts aufgeführt:

  1. Unterstützung der Vererbung von Routenattributen

    Beispiel:

    Hier würde eine Anforderung wie "/api/values/10" erfolgreich "Success:10" zurückgeben.

    public class BaseController : ApiController
{
    [Route("{id:int}")]
    public string Get(int id)
    {
        return "Success:" + id;
    }
}
[RoutePrefix("api/values")]
public class ValuesController : BaseController
{
}
       
config.MapHttpAttributeRoutes(new CustomDirectRouteProvider());
public class CustomDirectRouteProvider : DefaultDirectRouteProvider
{
    protected override IReadOnlyList<IDirectRouteFactory> 
    GetActionRouteFactories(HttpActionDescriptor actionDescriptor)
    {
        return actionDescriptor.GetCustomAttributes<IDirectRouteFactory>
        (inherit: true);
    }
}

  2. Geben Sie einen Standardroutennamen für Ihre Attributrouten an, indem Sie eine von Ihnen gewünschte Konvention verwenden. Standardmäßig werden beim Attributrouting nicht automatisch Namen für Attributrouten erstellt.

  3. Ändern Sie die Routenvorlage für Attributrouten an einer zentralen Stelle, bevor sie in der Routingtabelle landen.

Web-API-Clientunterstützung für Windows Phone 8.1

Sie können jetzt das Web-API-Client-NuGet-Paket verwenden, um Ihre Web-API-Clientlogik zu implementieren, wenn sie Windows Phone 8.1 oder innerhalb einer universellen App ausgerichtet ist.

Bekannte Probleme und Breaking Changes

In diesem Abschnitt werden bekannte Probleme und Breaking Changes im ASP.NET-Web-API 2.2 beschrieben.

OData v4

Modell-Generator

Problem: Überladene Funktionen konnten nicht als FunctionImport verfügbar gemacht werden.

Wenn zwei überladene Funktionen vorhanden sind und diese ebenfalls FunctionImport sind, wie unten gezeigt, führt das Anfordern von ~/GetAllConventionCustomers(CustomerName={customerName}) zu System.InvalidOperationException.

<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true" />
<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true">
<Parameter Name="CustomerName" Type="Edm.String" FixedLength="false" 
Unicode="false" />
</Function>
...
<FunctionImport Name="GetAllConventionCustomers" 
Function="WebStack.QA.Test.OData.UnboundOperation.GetAllConventionCustomers" 
EntitySet="ConventionCustomers" IncludeInServiceDocument="true" />

Problemumgehung: Die Problemumgehung für dieses Problem besteht darin, beide Funktionsüberladungen als FunctionImports hinzuzufügen.

OData-Routing

Zeichenfolgenliterale, die den URL-codierten Schrägstrich (%2F) und den umgekehrten Schrägstrich(%5C) enthalten, verursachen einen 404-Fehler, wenn sie in den OData-Ressourcenpfaden verwendet werden.

Beispielsweise können Zeichenfolgenliterale in den OData-Ressourcenpfaden als Parameter von Funktionen oder Schlüsselwerten von Entitätssätzen verwendet werden.

/Employees/Total.GetCount(Name='Name%2F')

/Employees('Name%5C')

Wenn Dienste solche Anforderungen empfangen, heben die Hosts die Escapesequenzen auf, bevor sie an die Web-API-Runtime übergeben werden. Dies schützt vor Angriffen wie den folgenden:

http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:

Dies führt dazu, dass der OData-Stapel der Web-API den Fehler 404 (Nicht gefunden) zurückgibt. Um diesen Fehler zu vermeiden, sollte Ihr Client die doppelten Escapesequenzen für Schrägstrich (%252F) und umgekehrten Schrägstrich (%255C) verwenden. Dies geschieht nicht für Abfragezeichenfolgen wie /Employees?$filter=Name eq 'Name%2F'

Beachten Sie, dass schräge Schrägstriche ohne Escapezeichen ("/" ) und umgekehrte Schrägstriche ("'") in OData-Ressourcenpfad-Zeichenfolgenliteralen nicht zulässig sind. Schrägstriche sollten nur als Pfadtrennzeichen angezeigt werden, und umgekehrte Schrägstriche sollten im OData-Ressourcenpfad überhaupt nicht angezeigt werden. (Beide können in einigen Teilen einer OData-Abfragezeichenfolge verwendet werden.)

Problemumgehung: Sie können die Parse-Methode von DefaultODataPathHandler überschreiben, um den Schrägstrich und den umgekehrten Schrägstrich in Zeichenfolgenliteralen zu escapen, bevor sie tatsächlich analysiert werden. Ein Beispiel für diesen Ansatz finden Sie hier.

OData v3

[Abfragbar]

Das [Queryable]-Attribut ist veraltet. Neue OData v3-Anwendungen sollten System.Web.Http.OData.EnableQueryAttribute verwenden.

Die ODataHttpConfigurationExtensions.EnableQuerySupport-Erweiterungsmethode fügt der globalen Filterauflistung jetzt ein EnableQueryAttribute hinzu. Wenn Controller über das [Queryable]- Attribut verfügen, führt das Aufrufen config.EnableQuerySupport() des [Queryable] -Attributs zu einem Fehler.

Die empfohlene Methode zum Beheben dieses Problems besteht darin, alle Instanzen von QueryableAttribute durch System.Web.Http.OData.EnableQueryAttribute zu ersetzen.

Eine alternative Problemumgehung besteht darin, den folgenden Code in Ihrer Web-API-Konfiguration zu verwenden:

config.EnableQuerySupport(new QueryableAttribute());

Attributrouting

Problem: Die Modellbindung eines komplexen Typs, der mit dem FromUri-Attribut versehen ist, verhält sich bei Verwendung von Attributrouting anders.

Problem: Das Gerüstbau der MVC/Web-API in ein Projekt mit 5.2.0-Paketen führt zu 5.1.2-Paketen für Pakete, die noch nicht im Projekt vorhanden sind.

Durch das Aktualisieren von NuGet-Paketen für ASP.NET MVC 5.2 werden die Visual Studio-Tools wie ASP.NET Gerüstbau oder die Projektvorlage ASP.NET Webanwendung nicht aktualisiert. Sie verwenden die vorherige Version der ASP.NET Runtimepakete (z. B. 5.1.2 in Update 2). Daher installiert das ASP.NET Gerüstbau die vorherige Version (z. B. 5.1.2 in Update 2) der erforderlichen Pakete, sofern diese nicht bereits in Ihren Projekten verfügbar sind. Das ASP.NET Gerüstbau in Visual Studio 2013 RTM oder Update 1 überschreibt jedoch nicht die neuesten Pakete in Ihren Projekten. Wenn Sie ASP.NET Gerüstbau nach dem Aktualisieren der Pakete Ihrer Projekte auf Web-API 2.2 oder ASP.NET MVC 5.2 verwenden, stellen Sie sicher, dass die Versionen der Web-API und ASP.NET MVC konsistent sind.

Microsoft.AspNet.OData 5.2.1

Das Paket Microsoft.AspNet.OData 5.2.1 enthält NuGet-Abhängigkeitsupdates, aber keine Fehlerbehebungen. Mit diesem Update besteht keine strikte Abhängigkeit von Microsoft.OData.Core 6.4.0 mehr, aber man kann ein Upgrade auf jede Version zwischen 6.4.0 und 7.0.0 durchführen.

Microsoft.AspNet.WebAPI 5.2.2

In diesem Release haben wir eine Abhängigkeitsänderung für Json.Net 6.0.4vorgenommen. Weitere Informationen zu den Neuerungen in dieser Version von Json.NETfinden Sie unter Json.NET 6.0 Release 4 – JSON Merge, Dependency Injection. Dieses Release enthält keine weiteren neuen Features oder Fehlerbehebungen in der Web-API. Wir haben anschließend alle anderen abhängigen Pakete, die wir besitzen, aktualisiert, um von dieser neuen Version der Web-API abhängig zu sein.

Microsoft.AspNet.WebAPI 5.2.3 Beta

Informationen zum Release finden Sie hier. Dieses Release enthält nur Fehlerbehebungen.