Usar OrganizationServiceContext

  • Artículo

En Microsoft Dataverse, puede usar distintas clases que implementan la interfaz de IOrganizationService para acceder a los servicios web. Como alternativa, puede usar el OrganizationServiceContext generado por el comando de Power Platform CLI pac modelbuilder build para acceder a la funcionalidad adicional. La clase OrganizationServiceContext permite controlar los cambios, administrar identidades y relaciones, y proporciona acceso al proveedor de LINQ. Esta clase también contiene un método OrganizationServiceContext.SaveChanges() que se usa para enviar los cambios a datos que el contexto está siguiendo. Esta clase se basa en el mismo concepto que el de la clase DataServiceContext en los servicios de datos de Windows Communication Foundation (WCF).

Para generar esta clase, proporcione un valor para el parámetro de --serviceContextName cuando genere enlaces en tiempo de compilación. El comando de Power Platform CLI pac modelbuilder build usa este nombre como nombre de la clase generada. Para obtener más información acerca de cómo utilizar el comando pac modelbuilder build , consulte Generar clases de entidad con enlace en tiempo de compilación con SDK para .NET. Puede usar el contexto de la instancia cuando desarrolle aplicaciones, complementos y actividades de flujo de trabajo.

Cómo usar la clase OrganizationServiceContext

Para crear una instancia de la clase de contexto, debe pasar al constructor de clases un objeto que implemente la interfaz de IOrganizationService. Una opción es pasar una instancia de la clase CrmServiceClient. Para obtener más información sobre la interfaz de IOrganizationService, vea Interfaz de IOrganizationService.

El siguiente ejemplo de código muestra cómo crear una nueva instancia de la clase de contexto. En este ejemplo, a la clase de contexto se le dio el nombre AdventureWorksCycleServiceContext especificando el nombre mediante el parámetro --serviceContextName al ejecutar el comando pac modelbuilder build:

// For early bound types to work correctly, they have to be enabled on the
// client connection. Here, _service is a reference to a ServiceClient or
// CrmServiceClient object. Those types implement IOrganizationService.
_service.EnableProxyTypes();
AdventureWorksCycleServiceContext context = new   
    AdventureWorksCycleServiceContext(_service);

Tras crear el contexto de la instancia, puede iniciar el seguimiento para crear, editar o eliminar filas de tablas (registros de entidad).

El contexto debe seguir cualquier fila de tabla o relación que desee enviar a Dataverse. Por ejemplo, podría recuperar una fila con una consulta LINQ y el contexto realizaría el seguimiento de esa fila o podría usar el método OrganizationServiceContext.Attach(Entity) para hacer que el contexto inicie el seguimiento de la fila. Puede trabajar con datos en una aplicación cliente y crear filas nuevas, crear filas relacionadas, y modificar las filas existentes, pero debe llamar al método de SaveChanges en las filas seguidas para confirmar los cambios en el servidor de Dataverse.

Realizar un seguimiento de los cambios

Para determinar cómo el contexto sigue a una fila de tabla, puede comprobar la propiedad de EntityState en la instancia de entidad derivada Entity. Debe notificar al contexto que siga a una fila de Dataverse llamando a varios métodos o utilizando una consulta de LINQ. El contexto de servicio sigue a todas las filas devueltas por una consulta de LINQ.

Puede agregar objetos al contexto de servicio llamando a uno de los siguientes métodos en OrganizationServiceContext.

método Uso
AddObject(Entity) Agrega una fila de tabla al conjunto de filas que el contexto del servicio está siguiendo. El estado de la fila en el contexto se establece en Created. Si se llama al método de SaveChanges(), este fila se creará o agregará al servidor.
Attach(Entity) Agrega una fila de tabla al conjunto de filas que el contexto del servicio está siguiendo. El estado de la fila en el contexto se establece en Unchanged. Si se llama al método de SaveChanges(), no se enviará esta fila al servidor a menos que su estado cambie.
CreateQuery(String) Agrega los resultados de una consulta al conjunto de filas que el contexto del servicio está siguiendo.

En Dataverse, el contexto del servicio permite crear y actualizar relaciones entre filas de tabla. Las propiedades de navegación generadas por el comando de Power Platform CLI pac modelbuilder build y ubicadas en las clases de enlace en tiempo de compilación permiten acceder y cambiar propiedades y relaciones relacionadas con la fila. El contexto del servicio debe seguir la fila relacionada para que la fila relacionada esté disponible para actualizarse en el servidor.

