Neuerungen in ASP.NET Web-API 2.1

von Microsoft

In diesem Thema wird beschrieben, was für ASP.NET Web-API 2.1 neu ist.

• Download

• Dokumentation

• Neue Features in ASP.NET Web-API 2.1

  • Globale Fehlerbehandlung
  • Verbesserungen beim Attributrouting
  • Verbesserungen der Hilfeseite
  • IgnoreRoute-Unterstützung
  • BSON-Media-Type-Formatierer
  • Bessere Unterstützung für Async-Filter
  • Abfrageanalyse für die Clientformatierungsbibliothek

• Bekannte Probleme und wichtige Änderungen

• Fehlerkorrekturen

Herunterladen

Die Laufzeitfeatures werden als NuGet-Pakete in der NuGet-Galerie veröffentlicht. Alle Laufzeitpakete folgen der Spezifikation für die semantische Versionsverwaltung . Das neueste ASP.NET Web-API 2.1 RTM-Paket hat die folgende Version: "5.1.2". Sie können diese Pakete über NuGet installieren oder aktualisieren. Die Version enthält auch entsprechende lokalisierte Pakete auf 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.1.2

Dokumentation

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

Neue Features in ASP.NET Web-API 2.1

Globale Fehlerbehandlung

Alle unbehandelten Ausnahmen können jetzt über einen zentralen Mechanismus protokolliert werden, und das Verhalten für unbehandelte Ausnahmen kann angepasst werden.

Das Framework unterstützt mehrere Ausnahmeprotokollierer, die alle die unbehandelte Ausnahme und Informationen zum Kontext sehen, in dem sie aufgetreten sind, z. B. die zu diesem Zeitpunkt verarbeitete Anforderung.

Der folgende Code verwendet beispielsweise System.Diagnostics.TraceSource, um alle unbehandelten Ausnahmen zu protokollieren:

public class TraceSourceExceptionLogger : ExceptionLogger
{
    private readonly TraceSource _traceSource;

    public TraceSourceExceptionLogger(TraceSource traceSource)
    {
        _traceSource = traceSource;
    }

    public override void Log(ExceptionLoggerContext context)
    {
        _traceSource.TraceEvent(TraceEventType.Error, 1,
            "Unhandled exception processing {0} for {1}: {2}",
            context.Request.Method,
            context.Request.RequestUri,
            context.Exception);
    }
}

config.Services.Add(typeof(IExceptionLogger), 
    new TraceSourceExceptionLogger(new 
    TraceSource("MyTraceSource", SourceLevels.All)));

Sie können auch den Standard-Ausnahmehandler ersetzen, sodass Sie die HTTP-Antwortnachricht, die gesendet wird, vollständig anpassen können, wenn eine unbehandelte Ausnahme auftritt.

Wir haben ein Beispiel bereitgestellt, das alle unbehandelten Ausnahmen über das beliebte ELMAH-Framework protokolliert.

Verbesserungen beim Attributrouting

Attributrouting unterstützt jetzt Einschränkungen und ermöglicht die Versionsverwaltung und die headerbasierte Routenauswahl. Darüber hinaus können viele Aspekte von Attributrouten jetzt über die IDirectRouteFactory-Schnittstelle und die RouteFactoryAttribute-Klasse angepasst werden. Das Routenpräfix ist jetzt über die IRoutePrefix-Schnittstelle und routePrefixAttribute-Klasse erweiterbar.

Wir haben ein Beispiel bereitgestellt, das Einschränkungen verwendet, um Controller dynamisch nach einem HTTP-Header "api-version" zu filtern.

Verbesserungen der Hilfeseite

Web-API 2.1 enthält die folgenden Verbesserungen für API-Hilfeseiten:

• Dokumentation einzelner Eigenschaften von Parametern oder Rückgabetypen von Aktionen.
• Dokumentation von Datenmodellanmerkungen.

Das UI-Design der Hilfeseiten wurde ebenfalls aktualisiert, um diese Änderungen zu berücksichtigen.

IgnoreRoute-Unterstützung

Web-API 2.1 unterstützt das Ignorieren von URL-Mustern im Web-API-Routing über eine Reihe von IgnoreRoute-Erweiterungsmethoden in HttpRouteCollection. Diese Methoden führen dazu, dass die Web-API alle URLs ignoriert, die einer angegebenen Vorlage entsprechen, und zulassen, dass der Host ggf. zusätzliche Verarbeitungen anwendet.

Im folgenden Beispiel werden URIs ignoriert, die mit einem "content"-Segment beginnen:

routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");

BSON-Media-Type-Formatierer

Web-API unterstützt jetzt das BSON-Drahtformat sowohl auf dem Client als auch auf dem Server.

Um BSON auf serverseitiger Seite zu aktivieren, fügen Sie der Formattersauflistung den BsonMediaTypeFormatter hinzu:

config.Formatters.Add(new BsonMediaTypeFormatter());

So kann ein .NET-Client das BSON-Format nutzen:

// Add Accept header.
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/bson"));

// POST data in BSON format.
HttpResponseMessage response = await client.PostAsync<MyData>("api/MyData", data, new 
BsonMediaTypeFormatter());

// GET data in BSON format.
data = await response.Content.ReadAsAsync<MyData>(new MediaTypeFormatter[] { 
  new BsonMediaTypeFormatter() });

