Consulta de datos usando SDK para .NET

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

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:

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

2. 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:

• Paginar resultados mediante FetchXml
• Resultados de la página usando QueryExpression

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:

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

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:

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

Más información sobre alias de columnas:

• Alias ​​de columna FetchXMl
• Alias ​​de columna QueryExpression

Convertir consultas entre FetchXml y QueryExpression

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

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