Co nowego w interfejsie WEB API 2.1 ASP.NET

autor: Microsoft

W tym temacie opisano nowości w ASP.NET Web API 2.1.

• Download

• dokumentacja

• Nowe funkcje w interfejsie Web API 2.1 ASP.NET

  • Globalna obsługa błędów
  • Ulepszenia routingu atrybutów
  • Ulepszenia strony pomocy
  • Obsługa IgnoreRoute
  • Formater Media-Type BSON
  • Lepsza obsługa filtrów asynchronicznych
  • Analizowanie zapytań dla biblioteki formatowania klienta

• Znane problemy i zmiany krytyczne

• Poprawki błędów

Pobierz

Funkcje środowiska uruchomieniowego są wydawane jako pakiety NuGet w galerii NuGet. Wszystkie pakiety środowiska uruchomieniowego są zgodne ze specyfikacją wersjonowania semantycznego. Najnowszy pakiet ASP.NET Web API 2.1 RTM 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 na platformie 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 Web API 2.1 ASP.NET

Globalna obsługa błędów

Wszystkie nieobsługiwane wyjątki można teraz rejestrować za pomocą jednego centralnego mechanizmu, a zachowanie nieobsługiwanych wyjątków 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 żądanie przetwarzane w tym czasie.

Na przykład poniższy kod używa 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żna 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 struktury ELMAH.

Ulepszenia atrybutowego routingu

Routing atrybutów obsługuje teraz ograniczenia, umożliwiając wersjonowanie oraz wybór tras opartych na nagłówkach. 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 na podstawie nagłówka HTTP "api-version".

Ulepszenia strony pomocy

Interfejs API sieci Web 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 internetowego interfejsu API za pośrednictwem zestawu metod rozszerzeń IgnoreRoute w usłudze HttpRouteCollection. Te metody powodują, że internetowy interfejs API ignoruje wszelkie adresy URL zgodne z określonym szablonem i umożliwiają hostowi zastosowanie dodatkowego przetwarzania, jeśli jest to konieczne.

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 element 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, który pokazuje zarówno stronę 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 musi wykonać akcję asynchroniową, taką jak dostęp do bazy danych. Wcześniej w celu utworzenia filtru asynchronicznego trzeba było samodzielnie zaimplementować interfejs filtru, ponieważ klasy bazowe filtru uwidoczniły tylko metody synchroniczne. Teraz możesz zastąpić metody wirtualne On*Async klasy bazowej filtru.

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ą asynchroniczność w interfejsie Web API 2.1.

Analizowanie zapytań dla biblioteki formatowania klienta

Wcześniej funkcja System.Net.Http.Formatting obsługiwała analizowanie i aktualizowanie zapytań o identyfikator URI dla kodu po stronie serwera, ale w równoważnej bibliotece przenośnej brakuje tej funkcji. 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. (W przykładach pokazano 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 niekompatybilne w ASP.NET Web API 2.1 RTM.

Routing z użyciem atrybutów

Niejednoznaczności w dopasowywaniu za pomocą atrybutów teraz zgłaszają błąd zamiast wybierania pierwszego dopasowania.

Trasy atrybutów nie mogą używać parametru {controller}, ani parametru {action} na trasach przypisanych do akcji. Te parametry bardzo prawdopodobnie spowodowałyby niejednoznaczności.

Skafoldowanie MVC/Web API w projekcie z pakietami 5.1 skutkuje użyciem pakietów w wersji 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 szkieletowanie ASP.NET w programie Visual Studio 2013 RTM lub Update 1 nie zastępuje oryginalnych pakietów w tych projektach.

Jeśli używasz szkieletu ASP.NET 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.

Zmiany nazw typów

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

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

Wcześniej, jeśli akcja asynchroniczna zgłaszała wyjątek AggregateException, filtr wyjątku odpakuje ten wyjątek, a OnException otrzyma podstawowy wyjątek. W wersji 2.1 filtr wyjątków nie rozwija go, a OnException otrzymuje oryginalny wyjątek 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 zawiera poprawek błędów.