Use los siguientes métodos en el OrganizationServiceContext para trabajar con filas relacionadas y agregar la fila al contexto del servicio:

Método Uso
AddRelatedObject(Entity, Relationship, Entity) Agrega el destino al contexto. Llama al método de Attach(Entity) en la fila de tabla de destino y luego llama al método de AddLink(Entity, Relationship, Entity) entre la fila de origen y la fila de destino (relacionada).
AttachLink(Entity, Relationship, Entity) Agrega la fila relacionada al contexto para realizar el seguimiento. El estado de la fila en el contexto se establece en Unchanged.
AddLink(Entity, Relationship, Entity) Crea una relación entre las filas de origen y de destino. Agrega el destino al contexto. El estado de la fila de destino en el contexto se establece en Created.
LoadProperty(Entity, String) Carga el conjunto de la entidad relacionada para la relación especificada. Da acceso a las filas relacionadas mediante la propiedad de navegación. Llame al método de AddObject(Entity) en la fila relacionada tras acceder a la fila usando una propiedad de navegación en la fila primaria.
UpdateObject(Entity) Cambia el estado de la fila especificada en el OrganizationServiceContext a editado.
DeleteObject(Entity) Cambia el estado de la fila especificada que se va a eliminar en el OrganizationServiceContext.

Las filas relacionadas para las filas que ha recuperado mediante LINQ serán nulas hasta que se use LoadProperty(Entity, Relationship) para recuperarlas. El siguiente ejemplo de código muestra cómo tener acceso a filas de tarea asociadas a una fila de contacto específico.

Contact pam = context.ContactSet.Where(c => c.FirstName == "Pamela").FirstOrDefault();  
if (pam != null)  
{  
// pam.Contact_Tasks is null until you use LoadProperty  
    context.LoadProperty(pam, "Contact_Tasks");  
    Task firstTask = pam.Contact_Tasks.FirstOrDefault();  
}

Puede usar el método AddLink(Entity, Relationship, Entity) para crear asociaciones. Debe llamar al método SaveChanges() antes de que el servidor se actualice con la información del nuevo vínculo.

El siguiente ejemplo de código muestra cómo crear una asociación entre un contacto y una cuenta.

Relationship relationship = new Relationship("account_primary_contact");  
context.AddLink(contact, relationship, account);  
context.SaveChanges();

Guardar los cambios

El contexto del servicio organiza un gráfico de las filas de tabla que está siguiendo. El orden en que el contexto del servicio procesa cambios en la tabla y los envía al servidor es importante. Las actualizaciones de las filas de tabla primaria se procesan y luego se procesan las filas de tabla relacionadas. Si un valor se establece en la filad e tabla primaria por la fila de tabla relacionada, se usa ese valor al actualizar los datos en el servidor.

Si se produce un error cuando se guarda la información de la entidad, se genera un nuevo tipo de excepción que contiene SaveChangesResult mediante el método OrganizationServiceContext.SaveChanges() independientemente del valor del parámetro SaveChangesOptions que se pase al método.

Usar métodos virtuales cuando cambia el contexto

A veces puede ser necesario realizar acciones en función de los cambios en el OrganizationServiceContext. Para facilitar esto, se proporcionan métodos virtuales para permitirle interceptar o que se le notifique una operación. Para aprovechar estos métodos, tiene que derivar de OrganizationServiceContext o cambiar el contexto generado de servicios. La siguiente tabla enumera los métodos virtuales.

Método Descripción
OnBeginEntityTracking(Entity) Llamado después de que una fila de tabla vínculo se asocie a OrganizationServiceContext.
OnBeginLinkTracking(Entity, Relationship, Entity) Llamado después de que un vínculo se asocie a OrganizationServiceContext.
OnEndEntityTracking(Entity) Llamado después de que una fila de tabla desvinculada de OrganizationServiceContext.
OnEndEntityTracking(Entity) Llamado después de que un vínculo se desasocie de OrganizationServiceContext.
OnExecuting(OrganizationRequest) Llamado inmediatamente antes de que una solicitud se envíe a Dataverse.
OnExecute(OrganizationRequest, OrganizationResponse) Llamado inmediatamente después de que una solicitud se envíe a Dataverse, independientemente de si se produjo una excepción o no.
OnSavingChanges(SaveChangesOptions) Llamado antes de que ocurra una operación tras una llamada a SaveChanges.
OnSaveChanges(SaveChangesResultCollection) Llamado cuando todas las operaciones de una llamada a SaveChanges se han completado, o si hay un error.

