Proiezioni di query (WCF Data Services)Query Projections (WCF Data Services)

Proiezione fornisce un meccanismo di Protocollo OData (Open Data)Open Data Protocol (OData) per ridurre la quantità di dati nel feed restituito da una query specificando che solo determinate proprietà di un'entità vengano restituite nella risposta.Projection provides a mechanism in the Protocollo OData (Open Data)Open Data Protocol (OData) to reduce the amount of data in the feed returned by a query by specifying that only certain properties of an entity are returned in the response. Per ulteriori informazioni, vedere OData: opzione Select System Query ($select).For more information, see OData: Select System Query Option ($select).

In questo argomento viene descritto come definire una proiezione di query e quali sono i requisiti per i tipi di entità e non entità. Viene inoltre illustrato come eseguire gli aggiornamenti dei risultati proiettati e creare i tipi proiettati e vengono elencate alcune considerazioni sulla proiezione.This topic describes how to define a query projection, what the requirements are for entity and non-entity types, making updates to projected results, creating projected types, and lists some projection considerations.

Definizione di una proiezione di queryDefining a Query Projection

È possibile aggiungere una clausola di proiezione a una query tramite l'utilizzo di $select opzione in un URI o tramite query di selezionare clausola (selezionare in Visual Basic) in una query LINQ.You can add a projection clause to a query either by using the $select query option in a URI or by using the select clause (Select in Visual Basic) in a LINQ query. I dati di entità restituiti possono essere proiettati in tipi di entità o non entità sul client.Returned entity data can be projected into either entity types or non-entity types on the client. Negli esempi di questo argomento viene illustrato l'uso della clausola select in una query LINQ.Examples in this topic demonstrate how to use the select clause in a LINQ query.

Importante

Quando si salvano gli aggiornamenti apportati ai tipi proiettati, potrebbe verificarsi una perdita di dati nel servizio dati.Data loss might occur in the data service when you save updates that were made to projected types. Per ulteriori informazioni, vedere considerazioni sulla proiezione.For more information, see Projection Considerations.

Requisiti per tipi di entità e non entitàRequirements for Entity and Non-Entity Types

I tipi di entità devono disporre di una o più proprietà Identity che costituiscono la chiave di entità.Entity types must have one or more identity properties that make up the entity key. I tipi di entità vengono definiti nei client usando uno dei modi riportati di seguito.Entity types are defined on clients in one of the following ways:

Per impostazione predefinita, quando si proiettano i risultati delle query in un tipo definito nel client, le proprietà richieste nella proiezione devono esistere nel tipo di client.By default, when you project query results into a type defined at the client, the properties requested in the projection must exist in the client type. Tuttavia, quando si specifica un valore true per la proprietà IgnoreMissingProperties di DataServiceContext, non è necessario che le proprietà specificate nella proiezione siano presenti nel tipo di client.However, when you specify a value of true for the IgnoreMissingProperties property of the DataServiceContext, properties specified in the projection are not required to occur in the client type.

Aggiornamenti dei risultati proiettatiMaking Updates to Projected Results

Quando si proiettano i risultati di una query in tipi di entità nel client, DataServiceContext può rilevare gli oggetti con aggiornamenti da restituire al servizio dati quando viene chiamato il metodo SaveChanges.When you project query results into entity types on the client, the DataServiceContext can track those objects with updates to be sent back to the data service when the SaveChanges method is called. Tuttavia, gli aggiornamenti apportati ai dati proiettati in tipi di non entità nel client non possono essere restituiti al servizio dati,However, updates that are made to data projected into non-entity types on the client cannot be sent back to the data service. perché il servizio dati non può aggiornare l'entità corretta nell'origine dati senza una chiave per identificare l'istanza di entità.This is because without a key to identify the entity instance, the data service cannot update the correct entity in the data source. I tipi di non entità non vengono associati a DataServiceContext.Non-entity types are not attached to the DataServiceContext.

Quando una o più proprietà di un tipo di entità definito nel servizio dati non sono presenti nel tipo di client in cui viene proiettata l'entità, gli inserimenti di nuove entità non conterranno le proprietà mancanti.When one or more properties of an entity type defined in the data service do not occur in the client type into which the entity is projected, inserts of new entities will not contain these missing properties. In questo caso, gli aggiornamenti apportati alle entità esistenti verranno anche non includono le proprietà mancanti.In this case, updates that are made to existing entities will also not include these missing properties. Quando esiste un valore per la proprietà, l'aggiornamento ripristina il valore predefinito della proprietà, secondo quanto definito nell'origine dati.When a value exists for such a property, the update resets it to the default value for the property, as defined in the data source.

