Controllo delle versioni del servizio dati (WCF Data Services)Data Service Versioning (WCF Data Services)

Il Protocollo OData (Open Data)Open Data Protocol (OData) consente di creare servizi dati in modo che i client possono accedere ai dati come risorse usando URI basati su un modello di dati.The Protocollo OData (Open Data)Open Data Protocol (OData) enables you to create data services so that clients can access data as resources using URIs that are based on a data model. ODataOData supporta inoltre la definizione di operazioni del servizio. also supports the definition of service operations. Dopo la distribuzione iniziale e, potenzialmente, più volte durante il loro ciclo di vita, potrebbe essere necessario cambiare questi servizi dati per molteplici ragioni, ad esempio perché cambiano le esigenze aziendali, i requisiti IT o per risolvere altri problemi.After initial deployment, and potentially several times during their lifetime, these data services may need to be changed for a variety of reasons, such as changing business needs, information technology requirements, or to address other issues. Quando si apportano modifiche a un servizio dati esistente, è necessario valutare se definire una nuova versione del servizio dati e il modo migliore per ridurre l'impatto sulle applicazioni client esistenti.When you make changes to an existing data service, you must consider whether to define a new version of your data service and how best to minimize the impact on existing client applications. In questo argomento vengono fornite informazioni su quando e come creare una nuova versione di un servizio dati.This topic provides guidance on when and how to create a new version of a data service. Viene inoltre descritto il modo in cui in WCF Data ServicesWCF Data Services viene gestito uno scambio tra client e servizi dati che supportano versioni diverse del protocollo ODataOData.It also describes how WCF Data ServicesWCF Data Services handles an exchange between clients and data services that support different versions of the ODataOData protocol.

Controllo delle versioni di un'istanza di WCF Data ServicesVersioning a WCF Data Service

Una volta che un servizio dati viene distribuito e i dati vengono usati, le modifiche apportate al servizio dati potrebbero provocare problemi di compatibilità con le applicazioni client esistenti.Once a data service is deployed and the data is being consumed, changes to the data service have the potential to cause compatibility issues with existing client applications. Tuttavia, perché le modifiche spesso sono richieste dalle esigenze aziendali complessive relative al servizio, è necessario considerare quando e come creare una nuova versione del servizio dati con il minimo impatto sulle applicazioni client.However, because changes are often required by the overall business needs of the service, you must consider when and how to create a new version of your data service with the least impact on client applications.

Modifiche al modello di dati per cui è consigliabile usare una nuova versione del servizio datiData Model Changes that Recommend a New Data Service Version

Quando si valuta se pubblicare una nuova versione di un servizio dati, è importante capire come i tipi diversi di modifiche possano influire sulle applicazioni client.When considering whether to publish a new version of a data service, it is important to understand how the different kinds of changes may affect client applications. Le modifiche a un servizio dati che potrebbero richiedere la creazione di una nuova versione di un servizio dati possono essere divise nelle due categorie seguenti:Changes to a data service that might require you to create a new version of a data service can be divided into the following two categories:

  • Modifiche al contratto del servizio, ossia aggiornamenti alle operazioni del servizio e all'accessibilità di set di entità (feed), modifiche alle versioni e altre modifiche ai comportamenti del servizio.Changes to the service contract—which include updates to service operations, changes to the accessibility of entity sets (feeds), version changes, and other changes to service behaviors.

  • Modifiche al contratto dati, ossia modifiche al modello di dati o ai formati o alle personalizzazioni di feed.Changes to the data contract—which include changes to the data model, feed formats, or feed customizations.

Nella tabella seguente sono contenute informazioni dettagliate sui tipi di modifiche che è necessario valutare per pubblicare una nuova versione del servizio dati:The following table details for which kinds of changes you should consider publishing a new version of the data service:

Tipo di modificaType of Change Nuova versione richiestaRequires a new version Nuova versione non necessariaNew version not needed
Operazioni di servizioService operations -Aggiungi nuovo parametro- Add new parameter
-Modificare il tipo restituito- Change return type
-Operazione di rimozione del servizio- Remove service operation
-Consente di eliminare un parametro esistente- Delete existing parameter
-Operazione di aggiunta del nuovo servizio- Add new service operation
Comportamenti del servizioService behaviors -Disabilita le richieste di conteggio- Disable count requests
-Disabilita supporto della proiezione- Disable projection support
-Incrementare la versione del servizio dati richiesta- Increase the required data service version
-Abilitare le richieste di conteggio- Enable count requests
-Abilitare il supporto di proiezione- Enable projection support
-Diminuire la versione del servizio dati richiesta- Decrease the required data service version
Autorizzazioni del set di entitàEntity set permissions -Consente di limitare le autorizzazioni di set di entità- Restrict entity set permissions
-Modificare il codice di risposta (nuovo valore della prima cifra) 1- Change response code (new first digit value) 1
-Ridurre le autorizzazioni del set di entità- Relax entity set permissions
-Modificare il codice di risposta (stesso valore della prima cifra)- Change response code (same first digit value)
Proprietà delle entitàEntity properties -Rimuovere proprietà esistente o relazione- Remove existing property or relationship
-Aggiungere proprietà che non ammette valori null- Add non-nullable property
-Consente di modificare una proprietà esistente- Change existing property
-Aggiungere proprietà nullable2- Add nullable property2
Set di entitàEntity sets -Rimuovere i set di entità- Remove entity set -Aggiungere un tipo derivato- Add derived type
-Modificare il tipo di base- Change base type
-Aggiungere set di entità- Add entity set
Personalizzazione di feedFeed customization -Modificare il mapping di proprietà di entità- Change entity-property mapping