Operaciones de datos

Puede modificar, crear y eliminar objetos del contexto de servicio, y aplicaciones Dataverse hace un seguimiento de los cambios realizados en estos objetos. Cuando se llama al método OrganizationServiceContext.SaveChanges() Cuando se llama al método, Dataverse genera y ejecuta comandos que realizan las instrucciones de inserción, actualización o eliminación equivalentes en los datos de Dataverse.

Al trabajar con clases de Entity de enlace de tiempo de compilación, se utiliza el nombre de tabla y el nombre de esquema de la columna para especificar una fila de tabla o un columna con el que trabajar. Los nombres de esquema se definen en EntityMetadata.SchemaName y AttributeMetadata.SchemaName, o puede usar los nombres de clase y de propiedad mostrados en el archivo generado por el código. El siguiente ejemplo muestra cómo asignar un valor al atributo de correo electrónico de una nueva instancia de contacto.

Contact contact = new Contact();
contact.EMailAddress1 = "sonny@contoso.com";

Crear una nueva fila de tabla

Si desea insertar datos de tabla en Dataverse, debe crear una instancia de un tipo de entidad y agregar el objeto a un contexto de servicio. El contexto de servicio debe realizar un seguimiento del objeto para poder guardarlo en Dataverse.

Cuando se crea una fila de tabla nueva, se agrega la entidad objeto al contexto de servicio mediante el método AddObject(Entity).

El siguiente ejemplo muestra la creación y el guardado de un nuevo contacto usando el modelo de datos de la entidad. También demuestra cómo acceder a un atributo personalizado.

OrganizationServiceContext orgContext =new OrganizationServiceContext(svc);  
Contact contact = new Contact()     
 {  
   FirstName = "Charles",  
   LastName = "Brown",  
   Address1_Line1 = "123 Main St.",  
   Address1_City = "Des Moines",  
   Address1_StateOrProvince = "IA",  
   Address1_PostalCode = "21254",  
   new_twittername = "Chuck",  
   Telephone1 = "123-234-5678"  
 };   
orgContext.AddObject(contact);
orgContext.SaveChanges();

Existen varios puntos a tener en cuenta en el código de ejemplo anterior. Primero, después de que se cree una instancia de un nuevo contacto, pasa ese objeto de contacto al método OrganizationServiceContext.AddObject(Entity) de manera que el contexto puede seguir realizando un seguimiento del objeto. El segundo punto es que el nuevo objeto se guarda en el servidor mediante el método OrganizationServiceContext.SaveChanges() .

Después de agregar un objeto al contexto y antes de que se llame al método OrganizationServiceContext.SaveChanges(), el contexto genera un identificador para el nuevo objeto. Una excepción que contiene el valor SaveChangesResults se genera desde el método SaveChanges() si falla alguna actualización en los datos de Dataverse.

Actualizar una fila de tabla

Dataverse hace un seguimiento de los cambios en los objetos asociados al contexto de servicio. Para modificar una fila de tabla existente, primero debe agregar el objeto al contexto. Para agregar un objeto al contexto, primero debe recuperar la fila de tabla de Dataverse y después agregar el objeto al contexto mediante el método Attach(Entity). Una vez el contexto esté realizando el seguimiento del objeto, puede actualizar la fila estableciendo sus columnas (atributos de la entidad).

El siguiente ejemplo muestra cómo actualizar una columna de cuenta con clases de enlaces en tiempo de compilación.

Account.EMailAddress1 = "Contoso-WebMaster@contoso.com";

El siguiente ejemplo muestra cómo eliminar un valor de columna.

Account.EMailAddress1 = null;

Existen dos métodos parciales denominados OnPropertyChanging y OnPropertyChanged para fila de tabla. A estos métodos se les llama en el establecedor de propiedad. Puede ampliar estos métodos mediante clases parciales para insertar lógica de negocios personalizada.

Eliminar una fila de tabla

Para eliminar una fila de tabla, el contexto de servicio debe realizar un seguimiento del objeto. Una vez el objeto esté en el contexto, puede usar el método DeleteObject(Entity) para marcar el objeto en el contexto para su eliminación. Tenga en cuenta que la fila de tabla de Dataverse no se eliminará hasta que se llame al método OrganizationServiceContext.SaveChanges() .

Consultar también

Ejemplos de la consulta LINQ mediante OrganizationServiceContext con Dataverse
Generar clases para programación en tiempo de compilación con SDK para .NET
IOrganizationService
OrganizationServiceContext

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).