Consulta de datos usando SDK para .NET

Artigo
07/22/2024

El SDK para .NET proporciona varios métodos para consultar datos. Cada uno ofrece diferentes ventajas.

método	Ventajas
Clase FetchExpression	Utilice el lenguaje de consulta FetchXML de su propiedad para crear consultas complejas que pueden devolver conjuntos de datos paginados o datos agrupados y agregados. Puede crear uniones para incluir datos de registros relacionados. FetchXml proporciona capacidades que otras opciones no ofrecen. Aprender a consultar datos mediante FetchXml
Clase QueryExpression	Utilice un modelo de objeto descrito en detalla para crear consultas complejas que pueden devolver conjuntos de datos paginados o datos agrupados y agregados. Puede crear uniones para incluir datos de registros relacionados. Admite la mayoría de las características en FetchXML. Aprenda a consultar datos usando QueryExpression
Clase QueryByAttribute	Un modelo de objetos más simple para consultas comunes que devuelve filas que coinciden con todos los criterios de su consulta. Admite paginación, pero no grupos ni conjuntos de datos agregados. Solo puede devolver datos de una sola tabla. Aprenda a consultar datos utilizando la clase QueryByAttribute
LINQ	Use OrganizationServiceContext.QueryProvider para redactar consultas utilizando la popular sintaxis LINQ. Todas las consultas LINQ se convierten en QueryExpression de forma que las funcionalidades se limitan a las disponibles para `QueryExpression`. Este artículo se centra en las clases de SDK para recuperar datos. Aprenda a usar la consulta de datos con LINQ (consulta integrada en el lenguaje .NET)

Cómo enviar solicitudes

FetchExpression, QueryExpression y QueryByAttribute se obtienen de la clase abstracta QueryBase. Hay dos formas para obtener los resultados de una consulta definida mediante estos tipos:

Puede pasar una instancia de cualquiera de estas clases como el parámetro query al método IOrganizationService.RetrieveMultiple.
Puede configurar la propiedad RetrieveMultipleRequest.Query de la clase y utilizar el método IOrganizationService.Execute.

Generalmente, la gente usa el método IOrganizationService.RetrieveMultiple, pero puedes usar la clase RetrieveMultipleRequest para usar parámetros opcionales o enviar la solicitud como parte de un lote usando las clases ExecuteMultipleRequest o ExecuteTransactionRequest.

Ambos métodos devuelven un EntityCollection que contiene los resultados de la consulta en la propiedad de colección Entities. EntityCollection tiene otras propiedades para gestionar los resultados de paginación devueltos.

Cuando recupera datos utilizando estas clases, hay algunos conceptos que debe comprender. El resto de este artículo explica conceptos comunes al recuperar datos utilizando el SDK para clases .NET.

Los valores de columna nulos no se devuelven

Cuando una columna de la tabla contiene un valor nulo, o si la columna no se solicitó, la colección Entity.Attributes no incluirá el valor. No una clave para tener acceso ni un valor para devolver. La ausencia del atributo indica que el valor es nulo.

Las columnas que no son válidas para lectura siempre devuelven valores nulos. La definición de estas columnas tiene la propiedad AttributeMetadata.IsValidForRead establecida en false.

Las clases enlazadas inicialmente gestionan valores nulos

Cuando usa el estilo de enlace en tiempo de compilación, las propiedades de las clases generadas que heredan de la clase Entity administran esto y devuelven un valor nulo. Obtenga más información sobre cómo generar clases enlazadas anticipadamente

Cómo mitigar los valores nulos utilizando clases de enlace tardío

Cuando se usa el estilo de enlace tardío, si intenta obtener acceso al valor con un indizador en las colecciones Entity.Attributes o Entity.FormattedValues recibirá un KeyNotFoundException con el mensaje: The given key was not present in the dictionary.

Para evitar este problema al usar el estilo de enlace en tiempo de ejecución, puede usar dos estrategias:

Para una columna que podría ser nula, utilice el método Entity.Contains(System.String) para comprobar si el valor de la columna es nulo antes de intentar acceder a ella con un indexador. Por ejemplo:

Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);
Utilice el método Entity.GetAttributeValue<T>(System.String) para acceder al valor. Por ejemplo:

Money revenue = entity.GetAttributeValue<Money>("revenue");

Nota