1 può dipendere da quanto un'applicazione client si basa sul ricevimento di un codice di errore specifico.1 This may depend on how strictly a client application relies on receiving a specific error code.

2 è possibile impostare il IgnoreMissingProperties proprietà true in modo che il client ignori qualsiasi nuova proprietà inviata dal servizio dati che non sono definiti nel client.2 You can set the IgnoreMissingProperties property to true to have the client ignore any new properties sent by the data service that are not defined on the client. Tuttavia, quando vengono eseguiti inserimenti, le proprietà non incluse dal client nella richiesta POST vengono impostate sui valori predefiniti.However, when inserts are made, the properties not included by the client in the POST request are set to their default values. Per gli aggiornamenti, qualsiasi dato esistente in una proprietà sconosciuto al client potrebbe essere sovrascritto da valori predefiniti.For updates, any existing data in a property unknown to the client might be overwritten with default values. In questo caso, è necessario inviare l'aggiornamento come una richiesta MERGE (impostazione predefinita).In this case, you should send the update as a MERGE request, which is the default. Per ulteriori informazioni, vedere gestione del contesto del servizio dati.For more information, see Managing the Data Service Context.

Come controllare le versioni di un servizio datiHow to Version a Data Service

Se necessario, una nuova versione del servizio dati viene definita creando una nuova istanza del servizio con un contratto di servizio o un modello di dati aggiornato.When required, a new data service version is defined by creating a new instance of the service with an updated service contract or data model. Questo nuovo servizio viene quindi esposto tramite un nuovo endpoint dell'URI che lo differenzia dalla versione precedente.This new service is then exposed by using a new URI endpoint, which differentiates it from the previous version. Ad esempio:For example:

  • Versione obsoleta: http://services.odata.org/Northwind/v1/Northwind.svc/Old version: http://services.odata.org/Northwind/v1/Northwind.svc/

  • Nuova versione: http://services.odata.org/Northwind/v2/Northwind.svc/New version: http://services.odata.org/Northwind/v2/Northwind.svc/

Quando si aggiorna un servizio dati, sarà necessario inoltre aggiornare i client in base ai nuovi metadati del servizio dati e usare il nuovo URI radice.When upgrading a data service, clients will need to also be updated based on the new data service metadata and to use the new root URI. Quando possibile, è necessario gestire la versione precedente del servizio dati per supportare i client non ancora aggiornati per usare la nuova versione.When possible, you should maintain the previous version of the data service to support clients that have not yet been upgraded to use the new version. Quando non sono più necessarie, le versioni precedenti di un servizio dati possono essere rimosse.Older versions of a data service can be removed when they are no longer needed. È opportuno valutare la gestione dell'URI dell'endpoint del servizio dati in file di configurazione esterno.You should consider maintaining the data service endpoint URI in an external configuration file.

Versioni del protocollo ODataOData Protocol Versions

Nuove versioni di ODataOData vengono rilasciati, le applicazioni client potrebbero non essere utilizzando la stessa versione del ODataOData protocollo supportato dal servizio dati.As new versions of ODataOData are released, client applications may not be using the same version of the ODataOData protocol that is supported by the data service. È possibile che un'applicazione client meno recente acceda a un servizio dati che supporta una versione più recente di ODataOData.An older client application may access a data service that supports a newer version of ODataOData. Un'applicazione client può inoltre usare una versione più recente di WCF Data ServicesWCF Data Services libreria client, che supporta una versione più recente di ODataOData rispetto a quello del servizio dati che si accede.A client application may also be using a newer version of the WCF Data ServicesWCF Data Services client library, which supports a newer version of ODataOData than does the data service that is being accessed.

WCF Data ServicesWCF Data Services sfrutta il supporto fornito da ODataOData per gestire tali scenari di controllo delle versioni. leverages the support provided by ODataOData to handle such versioning scenarios. È inoltre disponibile il supporto per la generazione e l'utilizzo di metadati del modello di dati per creare le classi del servizio dati client quando il client utilizza una versione diversa di ODataOData rispetto al servizio dati utilizzato.There is also support for generating and using data model metadata to create client data service classes when the client uses a different version of ODataOData than the data service uses. Per ulteriori informazioni, vedere OData: controllo delle versioni protocollo.For more information, see OData: Protocol Versioning.

Negoziazione della versioneVersion Negotiation

