Co nowego we wzorcu ASP.NET Web API 2.1

Artykuł
06/16/2023

W tym temacie opisano nowości dotyczące ASP.NET internetowego interfejsu API 2.1.

Pobieranie
Dokumentacja
Nowe funkcje w interfejsie API sieci Web ASP.NET 2.1
Znane problemy i zmiany powodujące niezgodność
Poprawki błędów

Pobierz

Funkcje środowiska uruchomieniowego są wydawane jako pakiety NuGet w galerii NuGet. Wszystkie pakiety uruchomieniowe są zgodne ze specyfikacją semantycznego przechowywania wersji . Najnowszy pakiet internetowego interfejsu API 2.1 RTM ASP.NET ma następującą wersję: "5.1.2". Te pakiety można zainstalować lub zaktualizować za pomocą narzędzia NuGet. Wydanie zawiera również odpowiednie zlokalizowane pakiety w usłudze NuGet.

Możesz zainstalować lub zaktualizować wydane pakiety NuGet przy użyciu konsoli Menedżera pakietów NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Dokumentacja

Samouczki i inne informacje o ASP.NET Web API 2.1 RTM są dostępne w witrynie internetowej ASP.NET (https://www.asp.net/web-api).

Nowe funkcje w interfejsie API sieci Web ASP.NET 2.1

Globalna obsługa błędów

Wszystkie nieobsługiwane wyjątki można teraz rejestrować za pomocą jednego centralnego mechanizmu, a zachowanie nieobsługiwane wyjątki można dostosować.

Platforma obsługuje wiele rejestratorów wyjątków, które widzą nieobsługiwany wyjątek i informacje o kontekście, w którym wystąpił, na przykład w czasie przetwarzania żądania.

Na przykład poniższy kod używa elementu System.Diagnostics.TraceSource do rejestrowania wszystkich nieobsługiwanych wyjątków:

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

Możesz również zastąpić domyślną procedurę obsługi wyjątków, aby można było w pełni dostosować komunikat odpowiedzi HTTP wysyłany po wystąpieniu nieobsługiwanego wyjątku.

Udostępniliśmy przykład , który rejestruje wszystkie nieobsługiwane wyjątki za pośrednictwem popularnej platformy ELMAH.

Ulepszenia routingu atrybutów

Routing atrybutów obsługuje teraz ograniczenia, włączając wybór wersji i trasy opartej na nagłówku. Ponadto wiele aspektów tras atrybutów można teraz dostosowywać za pośrednictwem interfejsu IDirectRouteFactory i klasy RouteFactoryAttribute . Prefiks trasy jest teraz rozszerzalny za pośrednictwem interfejsu IRoutePrefix i klasy RoutePrefixAttribute .

Udostępniliśmy przykład , który używa ograniczeń do dynamicznego filtrowania kontrolerów według nagłówka HTTP "api-version".

Ulepszenia strony pomocy

Internetowy interfejs API 2.1 zawiera następujące ulepszenia stron pomocy interfejsu API:

Dokumentacja poszczególnych właściwości parametrów lub zwracanych typów akcji.
Dokumentacja adnotacji modelu danych.

Zaktualizowano również projekt interfejsu użytkownika stron pomocy, aby uwzględnić te zmiany.

Ignoruj obsługę usługiRoute

Internetowy interfejs API 2.1 obsługuje ignorowanie wzorców adresów URL w routingu interfejsu API sieci Web za pośrednictwem zestawu metod rozszerzeń IgnoreRoute w usłudze HttpRouteCollection. Te metody powodują, że internetowy interfejs API ignoruje wszystkie adresy URL zgodne z określonym szablonem i umożliwiają hostowi zastosowanie dodatkowego przetwarzania w razie potrzeby.

Poniższy przykład ignoruje identyfikatory URI rozpoczynające się od segmentu "content":

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

Formater Media-Type BSON

Internetowy interfejs API obsługuje teraz format przewodu BSON , zarówno na kliencie, jak i na serwerze.

Aby włączyć kod BSON po stronie serwera, dodaj obiekt BsonMediaTypeFormatter do kolekcji formaterów:

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

Oto jak klient platformy .NET może korzystać z formatu BSON:

// 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() });

Udostępniliśmy przykład pokazujący zarówno po stronie klienta, jak i serwera.

Aby uzyskać więcej informacji, zobacz Obsługa formatu BSON w internetowym interfejsie API 2.1

Lepsza obsługa filtrów asynchronicznych

Internetowy interfejs API obsługuje teraz łatwy sposób tworzenia filtrów wykonywanych asynchronicznie. Ta funkcja jest przydatna, ponieważ filtr wymaga wykonania akcji asynchronicznych, takiej jak dostęp do bazy danych. Wcześniej, aby utworzyć filtr asynchroniczny, trzeba było samodzielnie zaimplementować interfejs filtru, ponieważ klasy podstawowe filtru uwidoczniły tylko metody synchroniczne. Teraz możesz zastąpić metody wirtualne On*Async klasy bazowej filtru.

Na przykład:

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

Klasy AuthorizationFilterAttribute, ActionFilterAttribute i ExceptionFilterAttribute obsługują asynchroniczne w interfejsie Web API 2.1.

Analizowanie zapytań dla biblioteki formatowania klienta

Wcześniej obsługiwane jest analizowanie i aktualizowanie zapytań identyfikatora URI dla kodu po stronie serwera, ale brakuje tej funkcji równoważnej biblioteki przenośnej. W internetowym interfejsie API 2.1 aplikacja kliencka może teraz łatwo analizować i aktualizować ciąg zapytania.

W poniższych przykładach pokazano, jak analizować, modyfikować i generować zapytania identyfikatora URI. (Przykłady pokazują aplikację konsolową dla uproszczenia).

// 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

Znane problemy i zmiany powodujące niezgodność

W tej sekcji opisano znane problemy i zmiany powodujące niezgodność w interfejsie API sieci Web ASP.NET 2.1 RTM.

Routing atrybutów

Niejednoznaczności w routingu atrybutów są teraz raportowane błąd zamiast wybierania pierwszego dopasowania.

Trasy atrybutów nie mogą używać parametru {controller} i z używania parametru {action} dla tras umieszczonych w akcjach. Te parametry byłyby bardzo prawdopodobne, co spowodowałoby niejednoznaczność.

Tworzenie szkieletu interfejsu MVC/internetowego interfejsu API w projekcie z pakietami 5.1 powoduje utworzenie pakietów 5.0 dla tych, które jeszcze nie istnieją w projekcie

Aktualizowanie pakietów NuGet dla ASP.NET web API 2.1 RTM nie aktualizuje narzędzi programu Visual Studio, takich jak tworzenie szkieletów ASP.NET lub szablon projektu aplikacji internetowej ASP.NET. Używają poprzedniej wersji pakietów środowiska uruchomieniowego ASP.NET (5.0.0.0). W rezultacie szkielet ASP.NET zainstaluje poprzednią wersję (5.0.0.0.0) wymaganych pakietów, jeśli nie są one jeszcze dostępne w projektach. Jednak szkielet ASP.NET w Visual Studio 2013 RTM lub Update 1 nie zastępuje najnowszych pakietów w projektach.

Jeśli używasz ASP.NET tworzenia szkieletów po zaktualizowaniu pakietów do internetowego interfejsu API 2.1 lub ASP.NET MVC 5.1, upewnij się, że wersje internetowego interfejsu API i MVC są spójne.

Nazwy typów

Niektóre typy używane do rozszerzalności routingu atrybutów zostały zmienione z RC na 2.1 RTM.

Stara nazwa typu (2.1 RC)	Nowa nazwa typu (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Filtry wyjątków nie usuwają wyjątków agregacji zgłaszanych w akcjach asynchronicznych

Wcześniej, jeśli akcja asynchronicznie rzuciła agregacjęException, filtr wyjątku spowoduje usunięcie wyjątku, a wyjątek OnException otrzyma wyjątek podstawowy. W wersji 2.1 filtr wyjątku nie odpakowuje go, a onException pobiera oryginalny element AggregateException.

Poprawki błędów

Ta wersja zawiera również kilka poprawek błędów.

Pakiet 5.1.2 zawiera aktualizacje funkcji IntelliSense, ale nie ma poprawek błędów.