Udostępnij za pośrednictwem

Co nowego we wzorcu ASP.NET Web API 2.2

  • Artykuł

autor: Microsoft

W tym temacie opisano nowości dotyczące interfejsu API sieci Web 2.2 ASP.NET.

Pobierz

Funkcje środowiska uruchomieniowego są wydawane jako pakiety NuGet w galerii NuGet. Wszystkie pakiety środowiska uruchomieniowego są zgodne ze specyfikacją semantycznego przechowywania wersji . Najnowszy pakiet internetowego interfejsu API 2.2 ASP.NET ma następującą wersję: "5.2.0". Te pakiety można instalować lub aktualizować za pomocą narzędzia NuGet. Wydanie zawiera również odpowiednie zlokalizowane pakiety w programie 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.2.0

Dokumentacja

Samouczki i inne informacje na temat ASP.NET internetowego interfejsu API 2.2 są dostępne w witrynie internetowej ASP.NET (https://www.asp.net/web-api).

Nowe funkcje w interfejsie Web API 2.2 ASP.NET

OData 4

W tej wersji dodano obsługę protokołu OData w wersji 4. Aby uzyskać więcej informacji, zobacz dokumentację internetowego interfejsu API OData w wersji 4.

Poniżej przedstawiono niektóre kluczowe funkcje i zmiany dotyczące usługi OData w wersji 4:

Ulepszenia routingu atrybutów

Routing atrybutów udostępnia teraz punkt rozszerzalności o nazwie IDirectRouteProvider, który umożliwia pełną kontrolę nad sposobem odnajdowania i konfigurowania tras atrybutów. Dostawca IDirectRouteProvider jest odpowiedzialny za udostępnienie listy akcji i kontrolerów wraz ze skojarzonymi informacjami o trasie, aby określić dokładnie, jaka konfiguracja routingu jest wymagana dla tych akcji. Implementację IDirectRouteProvider można określić podczas wywoływania atrybutów MapAttributes/MapHttpAttributeRoutes.

Dostosowanie dostawcy IDirectRouteProvider będzie najłatwiejsze przez rozszerzenie domyślnej implementacji DefaultDirectRouteProvider. Ta klasa udostępnia oddzielne metody wirtualne, które można zastąpić, aby zmienić logikę odnajdywania atrybutów, tworzenia wpisów trasy oraz odnajdywania prefiksu trasy i prefiksu obszaru.

Poniżej przedstawiono kilka przykładów dotyczących tego nowego punktu rozszerzalności:

  1. Obsługa dziedziczenia atrybutów trasy

    Przykład:

    W tym przypadku żądanie, takie jak "/api/values/10", pomyślnie zwróci komunikat "Success:10"

    public class BaseController : ApiController
{
    [Route("{id:int}")]
    public string Get(int id)
    {
        return "Success:" + id;
    }
}
[RoutePrefix("api/values")]
public class ValuesController : BaseController
{
}
       
config.MapHttpAttributeRoutes(new CustomDirectRouteProvider());
public class CustomDirectRouteProvider : DefaultDirectRouteProvider
{
    protected override IReadOnlyList<IDirectRouteFactory> 
    GetActionRouteFactories(HttpActionDescriptor actionDescriptor)
    {
        return actionDescriptor.GetCustomAttributes<IDirectRouteFactory>
        (inherit: true);
    }
}

  2. Podaj domyślną nazwę trasy dla tras atrybutów, postępując zgodnie z konwencją, którą chcesz. Domyślnie routing atrybutów nie tworzy automatycznie nazw tras atrybutów.

  3. Zmodyfikuj szablon trasy tras atrybutów w jednym centralnym miejscu, zanim trafią do tabeli tras.

Obsługa klienta internetowego interfejsu API dla Windows Phone 8.1

Teraz możesz użyć pakietu NuGet klienta internetowego interfejsu API, aby zaimplementować logikę klienta internetowego interfejsu API podczas określania wartości docelowej Windows Phone 8.1 lub z poziomu aplikacji uniwersalnej.

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.2.

OData 4

Konstruktor modelu

Problem: Nie można uwidocznić przeciążonych funkcji jako FunctionImport

Jeśli istnieją 2 przeciążone funkcje i są one również FunctionImport, jak pokazano poniżej, żądanie ~/GetAllConventionCustomers(CustomerName={customerName}) powoduje wyjątek System.InvalidOperationException.

<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true" />
<Function Name="GetAllConventionCustomers" 
ReturnType="Collection(WebStack.QA.Test.OData.UnboundOperation.ConventionCustomer)" 
IsComposable="true">
<Parameter Name="CustomerName" Type="Edm.String" FixedLength="false" 
Unicode="false" />
</Function>
...
<FunctionImport Name="GetAllConventionCustomers" 
Function="WebStack.QA.Test.OData.UnboundOperation.GetAllConventionCustomers" 
EntitySet="ConventionCustomers" IncludeInServiceDocument="true" />

Obejście: Obejściem tego problemu jest dodanie obu przeciążeń funkcji jako FunctionImports.

OData Routing

Literały ciągów zawierające zakodowany ukośnik adresu URL (%2F) i ukośnik odwrotny (%5C) powodują błąd 404, gdy są używane w ścieżkach zasobów OData.

Na przykład literały ciągu mogą być używane w ścieżkach zasobów OData jako parametry funkcji lub kluczowych wartości zestawów jednostek.

/Employees/Total.GetCount(Name='Name%2F')

/Employees('Name%5C')

Gdy usługi odbierają takie żądania, hosty nie unikną tych sekwencji ucieczki przed przekazaniem ich do środowiska uruchomieniowego internetowego interfejsu API. Chroni to przed atakami, takimi jak następujące:

http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:

Powoduje to zwrócenie przez stos OData internetowego interfejsu API błędu 404 (nie znaleziono). Aby zapobiec temu błędowi, klient powinien używać podwójnych sekwencji ucieczki ukośnika (%252F) i ukośnika odwrotnego (%255C). Nie dzieje się tak w przypadku ciągów zapytań, takich jak /Employees?$filter=Name eq 'Name%2F'

Zwróć uwagę, że ukośniki nieunikowane ('/') i ukośniki odwrotne ("") nie są legalne w literałach ciągu ścieżki zasobu OData. Ukośniki powinny być wyświetlane tylko jako separatory ścieżek i ukośniki odwrotne nie powinny być wyświetlane w ścieżce zasobu OData. (Oba te elementy mogą być używane w niektórych częściach ciągu zapytania OData).

Obejście: Możesz zastąpić metodę Parse klasy DefaultODataPathHandler, aby uniknąć ukośnika i ukośnika odwrotnego w literałach ciągu, zanim faktycznie je przeanalizujemy. Przykład tego podejścia można znaleźć tutaj.

OData 3

[Możliwe do wykonywania zapytań]

Atrybut [Queryable] jest przestarzały. Nowe aplikacje OData w wersji 3 powinny używać atrybutu System.Web.Http.OData.EnableQueryAttribute.

Metoda rozszerzenia ODataHttpConfigurationExtensions.EnableQuerySupport dodaje teraz atrybut EnableQueryAttribute do kolekcji filtrów globalnych. Jeśli jakiekolwiek kontrolery mają atrybut [Queryable], wywołanie config.EnableQuerySupport() spowoduje niepowodzenie atrybutu [Queryable]

Zalecanym sposobem rozwiązania tego problemu jest zastąpienie wszystkich wystąpień atrybutu QueryableAttribute atrybutem System.Web.Http.OData.EnableQueryAttribute.

Alternatywnym obejściem jest użycie następującego kodu w konfiguracji internetowego interfejsu API:

config.EnableQuerySupport(new QueryableAttribute());

Routing atrybutów

Problem: Powiązanie modelu typu złożonego, który jest ozdobiony atrybutem FromUri zachowuje się inaczej w przypadku korzystania z routingu atrybutów.

Problem: Tworzenie szkieletu wzorca MVC/internetowego interfejsu API w projekcie z pakietami w wersji 5.2.0 powoduje utworzenie pakietów 5.1.2 dla pakietów, które jeszcze nie istnieją w projekcie

Aktualizowanie pakietów NuGet dla ASP.NET MVC 5.2 nie powoduje zaktualizowania narzędzi programu Visual Studio, takich jak tworzenie szkieletu ASP.NET lub szablon projektu aplikacji internetowej ASP.NET. Używają poprzedniej wersji pakietów środowiska uruchomieniowego ASP.NET (np. 5.1.2 w aktualizacji Update 2). W związku z tym szkielet ASP.NET zainstaluje poprzednią wersję (np. 5.1.2 w aktualizacji Update 2) wymaganych pakietów, jeśli nie są 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 szkieletu ASP.NET po zaktualizowaniu pakietów projektów do internetowego interfejsu API 2.2 lub ASP.NET MVC 5.2, upewnij się, że wersje internetowego interfejsu API i ASP.NET MVC są spójne.

Microsoft.AspNet.OData 5.2.1

Pakiet Microsoft.AspNet.OData 5.2.1 zawiera aktualizacje zależności NuGet, ale nie zawiera poprawek błędów. Dzięki tej aktualizacji nie istnieje już ścisła zależność od microsoft.OData.Core 6.4.0, ale można ją uaktualnić do dowolnej wersji z zakresu od 6.4.0 do 7.0.0.

Microsoft.AspNet.WebAPI 5.2.2

W tej wersji wprowadziliśmy zmianę zależności dla .Json.Net 6.0.4 Aby uzyskać więcej informacji na temat nowości w tej wersji programu Json.NET, zobacz Json.NET 6.0 Release 4 — JSON Merge, Dependency Injection (Wstrzykiwanie zależności w formacie JSON). Ta wersja nie ma żadnych innych nowych funkcji ani poprawek błędów w internetowym interfejsie API. Następnie zaktualizowaliśmy wszystkie inne pakiety zależne, które są nam właścicielami, aby zależeć od tej nowej wersji internetowego interfejsu API.

Microsoft.AspNet.WebAPI 5.2.3 Beta

Informacje o wersji można znaleźć tutaj. Ta wersja zawiera tylko poprawki błędów.