Condividi tramite

Novità dell'API Web ASP.NET 2.2

  • Articolo

di Microsoft

Questo argomento descrive le novità per API Web ASP.NET 2.2.

Scarica

Le funzionalità di runtime vengono rilasciate come pacchetti NuGet nella raccolta NuGet. Tutti i pacchetti di runtime seguono la specifica del controllo delle versioni semantiche . La versione più recente del pacchetto API Web ASP.NET 2.2 è la seguente: "5.2.0". È possibile installare o aggiornare questi pacchetti tramite NuGet. La versione include anche i pacchetti localizzati corrispondenti in NuGet.

È possibile installare o aggiornare i pacchetti NuGet rilasciati usando la console di Gestione pacchetti NuGet:

Install-Package Microsoft.AspNet.WebApi -Version 5.2.0

Documentazione

Le esercitazioni e altre informazioni su API Web ASP.NET 2.2 sono disponibili nel sito Web ASP.NET (https://www.asp.net/web-api).

Nuove funzionalità in API Web ASP.NET 2.2

OData v4

Questa versione aggiunge il supporto per il protocollo OData v4. Per altre informazioni, vedere la documentazione relativa all'API Web OData v4.

Ecco alcune delle principali funzionalità e modifiche per OData v4:

Miglioramenti del routing degli attributi

Il routing degli attributi fornisce ora un punto di estendibilità denominato IDirectRouteProvider, che consente il controllo completo sulla modalità di scoperta e configurazione delle route degli attributi. Un IDirectRouteProvider è responsabile di fornire un elenco di azioni e controller insieme alle informazioni sulla route associate per specificare esattamente la configurazione di routing desiderata per tali azioni. È possibile specificare un'implementazione IDirectRouteProvider quando si chiama MapAttributes/MapHttpAttributeRoutes.

La personalizzazione di IDirectRouteProvider sarà più semplice estendendo l'implementazione predefinita DefaultDirectRouteProvider. Questa classe fornisce metodi virtuali sostituibili separati per modificare la logica per l'individuazione degli attributi, la creazione di voci di route e l'individuazione del prefisso di route e del prefisso dell'area.

Di seguito sono riportati alcuni esempi sulle operazioni che è possibile eseguire con questo nuovo punto di estendibilità:

  1. Supporto dell'ereditarietà degli attributi di route

    Esempio:

    In questo caso, una richiesta come "/api/values/10" restituirà correttamente "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. Specificare un nome di route predefinito per le route degli attributi seguendo alcune convenzioni desiderate. Per impostazione predefinita, il routing degli attributi non crea automaticamente i nomi per le route degli attributi.

  3. Modificare il modello di route degli attributi in un'unica posizione centrale prima di finire nella tabella di route.

Supporto client API Web per Windows Phone 8.1

È ora possibile usare il pacchetto NuGet client dell'API Web per implementare la logica client dell'API Web quando la destinazione è Windows Phone 8.1 o dall'interno di un'app universale.

Problemi noti e modifiche di rilievo

Questa sezione descrive i problemi noti e le modifiche che causano interruzioni nel API Web ASP.NET 2.2.

OData v4

Generatore di modelli

Problema: Impossibile esporre funzioni di overload come FunctionImport

Se sono presenti 2 funzioni di overload e sono anche FunctionImport, come illustrato di seguito, la richiesta di ~/GetAllConventionCustomers(CustomerName={customerName}) restituisce 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" />

Soluzione alternativa: la soluzione alternativa per questo problema consiste nell'aggiungere entrambi gli overload della funzione come FunctionImports.

OData Routing

I valori letterali stringa che includono la barra con codifica URL (%2F) e la barra rovesciata (%5C) generano un errore 404 quando vengono usati nei percorsi delle risorse OData.

Ad esempio, i valori letterali stringa possono essere usati nei percorsi delle risorse OData come parametri di funzioni o valori chiave di set di entità.

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

/Employees('Name%5C')

Quando i servizi ricevono tali richieste, gli host annullano l'escape delle sequenze di escape prima di passarle al runtime dell'API Web. In questo modo si protegge da attacchi come i seguenti:

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

In questo modo lo stack OData dell'API Web restituisce un errore 404 (Non trovato). Per evitare questo errore, il client deve usare le sequenze di escape doppie per la barra (%252F) e la barra rovesciata (%255C). Questa operazione non si verifica per le stringhe di query, ad esempio /Employees?$filter=Name eq 'Name%2F'

Nota le barre senza escape ('/') e le barre rovesciate ('') non sono legali nei valori letterali stringa del percorso della risorsa OData. Le barre devono essere visualizzate solo come separatori di percorso e barre rovesciata non devono essere visualizzate nel percorso della risorsa OData. Entrambi sono utilizzabili in alcune parti di una stringa di query OData.

Soluzione alternativa: è possibile eseguire l'override del metodo Parse di DefaultODataPathHandler per eseguire l'escape della barra e della barra rovesciata nei valori letterali stringa prima di analizzarli effettivamente. Un esempio di questo approccio è disponibile qui.

OData v3

[Queryable]

L'attributo [Queryable] è deprecato. Le nuove applicazioni OData v3 devono usare System.Web.Http.OData.EnableQueryAttribute.

Il metodo di estensione ODataHttpConfigurationExtensions.EnableQuerySupport aggiunge ora enableQueryAttribute alla raccolta di filtri globale. Se i controller hanno l'attributo [Queryable], la chiamata config.EnableQuerySupport() causerà l'esito negativo dell'attributo [Queryable]

Il modo consigliato per risolvere questo problema consiste nel sostituire tutte le istanze di QueryableAttribute con System.Web.Http.OData.EnableQueryAttribute.

Una soluzione alternativa consiste nell'usare il codice seguente nella configurazione dell'API Web:

config.EnableQuerySupport(new QueryableAttribute());

Routing degli attributi

Problema: l'associazione di modelli di tipo complesso decorata con l'attributo FromUri si comporta in modo diverso quando si usa il routing degli attributi.

Problema: lo scaffolding dell'API MVC/Web in un progetto con pacchetti 5.2.0 genera pacchetti 5.1.2 per quelli che non esistono già nel progetto

L'aggiornamento dei pacchetti NuGet per ASP.NET MVC 5.2 non aggiorna gli strumenti di Visual Studio, ad esempio ASP.NET lo scaffolding o il modello di progetto applicazione Web ASP.NET. Usano la versione precedente dei pacchetti di runtime ASP.NET ,ad esempio 5.1.2 nell'aggiornamento 2. Di conseguenza, il ASP.NET scaffolding installerà la versione precedente (ad esempio 5.1.2 nell'aggiornamento 2) dei pacchetti necessari, se non sono già disponibili nei progetti. Tuttavia, lo scaffolding ASP.NET in Visual Studio 2013 RTM o Update 1 non sovrascrive i pacchetti più recenti nei progetti. Se si usa ASP.NET scaffolding dopo aver aggiornato i pacchetti dei progetti all'API Web 2.2 o ASP.NET MVC 5.2, assicurarsi che le versioni dell'API Web e ASP.NET MVC siano coerenti.

Microsoft.AspNet.OData 5.2.1

Il pacchetto Microsoft.AspNet.OData 5.2.1 contiene aggiornamenti delle dipendenze NuGet, ma non correzioni di bug. Con questo aggiornamento, non esiste più una dipendenza rigida da Microsoft.OData.Core 6.4.0, ma è possibile eseguire l'aggiornamento a qualsiasi versione compresa tra 6.4.0 e 7.0.0.

Microsoft.AspNet.WebAPI 5.2.2

In questa versione è stata apportata una modifica delle dipendenze per Json.Net 6.0.4. Per altre informazioni sulle novità di questa versione di Json.NET, vedere Json.NET 6.0 Release 4 - JSON Merge, Dependency Injection. Questa versione non include altre nuove funzionalità o correzioni di bug nell'API Web. Sono stati successivamente aggiornati tutti gli altri pacchetti dipendenti di cui si è proprietari a seconda di questa nuova versione dell'API Web.

Microsoft.AspNet.WebAPI 5.2.3 Beta

Per informazioni sulla versione, vedere qui. Questa versione contiene solo correzioni di bug.