Wir haben ein Beispiel bereitgestellt, das sowohl client- als auch serverseitig zeigt.

Weitere Informationen finden Sie unter BSON-Support in Web API 2.1

Bessere Unterstützung für Async-Filter

Web-API unterstützt jetzt eine einfache Möglichkeit zum Erstellen von Filtern, die asynchron ausgeführt werden. Dieses Feature ist nützlich, wenn Ihr Filter eine asynchrone Aktion ausführen muss, z. B. zugriff auf eine Datenbank. Zuvor mussten Sie zum Erstellen eines asynchronen Filters die Filterschnittstelle selbst implementieren, da die Filterbasisklassen nur synchrone Methoden verfügbar gemacht haben. Jetzt können Sie die virtuellen On*Async Methoden der Filterbasisklasse außer Kraft setzen.

Beispiel:

public class AsyncLoggingFilter : ActionFilterAttribute
{
    public override async Task OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)
    {
        await Trace.WriteAsync("Executing action named {0} for request {1}.", 
            actionContext.ActionDescriptor.ActionName, 
            actionContext.Request.GetCorrelationId());
    }
}

Die Klassen AuthorizationFilterAttribute, ActionFilterAttribute und ExceptionFilterAttribute unterstützen alle asynchron in Web API 2.1.

Abfrageanalyse für die Clientformatierungsbibliothek

Zuvor unterstützte System.Net.Http.Formatting das Analysieren und Aktualisieren von URI-Abfragen für serverseitigen Code, aber die entsprechende portable Bibliothek fehlte dieses Feature. In Web-API 2.1 kann eine Clientanwendung jetzt einfach eine Abfragezeichenfolge analysieren und aktualisieren.

Die folgenden Beispiele zeigen, wie URI-Abfragen analysiert, geändert und generiert werden. (Die Beispiele zeigen eine Konsolenanwendung zur Vereinfachung.)

// Query parsing
HttpValueCollection collection = new Uri("http://api/something?catId=3&catId=4&dogId=1,2").ParseQueryString();

Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2

// Modify the query
collection.Add("dogId", "7");

// Index into the values
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2,7

// Recreate the query string
Console.WriteLine(collection.ToString()); // output: catId=3&catId=4&dogId=1%2C2&dogId=7

// Query generation
HttpValueCollection newCollection = new HttpValueCollection();

newCollection.Add("catId", "1");
newCollection.Add("dogId", "7");

// Index into the values
Console.WriteLine(newCollection["catId"]); // output: 1
Console.WriteLine(newCollection["dogId"]); // output: 7

// Create the query string
Console.WriteLine(newCollection.ToString()); // catId=1&dogId=7

Bekannte Probleme und wichtige Änderungen

In diesem Abschnitt werden bekannte Probleme und wichtige Änderungen in der ASP.NET Web-API 2.1 RTM beschrieben.

Attributrouting

Mehrdeutigkeiten im Attributrouting melden jetzt einen Fehler, anstatt die erste Übereinstimmung auszuwählen.

Attributrouten ist die Verwendung des {controller}-Parameters untersagt, und die Verwendung des {action}-Parameters in Routen, die auf Aktionen angewendet werden. Diese Parameter würden sehr wahrscheinlich zu Mehrdeutigkeiten führen.

Das Einfügen der MVC/Web-API in ein Projekt mit 5.1-Paketen führt zu 5.0-Paketen für diejenigen, die noch nicht im Projekt vorhanden sind.

Das Aktualisieren von NuGet-Paketen für ASP.NET Web-API 2.1 RTM aktualisiert nicht die Visual Studio-Tools, z. B. ASP.NET Gerüst oder die ASP.NET Webanwendungsprojektvorlage. Sie verwenden die vorherige Version der ASP.NET Laufzeitpakete (5.0.0.0.0). Daher installiert das ASP.NET Gerüst die vorherige Version (5.0.0.0.0) der erforderlichen Pakete, sofern sie in Ihren Projekten noch nicht verfügbar sind. Das ASP.NET Gerüst in Visual Studio 2013 RTM oder Update 1 überschreibt jedoch nicht die neuesten Pakete in Ihren Projekten.

Wenn Sie ASP.NET Gerüst verwenden, nachdem Sie die Pakete auf Web API 2.1 oder ASP.NET MVC 5.1 aktualisiert haben, stellen Sie sicher, dass die Versionen von Web-API und MVC konsistent sind.

Umbenennungen von Typen

Einige der Typen, die für die Attributweiterleitung verwendet werden, wurden vom RC in 2.1 RTM umbenannt.

Ausnahmefilter lösen keine aggregierten Ausnahmen aus, die in asynchronen Aktionen ausgelöst werden

Früher, wenn eine asynchrone Aktion eine AggregateException ausgelöst hat, würde ein Ausnahmefilter die Ausnahme entpacken, und OnException würde die Basisausnahme abrufen. In 2.1 wird die Ausnahme nicht vom Filter entpackt, und OnException erhält die ursprüngliche AggregateException.

Fehlerkorrekturen

Diese Version enthält auch mehrere Fehlerbehebungen.

Das 5.1.2-Paket enthält IntelliSense-Updates, aber keine Fehlerbehebungen.