DomainContext y operaciones

En este tema se describe cómo un cliente de una aplicación de WCF RIA Services utiliza el contexto de dominio para comunicar con el servicio de dominio en el nivel intermedio de la aplicación. No se interactúa directamente con los servicios de dominio desde el proyecto de cliente. En su lugar, se genera una clase de contexto de dominio en el proyecto de cliente para cada servicio de dominio en el proyecto de servidor. Se llama a los métodos en la clase de contexto de dominio que corresponden al método de servicio de dominio que se desea utilizar. La clase de contexto de dominio generada deriva de la clase DomainContext. De forma predeterminada, el contexto de dominio se denomina con un sufijo de Context en lugar del sufijo de Service que se utiliza para asignar nombre al servicio de dominio. Por ejemplo, un servicio de dominio denominado HRService tiene un contexto de dominio correspondiente denominado HRContext. Para obtener información sobre cómo definir los métodos de servicio de dominio, vea Servicios de dominio.

El contexto de dominio generado contiene tres métodos de constructor:

1. Un constructor predeterminado que incrusta el URI para comunicarse con el servicio de dominio mediante HTTP.

2. Un constructor que permite especificar un URI alternativo.

3. Un constructor que permite proporcionar una implementación de DomainClient personalizada. Este constructor se utiliza normalmente para las pruebas unitarias o para redirigir a una capa de transporte personalizada.

La clase DomainContext admite operaciones de dominio de consulta, envío e invocación. Para cada tipo de operación, hay una clase correspondiente que representa la operación asincrónica en curso. Estas clases son: LoadOperation, SubmitOperation y InvokeOperation.

Se genera un objeto EntitySet en el contexto de dominio con propiedades que indican qué operaciones (inserción, actualización o eliminación) se permiten desde el cliente.

Consultas

El método de consulta en el contexto de dominio tiene normalmente el mismo nombre que el método de consulta de servicio de dominio más un sufijo de Query. Por ejemplo, un método GetCustomersQuery en el contexto de dominio se genera a partir de un método GetCustomers en el servicio de dominio. El método de consulta de contexto de dominio devuelve un objeto EntityQuery que puede utilizarse para aplicar operaciones adicionales.

Todas las consultas de un contexto de dominio se ejecutan de forma asincrónica. Para ejecutar la consulta, se pasa el objeto EntityQuery como parámetro en el método Load.

Para obtener más información, vea Tutorial: recuperar y mostrar datos de un servicio de dominio.

El código siguiente muestra cómo recuperar clientes desde el servicio de dominio. Filtra los clientes con números de teléfono que comienzan por 583 y los ordena alfabéticamente por apellido. Los resultados se muestran en un control 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;
    }
}

Modificar datos

Cuando el servicio de dominio incluye métodos para actualizar, insertar y eliminar entidades, dichos métodos no se generan en el contexto de dominio. En su lugar, se debe utilizar el método SubmitChanges en el contexto de dominio y se llama a las operaciones apropiadas en el servicio de dominio. No se realizan cambios en el origen de datos hasta que se llame a SubmitChanges. Se pueden cancelar los cambios pendientes llamando al método RejectChanges.

La clase DomainContext también proporciona las propiedades EntityContainer y HasChanges para permitir la evaluación de los cambios pendientes. El objeto EntityContainer para un contexto de dominio realiza el seguimiento de los cambios pendientes. Los cambios pendientes no incluyen llamadas para invocar operaciones en el servicio de dominio porque las operaciones de invocación se ejecutan inmediatamente cuando se les llama. Cuando se llama a SubmitChanges, todos los cambios pendientes se envían juntos al servicio de dominio.

Se puede agregar una nueva entidad llamando al método Add en el objeto EntitySet o llamando al método AddNew en el objeto IEditableCollectionView. Cuando se agrega una entidad llamando al método AddNew, esa entidad se presenta en la colección antes de que la nueva entidad se guarde en el origen de datos.

Para obtener más información, vea Tutorial: editar datos de un servicio de dominio.

Métodos de actualización con nombres

El contexto de dominio contendrá un método para cada método de actualización con nombres en el servicio de dominio que tenga un modificador de acceso público y no esté marcado con el atributo IgnoreAttribute. El método generado en el contexto de dominio contiene el mismo nombre que el método en el servicio de dominio. En el proyecto de cliente, se llama al método, pero el método no se ejecuta realmente hasta que se llama a SubmitChanges. El elemento EntityContainer realiza el seguimiento de todas las llamadas a los métodos de actualización con nombres como cambios pendientes. Cuando se llama a SubmitChanges, el método se procesa de forma asincrónica.

También se genera el mismo método de actualización con nombres en el proyecto de cliente para la entidad que se pasa como parámetro en el método de actualización con nombres. Por lo tanto, se puede llamar al método de actualización con nombres mediante una instancia del contexto de dominio o una instancia de la entidad. Si se abre el archivo de código generado, se observará que el método generado en el contexto de dominio simplemente llama al método generado en la entidad. En cualquier caso, todavía se debe llamar al método SubmitChanges en el contexto de dominio para ejecutar el método.

En el ejemplo siguiente se muestra cómo llamar a un método de actualización con nombres denominado ResetPassword en la entidad. OnSubmitCompleted es un método de devolución de llamada que se implementa para controlar los resultados de la operación de datos.

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

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

Operaciones de invocación

El contexto de dominio contendrá un método para cada operación de invocación en el servicio de dominio. A diferencia de las operaciones de dominio, las operaciones de invocación se ejecutan inmediatamente. No se llama al método SubmitChanges. Las operaciones de invocación se ejecutan de forma asincrónica. La operación de invocación devuelve un objeto InvokeOperation. Se recupera el valor de la propiedad Value para obtener el valor devuelto de la operación de servicio.

En casi todos los escenarios, se deben usar operaciones de consulta en lugar de operaciones de invocación para la carga de datos. Los métodos de consulta devuelven un solo objeto Entity, un objeto IQueryable<Entity> o un objeto IEnumerable<Entity>. Los métodos de consulta forman parte integral del patrón de datos admitido por DomainService en el nivel intermedio y por DomainContext en el cliente. El marco de RIA Services genera entidades en el proyecto de cliente solo para las entidades devueltas por los métodos de consulta en DomainService.

Las operaciones de invocación proporcionan un mecanismo fuera de banda para devolver datos que no son de entidad y ejecutar operaciones con efectos secundarios. Para obtener más información sobre los efectos secundarios, vea la propiedad HasSideEffects. Las operaciones de invocación no son normalmente adecuadas para los métodos de consulta. Incluso cuando una operación de invocación devuelve una entidad, la entidad se genera para el proyecto de cliente únicamente si la devuelve un método de consulta.

En el ejemplo siguiente se muestra cómo utilizar una operación de invocación denominada GetLocalTemperature. Para este ejemplo, se ha de suponer que el método recupera un valor que no está relacionado con datos de entidad.

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;
  }
}

Control de errores

Cuando se recuperan o modifican datos, se debe decidir cómo controlar los errores que pueden surgir de estas operaciones. Cuando se llama a métodos en el contexto de dominio que recuperan o modifican datos, se deben incluir parámetros que especifiquen los pasos para controlar los errores. Cuando se cargan datos, se puede especificar que se omitan los errores. Cuando se modifican datos, se debe controlar la excepción que se devuelve. Para obtener más información, vea Control de errores en el cliente.