DomainContext e operazioni

In questo argomento viene descritto l'utilizzo da parte del client di un'applicazione WCF RIA Services del contesto del dominio per comunicare con il servizio del dominio nel livello intermedio dell'applicazione. Dall'interno del progetto client, non vi è interazione diretta con i servizi del dominio. Al contrario, una classe del contesto del dominio viene generata nel progetto client per ogni servizio del dominio nel progetto server. Si esegue la chiamata ai metodi nella classe del contesto del dominio, corrispondenti al metodo del servizio del dominio che si desidera utilizzare. La classe del contesto del dominio generata deriva dalla classe DomainContext. Per impostazione predefinita, il contesto del dominio viene denominato con una forma suffissa di Context anziché di Service, che è invece utilizzata per assegnare un nome al servizio del dominio. Ad esempio, un servizio del dominio denominato HRService dispone di un contesto del dominio corrispondente denominato HRContext. Per informazioni sulla definizione di metodi del servizio del dominio, vedere Servizi del dominio.

Il contesto del dominio generato contiene tre metodi del costruttore:

1. Un costruttore predefinito che incorpora l'URI necessario per comunicare con il servizio del dominio su HTTP.

2. Un costruttore che consente di specificare un URI alternativo.

3. Un costruttore che consente di fornire un'implementazione personalizzata di DomainClient. Questo costruttore viene utilizzato in genere per gli unit test o per il reindirizzamento a un livello di trasporto personalizzato.

La classe DomainContext supporta operazioni di dominio query, submit e invoke. Per ogni tipo di operazione è disponibile una classe corrispondente che rappresenta l'operazione asincrona in corso. Le classi sono: LoadOperation, SubmitOperation e InvokeOperation.

Nel contesto del dominio viene generato un oggetto EntitySet con proprietà che indicano quali operazioni (inserimento, aggiornamento o eliminazione) sono consentite dal client.

Query

Il metodo di query nel contesto del dominio presenta in genere lo stesso nome del metodo di query del servizio del dominio, più una forma suffissa di Query. Un metodo GetCustomersQuery nel contesto del dominio viene ad esempio generato da un metodo GetCustomers nel servizio del dominio. Il metodo di query del contesto del dominio restituisce un oggetto EntityQuery che è possibile utilizzare per effettuare operazioni aggiuntive.

Tutte le query da un contesto del dominio vengono eseguite in modo asincrono. Per eseguire la query, viene passato l'oggetto EntityQuery come parametro nel metodo Load.

Per ulteriori informazioni, vedere Procedura dettagliata: recupero e visualizzazione di dati da un servizio del dominio.

Nel codice riportato di seguito viene illustrato come recuperare clienti dal servizio del dominio. I clienti i cui numeri di telefono iniziano con 583 vengono filtrati e quindi disposti in ordine alfabetico in base a LastName. I risultati verranno visualizzati in un oggetto DataGrid.

Partial Public Class MainPage
    Inherits UserControl

    Private _customerContext As New CustomerDomainContext

    Public Sub New()
        InitializeComponent()

        Dim query As EntityQuery(Of Customer)

        query = _
            From c In Me._customerContext.GetCustomersQuery() _
            Where c.Phone.StartsWith("583") _
            Order By c.LastName

        Dim loadOp = Me._customerContext.Load(query)
        CustomerGrid.ItemsSource = loadOp.Entities
    End Sub

End Class

public partial class MainPage : UserControl
{
    private CustomerDomainContext _customerContext = new CustomerDomainContext();

    public MainPage()
    {
        InitializeComponent();
        EntityQuery<Customer> query = 
            from c in _customerContext.GetCustomersQuery()
            where c.Phone.StartsWith("583")
            orderby c.LastName
            select c;
        LoadOperation<Customer> loadOp = this._customerContext.Load(query);
        CustomerGrid.ItemsSource = loadOp.Entities;
    }
}

Modifica dei dati

Quando il servizio del dominio include metodi per l'aggiornamento, l'inserimento e l'eliminazione di entità, tali metodi non vengono generati nel contesto del dominio. Viene invece utilizzato il metodo SubmitChanges nel contesto del dominio stesso e le operazioni appropriate vengono chiamate nel servizio del dominio. Non vengono apportate modifiche all'origine dati fino alla chiamata di SubmitChanges. È possibile annullare le modifiche in sospeso chiamando il metodo RejectChanges.

La classe DomainContext fornisce anche le proprietà HasChanges e EntityContainer per consentire di valutare le modifiche in sospeso. L'oggetto EntityContainer per un contesto del dominio consente di rilevare le modifiche in sospeso. Le modifiche in sospeso non includono chiamate a operazioni invoke nel servizio del dominio poiché tali operazioni vengono eseguite immediatamente quando vengono chiamate. Quando si chiama SubmitChanges, tutte le modifiche in sospeso vengono inviate insieme al servizio del dominio.

È possibile aggiungere una nuova entità chiamando il metodo Add nell'oggetto EntitySet oppure chiamando il metodo AddNew nell'oggetto IEditableCollectionView. Quando si aggiunge un'entità chiamando il metodo AddNew, viene eseguito il rendering di tale entità nella raccolta prima del suo salvataggio nell'origine dati.

