Operaciones de clase de la entidad con SDK para .NET

Al ejecutar con datos de Microsoft Dataverse mediante el SDK para .NET usará la clase Entity con el estilo de enlace en tiempo e ejecución o con clases de entidad generadas mediante en el estilo de enalce en tiempo de compilación. Las tipos de entidad generadas heredan de la clase Entity, por lo que de entender la clase Entity es importante para cualquiera de los estilos.

Este tema describirá algunas de las propiedades y métodos más utilizados de la clase Entity.

Entity.LogicalName

Cuando crea una instancia una clase de instancia nueva Entity utilizando el estilo de enlace tardío, debe proporcionar un valor de cadena válido para especificar qué tipo de entidad es. LogicalName se define en los metadatos de la entidad (definición de tabla).

Cuando se usa el estilo de enlace en tiempo de compilación, el valor se establece por el constructor de la clase generada. Por ejemplo: var account = new Entity("account");

En su código, si luego desea recuperar el valor de cadena que describe el tipo de entidad, puede usar la propiedad LogicalName. Esto resulta útil para las muchas API que necesitan un nombre lógico de entidad como parámetro.

Identificador de la entidad

Cuando crea una instancia de la clase Entity, ya sea que use el estilo de enlace tardío o de enlace temprano, no tiene un conjunto de identificación único. Si crea una entidad, no debería establecerla, sino permitir que se pueda establecer por el sistema cuando se crea (guarda).

Si está recuperando una entidad, incluirá el valor de atributo de clave principal bien si lo solicita como si no. El nombre de atributo de clave principal es diferente para cada tipo de entidad. Por lo general, el nombre lógico del atributo de clave principal es la entidad logicalname + id. Para una cuenta es accountid y para el contacto es contactid.

Puede obtener o establecer el valor de la clave principal mediante el atributo de clave principal y también puede usar la propiedad Id para obtener acceso al valor sin tener que recordar el nombre del atributo de clave principal.

Acceso anticipado a las columnas de la tabla

Si usa el estilo de enlace en tiempo de compilación con las clases generadas, encontrará las propiedades escritas para cada atributo en la clase. Las propiedades de los atributos usan AttributeMetadata.SchemaName Y se puede acceder a ellos directamente en la instancia de clase Entity.

Por ejemplo:

//Using the early-bound Account entity class
var account = new Account();
// set attribute values
// string primary name
account.Name = "Contoso";
// Boolean (Two option)
account.CreditOnHold = false;
// DateTime
account.LastOnHoldTime = new DateTime(2017, 1, 1);
// Double
account.Address1_Latitude = 47.642311;
account.Address1_Longitude = -122.136841;
// Int
account.NumberOfEmployees = 500;
// Money
account.Revenue = new Money(new decimal(5000000.00));
// Picklist (Option set)
account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer

Acceso tardío a las columnas de la tabla

Los datos que contiene una entidad están en la propiedad Entity.Attributes . Esta propiedad es una AttributeCollection que proporciona un conjunto completo de métodos para agregar a nuevos atributos, comprobar si ya existe un atributo o quitar atributos.

Descubra los nombres de las columnas y los tipos de datos

En el estilo de enlace en tiempo de ejecución, debe conocer AttributeMetadata.LogicalName del atributo y del tipo de datos. LogicalName es la versión en minúsculas de SchemaName. Puede detectar LogicalName y el tipo de los atributos de diversas formas:

• Ver la definición de la columna (atributo) en las herramientas de personalización de la aplicación web
• Para las tablas del sistema, puede revisar la Referencia de tabla / entidad
• Utilice una herramienta para examinar las definiciones de la tabla, como el navegador de metadatos que se describe en Examine los metadatos de su entorno
• Ver la lista de clases derivadas en la página de referencia de AttributeMetadata

Los atributos pueden ser de los siguientes tipos. Esta es una lista parcial.

Tipo	Descripción
EntityReference	Un atributo de búsqueda. Un enlace a otro registro de entidad.
BooleanManagedProperty	Se usa solo para las entidades que pueden ser componentes de solución, como WebResource. Más información: Usar propiedades administradas
Money	Un atributo Currency.
OptionSetValue	Un atributo Option Set. Los atributos State y Status también usan este tipo.
Boolean	Un atributo Option Set.
Byte[]	Un atributo de Image. Cada entidad puede tener una imagen y el atributo se llama entityimage. Una dirección URL para descargar la imagen que se puede encontrar en un atributo de complemento denominado entityimage_url. Más información Atributos de imagen
DateTime	Un atributo de F¡fecha y hora usa normalmente un valor UTC. Más información: Comportamiento y formato del atributo de fecha y hora.
Decimal	Un atributo de número decimal.
Double	Un atributo de número de punto flotante.
Guid	Se usa normalmente como el identificador único para la entidad.
Int32	Un atributo de número entero.
String	Los atributos de varias líneas de texto y una sola línea de texto usan este tipo. Otro tipo menos común que usa cadenas son columnas EntityName, que almacenan un valor de cadena que representa el nombre lógico de una tabla.