Si el tipo indicado con Entity.GetAttributeValue<T>(System.String) es un tipo de valor que no puede ser nulo como Boolean o DateTime, el valor devuelto será el valor predeterminado, como false o 1/1/0001 12:00:00 AM en lugar de nulo.

Cada solicitud puede devolver hasta 5000 registros

Las aplicaciones interactivas normalmente limitarán la cantidad de registros mostrados a un número con el que un humano puede interactuar y luego ofrecerán la opción de navegar por páginas de datos. Por ejemplo, las aplicaciones basadas en modelos dependen de una opción personal que permite a las personas elegir un valor entre 25 y 250. Esta información se almacena en la columna UserSettings.PagingLimit.

Las aplicaciones que recuperan datos de Dataverse sin mostrar datos en una aplicación no necesitan especificar un tamaño de página. El tamaño de página predeterminado y máximo es 5000 filas. Si no establece un tamaño de página, Dataverse devolverá hasta 5000 filas de datos a la vez. Para obtener más filas, debe enviar solicitudes adicionales.

La paginación funciona mejor cuando utiliza los datos de la cookie de paginación que Dataverse devuelve con la propiedad EntityCollection.PagingCookie, pero no es obligatoria y algunas solicitudes no devuelven un valor de cookie de paginación. Más información:

Se devuelven valores formateados para algunas columnas

Para cada Entidad en EntityCollection.Entities, acceda a los valores de datos de la columna de la tabla (atributo) usando la colección Entity.Attributes.

Puede mostrar y editar tipos de datos simples como números y cadenas directamente en aplicaciones. Para ciertos tipos de datos, Dataverse proporciona valores de cadena formateados de solo lectura que puede mostrar en las aplicaciones. El formato de algunos de estos valores de cadena depende de la configuración que puede establecer un Administrador y que cada usuario puede anular.

Un administrador puede personalizar las opciones regionales predeterminadas que se aplican a todos los usuarios nuevos. Esta configuración se almacenan en la tabla Organization.
Cada usuario puede anular esta configuración según sus preferencias personales. Esta configuración se almacenan en la tabla UserSettings.

Utilice la colección Entity.FormattedValues para acceder a valores formateados para estos tipos de columnas:

Tipo	Tipo de datos devueltos	Descripción del valor formateado
Sí/no BooleanAttributeMetadata	Boolean	La etiqueta localizada para las propiedades BooleanOptionSetMetadata.FalseOption o BooleanOptionSetMetadata.TrueOption correspondientes.
Cliente, Búsqueda y Propietario LookupAttributeMetadata	EntityReference	El valor EntityReference.Name , que es el valor de la columna de nombre principal del registro.
Fecha y hora DateTimeAttributeMetadata	Fecha y hora	Depende de las configuraciones de comportamiento y formato de la columna, la configuración de la organización y las opciones personales establecidas por el usuario, como la zona horaria en la que se encuentra.
Nombre de entidad EntityNameAttributeMetadata	Cadena	Cuando el valor no es `none`, el valor formateado es el valor localizado DisplayName para la tabla.
Moneda MoneyAttributeMetadata	Dinero	Depende de la moneda seleccionada para la columna, así como de las preferencias de la organización y del usuario.
Choices MultiSelectPicklistAttributeMetadata	OptionSetValueCollection	Cuando se selecciona una sola opción, la etiqueta localizada para la opción seleccionada. Cuando se seleccionan varias opciones, se muestra una cadena con las etiquetas localizadas para cada opción seleccionada, separadas por `;` . Por ejemplo: `Appetizer; Entree; Dessert`
Opción PicklistAttributeMetadata Estado StateAttributeMetadata Estado Razón StatusAttributeMetadata	OptionSetValue	La etiqueta localizada para la opción seleccionada.

El siguiente ejemplo muestra cómo acceder a los valores de cadena con formato para las siguientes columnas de la cuenta:

Nombre lógico	Tipo
`primarycontactid`	EntityReference
`createdon`	DateTime
`revenue`	Money
`statecode`	OptionSetValue