Per ulteriori informazioni, vedere Procedura dettagliata: modifica dei dati da un servizio del dominio.

Metodi di aggiornamento denominati

Il contesto del dominio conterrà un metodo per ciascun metodo di aggiornamento denominato nel servizio del dominio che disponga di un modificatore di accesso pubblico e non sia contrassegnato dall'attributo IgnoreAttribute. Il metodo generato nel contesto del dominio contiene lo stesso nome del metodo nel servizio del dominio. Nel progetto client viene chiamato il metodo, ma questo non viene effettivamente eseguito fino a quando non è stato chiamato il metodo SubmitChanges. Il metodo EntityContainer consente di rilevare tutte le chiamate ai metodi di aggiornamento denominati come modifiche in sospeso. Quando si chiama SubmitChanges, il metodo viene elaborato in modo asincrono.

Lo stesso metodo di aggiornamento denominato viene generato anche nel progetto client per l'entità passata come parametro nel metodo di aggiornamento denominato. Pertanto, il metodo di aggiornamento denominato può essere chiamato tramite un'istanza del contesto del dominio o un'istanza dell'entità. Se si apre il file di codice generato, si noterà che il metodo generato nel contesto del dominio chiama semplicemente il metodo generato nell'entità. In ambo i casi, per eseguire il metodo, è comunque ancora necessario chiamare il metodo SubmitChanges nel contesto del dominio.

Nell'esempio seguente viene mostrato come chiamare un metodo di aggiornamento denominato con nome ResetPassword nell'entità. OnSubmitCompleted è un metodo di callback che si implementa per gestire i risultati dell'operazione sui dati.

selectedCustomer.ResetPassword()
customerContext.SubmitChanges(AddressOf OnSubmitCompleted, Nothing)

selectedCustomer.ResetPassword();
customerContext.SubmitChanges(OnSubmitCompleted, null);

Operazioni invoke

Il contesto del dominio conterrà un metodo per ogni operazione invoke nel servizio del dominio. A differenza di quanto accade per le operazioni di dominio, le operazioni invoke vengono eseguite immediatamente. Il metodo SubmitChanges non viene chiamato. Le operazioni invoke vengono eseguite in modo asincrono. L'operazione invoke restituisce un oggetto InvokeOperation. Si recupera il valore della proprietà Value per ottenere il valore restituito dall'operazione del servizio.

In quasi tutti gli scenari è consigliabile utilizzare operazioni di query anziché operazioni invoke per caricare i dati. I metodi di query restituiscono un singolo oggetto Entity, un oggetto IQueryable<Entity> o un oggetto IEnumerable<Entity>. I metodi di query formano parte integrante del modello di dati supportato da DomainService a livello intermedio e da DomainContext nel client. Tramite il framework di Servizi RIA, vengono generate entità nel progetto client solo per le entità restituite dai metodi di query in un oggetto DomainService.

Le operazioni invoke forniscono un meccanismo fuori banda per la restituzione di dati di tipo non entità e per l'esecuzione di operazioni con effetti collaterali. Per ulteriori informazioni sugli effetti collaterali, vedere la proprietà HasSideEffects. Le operazioni invoke non sono in genere adatte per i metodi di query. Anche quando un'operazione invoke restituisce un'entità, l'entità viene generata per il progetto client solo se viene restituita da un metodo di query.

Nell'esempio riportato di seguito viene illustrato come utilizzare un'operazione invoke denominata GetLocalTemperature. In questo esempio si presuppone che il metodo recuperi un valore non correlato a dati di entità di alcun genere.

Dim invokeOp As InvokeOperation(Of Integer)
invokeOp = customerContext.GetLocalTemperature(selectedPostalCode, AddressOf OnInvokeCompleted, Nothing)

Private Sub OnInvokeCompleted(ByVal invOp As InvokeOperation(Of Integer))
  If (invOp.HasError) Then
    MessageBox.Show(String.Format("Method Failed: {0}", invOp.Error.Message))
    invOp.MarkErrorAsHandled()
  Else
    result = invOp.Value
  End If
End Sub

InvokeOperation<int> invokeOp = customerContext.GetLocalTemperature(selectedPostalCode, OnInvokeCompleted, null);

private void OnInvokeCompleted(InvokeOperation<int> invOp)
{
  if (invOp.HasError)
  {
    MessageBox.Show(string.Format("Method Failed: {0}", invOp.Error.Message));
    invOp.MarkErrorAsHandled();
  }
  else
  {
    result = invOp.Value;
  }
}

Gestione degli errori

Quando si recuperano o si modificano dati, è necessario decidere come gestire eventuali errori che potrebbero verificarsi in seguito a tali operazioni. Quando si chiamano metodi nel contesto del dominio che recuperano o modificano dati, si includono parametri che specificano i passaggi per la gestione degli errori. In caso di caricamento di dati, è possibile specificare che gli errori vengano ignorati. Quando si modificano dati, è necessario gestire l'eccezione restituita. Per ulteriori informazioni, vedere Gestione degli errori sul client.