Novinky webového rozhraní API 2.1 technologie ASP.NET

Článek
06/16/2023

Toto téma popisuje, co je nového ve webovém rozhraní API ASP.NET 2.1.

Stáhnout
Dokumentace
Nové funkce webového rozhraní API ASP.NET 2.1
Známé problémy a zásadní změny
Opravy chyb

Stáhnout

Funkce modulu runtime se vydávají jako balíčky NuGet v galerii NuGet. Všechny balíčky modulu runtime se řídí specifikací sémantické správy verzí . Nejnovější balíček ASP.NET Web API 2.1 RTM má následující verzi: 5.1.2. Tyto balíčky můžete nainstalovat nebo aktualizovat prostřednictvím nuGetu. Tato verze obsahuje také odpovídající lokalizované balíčky na NuGetu.

Vydané balíčky NuGet můžete nainstalovat nebo aktualizovat pomocí konzoly Správce balíčků NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Dokumentace

Kurzy a další informace o ASP.NET Web API 2.1 RTM jsou k dispozici na webu ASP.NET (https://www.asp.net/web-api).

Nové funkce webového rozhraní API ASP.NET 2.1

Globální zpracování chyb

Všechny neošetřené výjimky lze nyní protokolovat prostřednictvím jednoho centrálního mechanismu a chování neošetřených výjimek lze přizpůsobit.

Architektura podporuje více protokolovacích rutin výjimek, které všechny vidí neošetřenou výjimku a informace o kontextu, ve kterém k ní došlo, například požadavek zpracovávaný v době.

Například následující kód používá System.Diagnostics.TraceSource k protokolování všech neošetřených výjimek:

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

Můžete také nahradit výchozí obslužnou rutinu výjimky, abyste mohli plně přizpůsobit zprávu odpovědi HTTP, která se odešle, když dojde k neošetřené výjimce.

Poskytli jsme ukázku , která protokoluje všechny neošetřené výjimky prostřednictvím oblíbené architektury ELMAH.

Vylepšení směrování atributů

Směrování atributů teď podporuje omezení, která umožňují správu verzí a výběr trasy na základě hlaviček. Mnoho aspektů tras atributů je nyní přizpůsobitelné prostřednictvím rozhraní IDirectRouteFactory a třídy RouteFactoryAttribute . Předpona trasy je nyní rozšiřitelná prostřednictvím rozhraní IRoutePrefix a třídy RoutePrefixAttribute .

Poskytli jsme ukázku , která používá omezení k dynamickému filtrování kontrolerů podle hlavičky HTTP api-version.

Vylepšení stránky nápovědy

Webové rozhraní API 2.1 obsahuje následující vylepšení stránek nápovědy rozhraní API:

Dokumentace jednotlivých vlastností parametrů nebo návratových typů akcí
Dokumentace poznámek k datovým modelům

Aktualizovali jsme také návrh uživatelského rozhraní stránek nápovědy, aby se přizpůsobil těmto změnám.

Podpora IgnoreRoute

Webové rozhraní API 2.1 podporuje ignorování vzorů adres URL ve směrování webového rozhraní API prostřednictvím sady rozšiřujících metod IgnoreRoute na webu HttpRouteCollection. Tyto metody způsobí, že webové rozhraní API ignoruje všechny adresy URL, které odpovídají zadané šabloně, a v případě potřeby umožní hostiteli použít další zpracování.

Následující příklad ignoruje identifikátory URI, které začínají segmentem "content":

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

BSON Media-Type Formatter

Webové rozhraní API teď podporuje formát přenosu BSON v klientovi i na serveru.

Pokud chcete povolit BSON na straně serveru, přidejte BsonMediaTypeFormatter do kolekce formatters:

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

Tady je postup, jak může klient .NET využívat formát 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() });

Poskytli jsme ukázku , která ukazuje jak na straně klienta, tak na straně serveru.

Další informace najdete v tématu Podpora BSON ve webovém rozhraní API 2.1.

Lepší podpora asynchronních filtrů

Webové rozhraní API teď podporuje snadný způsob vytváření filtrů, které se spouštějí asynchronně. Tato funkce je užitečná, protože filtr potřebuje k provedení asynchronní akce, jako je přístup k databázi. Pokud jste dříve chtěli vytvořit asynchronní filtr, museli jste rozhraní filtru implementovat sami, protože základní třídy filtru zveřejňují pouze synchronní metody. Teď můžete přepsat virtuální On*Async metody základní třídy filtru.

Příklad:

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

Třídy AuthorizationFilterAttribute, ActionFilterAttribute a ExceptionFilterAttribute podporují asynchronní ve webovém rozhraní API 2.1.

Analýza dotazů pro knihovnu formátování klienta

Dříve System.Net.Http.Formatting podporoval parsování a aktualizaci dotazů URI pro kód na straně serveru, ale ekvivalentní přenosná knihovna tuto funkci chyběla. Ve webovém rozhraní API 2.1 teď může klientská aplikace snadno analyzovat a aktualizovat řetězec dotazu.

Následující příklady ukazují, jak analyzovat, upravovat a generovat dotazy URI. (Příklady pro jednoduchost ukazují konzolovou aplikaci.)

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

Známé problémy a zásadní změny

Tato část popisuje známé problémy a zásadní změny ve webovém rozhraní ASP.NET API 2.1 RTM.

Směrování atributů

Nejednoznačnosti ve shodách směrování atributů teď hlásí chybu, místo aby se vybrala první shoda.

Trasy atributů mají zakázáno používat parametr {controller} a parametr {action} u tras umístěných na akcích. Tyto parametry by s velkou pravděpodobností způsobily nejednoznačnost.

Generováním uživatelského rozhraní MVC/webového rozhraní API do projektu s balíčky 5.1 vznikne balíček 5.0 pro balíčky, které v projektu ještě neexistují.

Aktualizace balíčků NuGet pro ASP.NET Web API 2.1 RTM neaktualizuje nástroje sady Visual Studio, jako je ASP.NET generování nebo šablona projektu ASP.NET Web Application. Používají předchozí verzi balíčků modulu runtime ASP.NET (5.0.0.0). V důsledku toho ASP.NET generování nainstaluje předchozí verzi (5.0.0.0) požadovaných balíčků, pokud ještě nejsou k dispozici ve vašich projektech. ASP.NET generování uživatelského rozhraní v Visual Studio 2013 RTM nebo Update 1 však nepřepíše nejnovější balíčky ve vašich projektech.

Pokud používáte ASP.NET generování po aktualizaci balíčků na webové rozhraní API 2.1 nebo ASP.NET MVC 5.1, ujistěte se, že jsou verze webového rozhraní API a MVC konzistentní.

Přejmenování typů

Některé typy používané pro rozšiřitelnost směrování atributů byly přejmenovány z RC na 2.1 RTM.

Starý název typu (2.1 RC)	Nový název typu (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
Atribut RouteProviderAttribute	Atribut RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Filtry výjimek nerozbalují agregované výjimky vyvolané asynchronními akcemi.

Pokud dříve asynchronní akce vyvolala výjimku AggregateException, filtr výjimky by rozbalil výjimku a OnException by získal základní výjimku. Ve verzi 2.1 filtr výjimky nerozbalí a OnException získá původní výjimku AggregateException.

Opravy chyb

Tato verze obsahuje také několik oprav chyb.

Balíček 5.1.2 obsahuje aktualizace Technologie IntelliSense, ale žádné opravy chyb.

Share via