Neue Funktionen in ASP.NET-Web-API 2.1
von Microsoft
In diesem Thema werden die Neuerungen für ASP.NET-Web-API 2.1 beschrieben.
Herunterladen
Die Laufzeitfeatures werden als NuGet-Pakete im NuGet-Katalog veröffentlicht. Alle Laufzeitpakete entsprechen der Spezifikation für 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. Das Release enthält auch entsprechende lokalisierte Pakete auf NuGet.
Sie können die veröffentlichten NuGet-Pakete installieren oder aktualisieren, indem Sie die NuGet-Paket-Manager-Konsole verwenden:
Install-Package Microsoft.AspNet.WebApi -Version 5.1.2
Dokumentation
Tutorials 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 nicht behandelten Ausnahmen können jetzt über einen zentralen Mechanismus protokolliert werden, und das Verhalten für nicht behandelte Ausnahmen kann angepasst werden.
Das Framework unterstützt mehrere Ausnahmeprotokollierungen, die alle die nicht behandelte Ausnahme und Informationen über den Kontext anzeigen, in dem sie aufgetreten ist, z. B. die Anforderung, die zu diesem Zeitpunkt verarbeitet wird.
Der folgende Code verwendet beispielsweise System.Diagnostics.TraceSource, um alle nicht behandelten 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 Standardausnahmehandler ersetzen, sodass Sie die HTTP-Antwortnachricht vollständig anpassen können, die gesendet wird, wenn eine nicht behandelte Ausnahme auftritt.
Wir haben ein Beispiel bereitgestellt, das alle nicht behandelten Ausnahmen über das beliebte ELMAH-Framework protokolliert.
Verbesserungen des Attributroutings
Attributrouting unterstützt jetzt Einschränkungen und ermöglicht die Versionsverwaltung und die headerbasierte Routenauswahl. Außerdem 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 die 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
Die 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
Die 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 mit einer angegebenen Vorlage übereinstimmen, und der Host kann ggf. zusätzliche Verarbeitung anwenden.
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
Die Web-API unterstützt jetzt das BSON-Wire-Format , sowohl auf dem Client als auch auf dem Server.
Um BSON auf der Serverseite zu aktivieren, fügen Sie der Formattersammlung 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 die Client- als auch die Serverseite zeigt.
Weitere Informationen finden Sie unter BSON-Unterstützung in Web-API 2.1
Bessere Unterstützung für asynchrone Filter
Die 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. auf eine Datenbank zugreifen. 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 überschreiben.
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
Bisher unterstützte System.Net.Http.Formatierung die Analyse und Aktualisierung von URI-Abfragen für serverseitigen Code, aber in der entsprechenden portablen Bibliothek fehlte dieses Feature. In Der 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 der Einfachheit halber eine Konsolenanwendung.)
// 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 Breaking Changes im ASP.NET-Web-API 2.1 RTM beschrieben.
Attributrouting
Mehrdeutigkeiten in Attributrouting-Übereinstimmungen melden jetzt einen Fehler, anstatt die erste Übereinstimmung auszuwählen.
Attributrouten ist es untersagt, den {controller}- Parameter und den {action} -Parameter für Routen zu verwenden, die für Aktionen platziert werden. Diese Parameter würden sehr wahrscheinlich zu Mehrdeutigkeiten führen.
Das Gerüstieren der MVC/Web-API in ein Projekt mit 5.1-Paketen führt zu 5.0-Paketen für Pakete, die noch nicht im Projekt vorhanden sind
Durch das Aktualisieren von NuGet-Paketen für ASP.NET-Web-API 2.1 RTM werden die Visual Studio-Tools nicht aktualisiert, z. B. ASP.NET Gerüste oder die Projektvorlage ASP.NET Webanwendung. Sie verwenden die vorherige Version der ASP.NET Runtimepakete (5.0.0.0). Daher installiert das ASP.NET Gerüstbau die vorherige Version (5.0.0.0) 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 auf Web-API 2.1 oder ASP.NET MVC 5.1 verwenden, stellen Sie sicher, dass die Versionen von Web-API und MVC konsistent sind.
Typbenennungen
Einige der Typen, die für die Erweiterbarkeit des Attributroutings verwendet wurden, wurden vom RC in 2.1 RTM umbenannt.
| Alter Typname (2.1 RC) | Neuer Typname (2.1 RTM) |
|---|---|
| IDirectRouteProvider | IDirectRouteFactory |
| RouteProviderAttribute | RouteFactoryAttribute |
| DirectRouteProviderContext | DirectRouteFactoryContext |
Ausnahmefilter entpacken keine Aggregatausnahmen, die in asynchronen Aktionen ausgelöst werden
Wenn zuvor eine asynchrone Aktion eine AggregateException ausgelöst hat, hat ein Ausnahmefilter die Ausnahme entpackt, und OnException hat die Basisausnahme abgerufen. In Version 2.1 wird der Ausnahmefilter nicht entpackt, und OnException ruft die ursprüngliche AggregateException ab.
Fehlerkorrekturen
Dieses Release enthält auch mehrere Fehlerbehebungen.
Das Paket 5.1.2 enthält IntelliSense-Updates, aber keine Fehlerbehebungen.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für