Creazione di tipi proiettatiCreating Projected Types

Nell'esempio seguente viene usata una query LINQ anonima che proietta le proprietà correlate all'indirizzo del tipo Customers in un nuovo tipo CustomerAddress, definito nel client ed attribuito come tipo di entità:The following example uses an anonymous LINQ query that projects the address-related properties of the Customers type into a new CustomerAddress type, which is defined on the client and is attributed as an entity type:

// Define an anonymous LINQ query that projects the Customers type into 
// a CustomerAddress type that contains only address properties.
var query = from c in context.Customers
            where c.Country == "Germany"
            select new CustomerAddress { 
                CustomerID = c.CustomerID, 
                Address = c.Address, 
                City = c.City, 
                Region = c.Region,
                PostalCode = c.PostalCode, 
                Country = c.Country};
' Define an anonymous LINQ query that projects the Customers type into 
' a CustomerAddress type that contains only address properties.
Dim query = From c In context.Customers _
                Where c.Country = "Germany" _
                Select New CustomerAddress With { _
                    .CustomerID = c.CustomerID, _
                    .Address = c.Address, _
                    .City = c.City, _
                    .Region = c.Region, _
                    .PostalCode = c.PostalCode, _
                    .Country = c.Country}

In questo esempio, il modello dell'inizializzatore di oggetti viene usato per creare una nuova istanza del tipo CustmerAddress, anziché chiamare un costruttore.In this example, the object initializer pattern is used to create a new instance of the CustmerAddress type instead of calling a constructor. I costruttori non sono supportati in caso di proiezione in tipi di entità, ma possono essere usati durante la proiezione in tipi di non entità e anonimi.Constructors are not supported when projecting into entity types, but they can be used when projecting into non-entity and anonymous types. Poiché CustomerAddress è un tipo di entità, le modifiche possono essere apportate e restituite al servizio dati.Because CustomerAddress is an entity type, changes can be made and sent back to the data service.

Inoltre, i dati del tipo Customer vengono proiettati in un'istanza del tipo di entità CustomerAddress, anziché di un tipo anonimo.Also, the data from the Customer type is projected into an instance of the CustomerAddress entity type instead of an anonymous type. La proiezione in tipi anonimi è supportata, ma i dati sono di sola lettura perché i tipi anonimi vengono considerati come tipi di non entità.Projection into anonymous types is supported, but the data is read-only because anonymous types are treated as non-entity types.

Le impostazioni MergeOption di DataServiceContext vengono usate per la risoluzione di identità durante la proiezione di query.The MergeOption settings of the DataServiceContext are used for identity resolution during query projection. Pertanto, se un'istanza del tipo Customer esiste già in DataServiceContext, un'istanza di CustomerAddress con la stessa identità seguirà le regole di risoluzione di identità specificate da MergeOptionThis means that if an instance of the Customer type already exists in the DataServiceContext, an instance of CustomerAddress with the same identity will follow the identity resolution rules set by the MergeOption

Nella tabella seguente vengono descritti i comportamenti durante la proiezione dei risultati di tipi di entità e non entità:The following table describes the behaviors when projecting results into entity and non-entity types:

AzioneAction Tipo di entitàEntity Type Tipo di non entitàNon-Entity Type
Creazione di una nuova istanza proiettata tramite inizializzatori, come nell'esempio seguente:Creating a new projected instance by using initializers, as in the following example:

var query = from c in context.Customers
            where c.Country == "Germany"
            select new CustomerAddress { 
                CustomerID = c.CustomerID, 
                Address = c.Address, 
                City = c.City, 
                Region = c.Region,
                PostalCode = c.PostalCode, 
                Country = c.Country};
Dim query = From c In context.Customers _
                Where c.Country = "Germany" _
                Select New CustomerAddress With { _
                    .CustomerID = c.CustomerID, _
                    .Address = c.Address, _
                    .City = c.City, _
                    .Region = c.Region, _
                    .PostalCode = c.PostalCode, _
                    .Country = c.Country}
SupportatoSupported SupportatoSupported
Creazione di una nuova istanza proiettata tramite costruttori, come nell'esempio seguente:Creating a new projected instance by using constructors, as in the following example:

var query = from c in context.Customers
            where c.Country == "Germany"
            select new CustomerAddress(
            c.CustomerID, 
            c.Address, 
            c.City, 
            c.Region,
            c.PostalCode, 
            c.Country);
Dim query = From c In context.Customers _
                Where c.Country = "Germany" _
                Select New CustomerAddress( _
                c.CustomerID, _
                c.Address, _
                c.City, _
                c.Region, _
                c.PostalCode, _
                c.Country)