Nota

Las columnas de archivo no están disponibles directamente desde la entidad. Debe usar una serie de solicitudes para cargar o descargar datos de columnas de archivos. Más información: Usar datos de la columna del archivo.

Existen tres formas diferentes para interactuar con los atributos de la entidad con el estilo de enlace en tiempo de ejecución.

• Use el indexador en la clase Entity
• Usar el indizador en la colección Attributes
• Usar los métodos proporcionados en Entity

Use el indexador en la clase Entity

En la mayoría de casos si se usa el estilo de enlace en tiempo de ejecución, puede interactuar con la colección mediante el indizador para obtener o establecer el valor de un atributo mediante LogicalName para el atributo. Por ejemplo, para establecer el atributo de nombre de una cuenta:

//Use Entity class with entity logical name
var account = new Entity("account");
// set attribute values
// string primary name
account["name"] = "Contoso";
// Boolean (Two option)
account["creditonhold"] = false;
// DateTime
account["lastonholdtime"] = new DateTime(2017, 1, 1);
// Double
account["address1_latitude"] = 47.642311;
account["address1_longitude"] = -122.136841;
// Int
account["numberofemployees"] = 500;
// Money
account["revenue"] = new Money(new decimal(5000000.00));
// Picklist (Option set)
account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer

Usar el indizador en la colección de atributos

Al igual que en la entidad, también puede obtener acceso a un valor mediante el indizador en la colección de atributos.

string accountName = account.Attributes["name"];

Use los métodos de Entity

También puede usar los métodos Entity para obtener o establecer valores de atributo.

Método	Descripción
GetAttributeValue<T>(String)	Usar esta opción para devolver un valor de atributo escrito
SetAttributeValue(String, Object)	Usar esta opción para establecer un valor de atributo escrito

Por ejemplo:

account.SetAttributeValue("name", "Account Name");
var accountName = account.GetAttributeValue<string>("name");

Entity.FormattedValues

Cualquier valor de atributo de entidad que se puede presentar en la interfaz de usuario y no sea una cadena tendrá un valor de formato de cadena que se puede usar para mostrar el valor de la interfaz de usuario. Por ejemplo:

• Los valores de dinero tendrán un valor de cadena con el formato de la divisa y precisión adecuados.
• Los valores de fecha tendrán el formato establecido en función de cómo está configurado el sistema
• Los valores OptionSet (opciones) mostrarán la etiqueta localizada que representa el valor entero

Nota

Los valores con formato sólo se aplica a las entidades se han que se recuperado. Una vez que establezca el valor, no se calculará un nuevo valor de formato hasta que se guarde la entidad y se vuelva a recuperar. El valor darle con formato se genera en el servidor.

Puede obtener acceso a los valores con formato mediante la colección FormattedValues con un indizador o con una un método GetFormattedAttributeValue(String) de la entidad.

Por ejemplo, las dos alternativas siguientes recuperan el mismo valor de formato:

var formattedRevenueString1 = account.FormattedValues["revenue"];
var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");

Más información: Obtener acceso a valores con formato.

Entity.RelatedEntities

Cuando crea un registro de entidad (fila de tabla), también puede definir un conjunto de registros de entidad relacionados para crear en la misma operación. Más información: Crear filas de tabla relacionadas en una sola operación

Cuando recupera un registro de entidad usando RetrieveRequest puede configurar RelatedEntitiesQuery con una consulta para incluir registros de entidades relacionados en los resultados. Más información: Recuperar con filas relacionadas

Si incluye registros de entidad relacionados en los resultados, también puede actualizar los valores en esos registros relacionados e incluirlos cuando actualice el registro de entidad. Más información: Actualizar filas de tabla relacionadas en una sola operación

Conversión a un EntityReference

Muchas propiedades de mensaje requieren únicamente un método EntityReference. Use el Entity.ToEntityReference() Método para convertir un registro de entidad en una referencia de entidad.

Conversión a una clase de entidad

Si usa el estilo de enlace en tiempo de ejecución, deberá convertir la instancia Entity al tipo de clase de entidad generada que está usando. Esto se puede hacer normalmente con una conversión, pero también puede usar el método Entity.ToEntity<T>() Método.

Account account1 = (Account)retrievedEntity;
Account account2 = retrievedEntity.ToEntity<Account>();

Nota

Este método no se puede utilizar para convertir una instancia de clase Entity generada a otra clase generada o a Entity. Solo se puede usar para convertir una instancia Entity a un de las clases generadas que heredan de ella. Si la instancia Entity no es en realidad una instancia de la clase generada este mensaje producirá un error.

Pasos siguientes

Estos temas explicarán más sobre cómo trabajar con entidades Dataverse (filas de la tabla).

Inicio rápido: Ejemplo de SDK para .NET (C#)
Consultar datos
Crear filas de tabla
Recuperar una fila de tabla
Actualizar y eliminar una fila de tabla
Asociar y desasociar filas de tabla
Generación de clases para programación de enlace en tiempo de compilación

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).