Compartir por

Consultar datos usando QueryExpression

  • Artigo

La clase QueryExpression, junto con otras clases en el espacio de nombres Microsoft.Xrm.Sdk.Query, proporciona un objeto modelo para componer consultas complejas para recuperar registros de Dataverse usando el método IOrganizationService.RetrieveMultiple. Comparar opciones al consultar datos usando el SDK para .NET

Componer una consulta

Utilice QueryExpression para redactar consultas dinámicas que pueda modificar sin la manipulación de cadenas/xml requerida usando FetchXml.

Todas las consultas se basan en una sola tabla. Utilice la clase QueryExpression para seleccionar la tabla de la que la consulta recupera datos.

Estilo de inicialización de objetos

El siguiente ejemplo representa una consulta QueryExpression simple que devuelve la columna Nombre de las primeras cinco filas de la tabla Cuenta usando el inicializador de objeto para que la consulta se defina en una sola asignación.

public static EntityCollection SimpleExample(IOrganizationService service) {

   QueryExpression query = new("account")
   {
         ColumnSet = new ColumnSet("name"),
         TopCount = 5
   };

   return service.RetrieveMultiple(query);
}

Cuando se inicializa la instancia de consulta, puede:

Estilo de asignación de propiedad

Puede redactar la misma consulta sin el constructor QueryExpression(String) o el estilo de inicialización del objeto y simplemente establecer las propiedades en la instancia instanciada como se muestra en el siguiente ejemplo:

public static EntityCollection SimpleExample(IOrganizationService service)
{

   QueryExpression query = new();
   query.EntityName = "account";
   query.ColumnSet.AddColumn("name");
   query.TopCount = 5;

   return service.RetrieveMultiple(query);
}

Este ejemplo muestra cómo puede:

Los ejemplos de esta documentación utilizarán una combinación de estilos de inicialización de objetos y asignación de propiedades. A medida que las consultas se vuelven más complejas, el estilo de inicialización de objetos puede volverse difícil de manejar. Siempre puede definir las propiedades de la consulta por separado y agregarlas a la consulta estableciendo las propiedades o utilizando los métodos disponibles.

Liminar el número de filas

Para limitar el número de filas devueltas utilice la propiedad QueryExpression.TopCount. Sin configurar la propiedad TopCount , Dataverse devuelve hasta 5000 filas.

Alternativamente, especifique una cantidad de registros para devolver usando la paginación. No utilice la propiedad TopCount cuando solicite páginas de datos. Aprenda a solicitar resultados paginados

No puede usar la propiedad TopCount cuando solicita un recuento de filas usando la propiedad PagingInfo.ReturnTotalRecordCount. Aprender a contar filas

Devolver resultados distintos

Utilice la propiedad QueryExpression.Distinct para solicitar que la consulta excluya cualquier valor duplicado en los resultados.

Si usa la propiedad Distinct, debe agregar al menos una OrderExpression a la propiedad QueryExpression.Orders para tener una paginación consistente.

Cuando usa la propiedad Distinct, los resultados devueltos no incluyen valores de clave principal para cada registro porque representan una agregación de todos los valores distintos.

Recuperar datos

Como se explica en Consultar datos utilizando el SDK para .NET, QueryExpression es uno de los tres tipos derivados de la Clase QueryBase, para que pueda pasarlo al método IOrganizationService.RetrieveMultiple para conseguir un EntityCollection que contiene los resultados.

EntityCollection results = service.RetrieveMultiple(query);

Sugerencia

Intenta usar el código de muestra de QueryExpression para utilizar este método.

También puede utilizar la clase RetrieveMultipleRequest, establecer la consulta en RetrieveMultipleRequest.Query property para enviar la solicitud usando el método IOrganizationService.Execute.

RetrieveMultipleRequest request = new()
{
      Query = query
};
var response = (RetrieveMultipleResponse)service.Execute(request);

EntityCollection results = response.EntityCollection;

Utilice la clase RetrieveMultipleRequest cuando desee:

Refinar la consulta

Después de seleccionar la tabla con la que comenzar la consulta, refine la consulta para obtener los datos que necesita. Los siguientes artículos explican cómo completar su consulta.

Artículo Task
Seleccionar columnas Especifique qué columnas de datos se deben devolver.
Unir tablas Especificar el número de tablas relacionada para devolver en los resultados.
Ordenar filas Especifique el orden de clasificación de las filas que se deben devolver.
Filtrar filas Especifique qué filas de datos se deben devolver.
Resultados de página Especifique cuántas filas de datos se devolverán con cada solicitud.
Agregar datos Cómo agrupar y agregar los datos devueltos.
Recuento del número de filas Cómo obtener un recuento del número de filas devueltas.
Optimizaciones del rendimiento Cómo optimizar el rendimiento

Limitaciones

Hay algunas cosas que puede hacer usando FetchXml que QueryExpression no son compatibles.

Importante

Si usa el mensaje FetchXmlToQueryExpression con la clase SDK FetchXmlToQueryExpressionRequest o la API web función FetchXmlToQueryExpression, cualquier capacidad no admitida por QueryExpression no se aplica y no habrá ningún error.

Herramientas de la Comunidad

XrmToolBox FetchXMLBuilder es una herramienta gratuita para redactar y probar solicitudes FetchXml, pero también genera código para consultas de QueryExpression usando la misma experiencia de diseñador.

Nota

Las herramientas creadas por la comunidad no reciben soporte de Microsoft. Si tiene preguntas o problemas con las herramientas de la comunidad, comuníquese con el creador de la herramienta.

Utilice QueryExpression como parámetro de mensaje

También utiliza QueryExpression como parámetro para operaciones de Dataverse como los siguientes mensajes:

Nombre de mensaje SDK para la clase de solicitud .NET Operación de API web
BackgroundSendEmail BackgroundSendEmailRequest Acción BackgroundSendEmail
BulkDetectDuplicates BulkDetectDuplicatesRequest Acción BulkDetectDuplicates
BulkDelete BulkDeleteRequest Acción BulkDelete
FullTextSearchKnowledgeArticle FullTextSearchKnowledgeArticleRequest Acción FullTextSearchKnowledgeArticle
QueryExpressionToFetchXml QueryExpressionToFetchXmlRequest Acción QueryExpressionToFetchXml
SendBulkMail SendBulkMailRequest Acción SendBulkMail
SyncBulkOperation SyncBulkOperationRequest Acción SyncBulkOperation
Rollup RollupRequest Función Rollup

Nota

Operaciones de API web distintas de BulkDelete, SyncBulkOperation y acción QueryExpressionToFetchXml puede usar FetchXml a través del tipo complejo FetchExpression. Mientras que la API web contiene las estructuras para redactar consultas utilizando QueryExpression, como tipos complejos QueryExpression, ColumnSet y FilterExpression, actualmente no hay forma de usarlos para recuperar datos con QueryExpression usando la API web como puede con FetchXml. Esto significa que no es posible probar los resultados de la consulta que enviaría como parámetro mediante API web.

Pasos siguientes

Aprender a seleccionar columnas.

Seleccionar columnas

Pruebe algunas consultas.

Código de ejemplo de QueryExpression