Il servizio dati può essere configurato per definire la versione più recente del ODataOData protocollo che verrà utilizzato dal servizio, indipendentemente dalla versione richiesta dal client.The data service can be configured to define the highest version of the ODataOData protocol that will be used by the service, regardless of the version requested by the client. È possibile eseguire questa operazione specificando un DataServiceProtocolVersion valore per il MaxProtocolVersion proprietà del DataServiceBehavior utilizzato dal servizio dati.You can do this by specifying a DataServiceProtocolVersion value for the MaxProtocolVersion property of the DataServiceBehavior used by the data service. Per ulteriori informazioni, vedere configurazione del servizio dati.For more information, see Configuring the Data Service.

Quando un'applicazione usa le librerie client WCF Data ServicesWCF Data Services per accedere a un servizio dati, le intestazioni delle librerie vengono impostate automaticamente sui valori corretti, a seconda della versione di ODataOData e delle caratteristiche usate nell'applicazione.When an application uses the WCF Data ServicesWCF Data Services client libraries to access a data service, the libraries automatically set these headers to the correct values, depending on the version of ODataOData and the features that are used in your application. Per impostazione predefinita, WCF Data ServicesWCF Data Services utilizza la versione minima del protocollo che supporta l'operazione richiesta.By default, WCF Data ServicesWCF Data Services uses the lowest protocol version that supports the requested operation.

Nella tabella seguente sono contenuti i dettagli delle versioni di .NET Framework.NET Framework e SilverlightSilverlight che includono il supporto WCF Data ServicesWCF Data Services per versioni specifiche del protocollo ODataOData.The following table details the versions of .NET Framework.NET Framework and SilverlightSilverlight that include WCF Data ServicesWCF Data Services support for specific versions of the ODataOData protocol.

Versione del protocollo ODataODataODataOData Protocol Version Supporto introdotto in…Support introduced in…
Versione 1Version 1 - .NET Framework versione 3.5.NET Framework version 3.5 Service Pack 1 (SP1)- .NET Framework versione 3.5.NET Framework version 3.5 Service Pack 1 (SP1)
- SilverlightSilverlight versione 3- SilverlightSilverlight version 3
Versione 2Version 2 - .NET Framework versione 4.NET Framework version 4
-L'aggiornamento di .NET Framework versione 3.5.NET Framework version 3.5 SP1.- An update to .NET Framework versione 3.5.NET Framework version 3.5 SP1. È possibile scaricare e installare l'aggiornamento di Microsoft Download Center.You can download and install the update from the Microsoft Download Center.
- SilverlightSilverlight versione 4- SilverlightSilverlight version 4
Versione 3Version 3 -È possibile scaricare e installare una versione preliminare che supporta ODataOData versione 3 dal Microsoft Download Center.- You can download and install a pre-release version that supports ODataOData version 3 from the Microsoft Download Center.

Versioni di metadatiMetadata Versions

Per impostazione predefinita, WCF Data ServicesWCF Data Services usa la versione 1.1 di CSDL per rappresentare un modello di dati.By default, WCF Data ServicesWCF Data Services uses version 1.1 of CSDL to represent a data model. Questo comportamento viene applicato sempre nel caso di modelli di dati basati su un provider di reflection o un provider del servizio dati personalizzato.This is always the case for data models that are based on either a reflection provider or a custom data service provider. Tuttavia, quando il modello di dati è definito tramite Entity FrameworkEntity Framework, viene restituita la stessa versione di CSDL usata da Entity FrameworkEntity Framework.However, when the data model is defined by using the Entity FrameworkEntity Framework, the version of CSDL returned is the same as the version that is used by the Entity FrameworkEntity Framework. La versione del linguaggio CSDL è determinata dallo spazio dei nomi del elemento dello Schema.The version of the CSDL is determined by the namespace of the Schema element. Per altre informazioni, vedere la specifica [MC-CSDL]: formato di File di definizione dello Schema concettuale.For more information, see the specification [MC-CSDL]: Conceptual Schema Definition File Format.

L'elemento DataServices dei metadati restituiti contiene inoltre un attributo DataServiceVersion che corrisponde al valore dell'intestazione DataServiceVersion nel messaggio di risposta.The DataServices element of the returned metadata also contains a DataServiceVersion attribute, which is the same value as the DataServiceVersion header in the response message. Le applicazioni client, ad esempio il Aggiungi riferimento al servizio finestra di dialogo in Visual Studio, usare queste informazioni per generare il servizio dati client classi che funzionano correttamente con la versione di WCF Data ServicesWCF Data Services che funge da host del servizio dati.Client applications, such as the Add Service Reference dialog box in Visual Studio, use this information to generate client data service classes that work correctly with the version of WCF Data ServicesWCF Data Services that host the data service. Per ulteriori informazioni, vedere OData: controllo delle versioni protocollo.For more information, see OData: Protocol Versioning.

Vedere ancheSee Also

Provider di servizi datiData Services Providers
Definizione di WCF Data ServicesDefining WCF Data Services