Viene generato un oggetto NotSupportedException.A NotSupportedException is raised. SupportatoSupported
Uso di una proiezione per trasformare un valore di proprietà, come nell'esempio seguente:Using projection to transform a property value, as in the following example:

var query = from c in context.Customers
            where c.Country == "Germany"
            select new CustomerAddress
            {
                CustomerID = c.CustomerID, 
                Address = "Full address:" + c.Address + ", " +
                c.City + ", " + c.Region + " " + c.PostalCode,
                City = c.City,
                Region = c.Region,
                PostalCode = c.PostalCode,
                Country = c.Country
            };
Dim query = From c In context.Customers _
                Where c.Country = "Germany" _
                Select New CustomerAddress With _
                {.CustomerID = c.CustomerID, _
                    .Address = "Full address: " & c.Address & ", " & _
                    c.City & "," & c.Region & " " & c.PostalCode, _
                    .City = c.City, _
                    .Region = c.Region, _
                    .PostalCode = c.PostalCode, _
                    .Country = c.Country}


Questa trasformazione non è supportata per i tipi di entità perché può generare confusione e la potenziale sovrascrittura dei dati nell'origine dati appartenenti a un'altra entità.This transformation is not supported for entity types because it can lead to confusion and potentially overwriting the data in the data source that belongs to another entity.
Viene generato un oggetto NotSupportedException.A NotSupportedException is raised. SupportatoSupported

Considerazioni sulla proiezioneProjection Considerations

Alla definizione di una proiezione di query si applicano le considerazioni aggiuntive seguenti:The following additional considerations apply when defining a query projection.

  • Quando si definiscono feed personalizzati per il formato Atom, è necessario assicurarsi che tutte le proprietà dell'entità che dispongono di definizioni di mapping personalizzate vengano incluse nella proiezione.When you define custom feeds for the Atom format, you must make sure that all entity properties that have custom mappings defined are included in the projection. Se una proprietà di entità mappata non è inclusa nella proiezione potrebbe verificarsi una perdita di dati.When a mapped entity property is not included in the projection, data loss might occur. Per ulteriori informazioni, vedere personalizzazione Feed.For more information, see Feed Customization.

  • Quando vengono apportati inserimenti a un tipo proiettato che non contiene tutte le proprietà dell'entità nel modello di dati del servizio dati, le proprietà non incluse nella proiezione vengono impostate sui valori predefiniti nel client.When inserts are made to a projected type that does not contain all of the properties of the entity in the data model of the data service, the properties not included in the projection at the client are set to their default values.

  • Quando vengono apportati aggiornamenti a un tipo proiettato che non contiene tutte le proprietà dell'entità nel modello di dati del servizio dati, i valori esistenti non inclusi nella proiezione vengono sovrascritti con i valori predefiniti non inizializzati nel client.When updates are made to a projected type that does not contain all of the properties of the entity in the data model of the data service, existing values not included in the projection on the client will be overwritten with uninitialized default values.

  • Quando una proiezione include una proprietà complessa, è necessario che venga restituito l'intero oggetto complesso.When a projection includes a complex property, the entire complex object must be returned.

  • Quando una proiezione include una proprietà di navigazione, gli oggetti correlati vengono caricati in modo implicito senza necessità di chiamare il metodo Expand.When a projection includes a navigation property, the related objects are loaded implicitly without having to call the Expand method. Il metodo Expand non è supportato in una query proiettata.The Expand method is not supported for use in a projected query.

  • Le proiezioni di query eseguite nel client vengono convertite per l'uso dell'opzione query $select nell'URI della richiesta.Query projections queries on the client are translated to use the $select query option in the request URI. Se una query con proiezione viene eseguita su una versione precedente di WCF Data ServicesWCF Data Services che non supporta l'opzione query $select, viene restituito un errore.When a query with projection is executed against a previous version of WCF Data ServicesWCF Data Services that does not support the $select query option, an error is returned. Questa situazione può inoltre verificarsi quando MaxProtocolVersion di DataServiceBehavior per il servizio dati viene impostato su un valore pari a V1.This can also happen when the MaxProtocolVersion of the DataServiceBehavior for the data service is set to a value of V1. Per ulteriori informazioni, vedere controllo delle versioni del servizio dati.For more information, see Data Service Versioning.

Per ulteriori informazioni, vedere come: risultati della Query progetto.For more information, see How to: Project Query Results.

Vedere ancheSee Also

Esecuzione di query sul servizio datiQuerying the Data Service