static void FormattedValuesExample(IOrganizationService service)
{
    List<string> columns = new() {
        "name",
        "primarycontactid",
        "createdon",
        "revenue",
        "statecode"
    };

    QueryExpression query = new("account")
    {
        ColumnSet = new ColumnSet(columns.ToArray()),
        TopCount = 3
    };

    EntityCollection accounts = service.RetrieveMultiple(query);

    accounts.Entities.ToList().ForEach(x =>
    {
        string name = (string)x.Attributes["name"];
        string primarycontactid = x.Contains("primarycontactid") ? 
           x.FormattedValues["primarycontactid"] : 
           string.Empty;
        string createdon = x.FormattedValues["createdon"];
        string revenue = x.Contains("revenue") ? 
           x.FormattedValues["revenue"] : 
           string.Empty;
        string statecode = x.FormattedValues["statecode"];

        Console.WriteLine(@$"
name:{name}
    primary contact: {primarycontactid}
    created on: {createdon}
    revenue: {revenue}
    status: {statecode}"
            );
    });
}

Los resultados con formato aparecerán como sigue:

name:A Datum (sample)
  primary contact: Rene Valdes (sample)
  created on: 2/28/2020 11:04 AM
  revenue: $10,000.000
  status: Active

name:City Power & Light (sample)
  primary contact: Scott Konersmann (sample)
  created on: 2/28/2024 11:04 AM
  revenue: $100,000.000
  status: Active

name:Contoso Pharmaceuticals (sample)
  primary contact: Robert Lyon (sample)
  created on: 2/28/2018 11:04 AM
  revenue: $60,000.000
  status: Active

Las columnas que utilizan un alias devuelven un AliasedValue

Cuando recupera valores agregados, debe especificar un nombre para la columna que contiene el valor agregado. También puede especificar nombres de columna diferentes para consultas "normales", aunque esto es menos común.

Cuando especifica un alias, el valor devuelto se envuelve en un AliasedValue. La clase AliasedValue tiene tres propiedades:

Propiedad	Tipo	Descripción
`EntityLogicalName`	`String`	El nombre lógico de la tabla que tiene la columna de dónde provienen los datos.
`AttributeLogicalName`	`String`	El nombre lógico de la columna de dónde provienen los datos.
`Value`	`Object`	El valor agregado o el valor de la fila de la columna utilizando un alias.

Cuando usa un alias de columna, necesita convertir la propiedad Value para acceder al valor devuelto.

Más información sobre alias de columnas:

Convertir consultas entre FetchXml y QueryExpression

Puede convertir consultas QueryExpression a consultas FetchXml y FetchXml a QueryExpression mediante las clase QueryExpressionToFetchXmlRequest y FetchXmlToQueryExpressionRequest.

Nota

Hay algunas capacidades de FetchXml que QueryExpression no tiene. Al convertir una consulta FetchXml a QueryExpression, estas diferencias se pierden. Obtenga más información sobre las limitaciones de QueryExpression

La tabla SavedQuery almacena vistas del sistema para una tabla (tipo de entidad) y la tabla UserQuery almacena las consultas de los usuarios guardadas. Otras tablas también pueden almacenar una consulta como una cadena FetchXml. Estos métodos permiten convertir una cadena FetchXml a QueryExpression de forma que se puede manipular mediante el modelo de objetos y luego convertirla de nuevo a FetchXml para que se pueda guardar como cadena.

Más información: Ejemplo: convertir consultas entre Fetch y QueryExpression

Límites de las condiciones de consulta

Dataverse tiene un límite de 500 condiciones totales permitidas en una consulta. Cualquier combinación incluida en la consulta se cuenta como parte de este límite. Si una consulta (y sus combinaciones) supera las 500 condiciones, el usuario recibirá el siguiente error cuando se ejecute la consulta: Number of conditions in query exceeded maximum limit..

Si esto ocurre, el usuario debe:

Reducir el número de condiciones en su consulta.
Utilizar la cláusula In, que permite GUID y cadenas de hasta 850 caracteres sin límite de números enteros.

En ninguna de las condiciones de filtro para valores de cadena se distinguen mayúsculas de minúsculas

Al comparar valores de cadena, no se preocupe por las mayúsculas y minúsculas. La siguiente consulta QueryExpression devolverá registros de cuenta con el nombre Contoso, Ltd y CONTOSO, LTD.

QueryExpression query = new("account")
{
   ColumnSet = new ColumnSet("name"),
   Criteria = new FilterExpression(LogicalOperator.And) { 
      Conditions = {
         { 
               new ConditionExpression(
                  attributeName: "name", 
                  conditionOperator: ConditionOperator.Equal, 
                  value: "CONTOSO, LTD") 
         }
      }
   },
   TopCount = 3
};