Consulta de datos usando SDK para .NET
El SDK para .NET proporciona varios métodos para consultar datos. Cada uno ofrece diferentes ventajas.
| Método | Ventajas |
|---|---|
| FetchExpression | Use el leguaje de consultas exclusivo de FetchXML para crear consultas complejas que devuelvan agregados como la suma de un valor para todos los registros devueltos. También se pueden realizar operaciones "agrupar por" con FetchXML. Puede incluir datos de filas de tablas vinculadas (registros de entidad). |
| QueryExpression | Tiene un modelo de objetos con establecimiento inflexible de tipos para generar consultas complejas. Admite todas las características de FetchXML excepto agregados y agrupaciones. Puede incluir datos de filas de tablas vinculadas (registros de entidad). |
| QueryByAttribute | Un modelo de objetos más sencillo que QueryExpression. Use QueryByAttribute para consultas en las que está probando si todos los criterios de valor de la columna de la tabla (atributo) en su consulta coinciden. Solo puede devolver datos de una sola tabla (tipo de entidad). |
| LINQ | Usar OrganizationServiceContext.QueryProvider. para crear consultas mediante la sintaxis popular de LINQ. Todas las consultas LINQ se convierten en QueryExpression de forma que las funcionalidades se limitan a las disponibles para QueryExpression En este tema se centrará en los estilos de las consultas disponibles mediante las clases de ensamblados SDK. Más información: Crear consultas con LINQ (consulta integrada del lenguaje .NET) |
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
querya IOrganizationService.RetrieveMultiple . - Puede establecer la propiedad Query de la clase RetrieveMultipleRequest y usar el método IOrganizationService.Execute .
Nota
El método IOrganizationService.RetrieveMultiple se prefiere por lo general. No hay funcionalidades especiales que requieren el uso de la clase RetrieveMultipleRequest.
Ambos métodos devolverán una EntityCollection que contiene los resultados de la consulta en la colección Entities, así como las propiedades para administrar consultas adicionales para recibir resultados paginados.
Nota
Para garantizar el mejor rendimiento, cada solicitud de consulta puede devolver un máximo de 5000 filas. Para devolver conjuntos de resultados más grandes debe solicitar páginas adicionales.
En ninguna de las condiciones de filtro para valores de cadena se distinguen mayúsculas de minúsculas.
Los valores de columna de la tabla nulos no se devuelven
Cuando una columna de la tabla (atributo de entidad) contiene un valor nulo, o si el atributo no se incluyó en los atributos FetchXml o ColumnSet, Entity.Attributes no incluirá el atributo. No una clave para tener acceso ni un valor para devolver. La ausencia del atributo indica que el valor es NULL. Cuando se usa el estilo de encuadernación temprana, las propiedades de la clase Entity administrarán esto y devolverán un valor nulo.
Cuando se usa el estilo de enlace en tiempo de ejecución, si intenta obtener acceso al valor con un indizador en las colecciones Attributes o FormattedValues recibirá un KeyNotFoundException con el mensaje The given key was not present in the dictionary.
Para evitar esto al usar el estilo de enlace en tiempo de ejecución, puede usar dos estrategias:
Para un atributo que pueda ser NULL, use el método Entity.Contains(String) para comprobar si el atributo es NULL antes de intentar tener acceso al mismo con un indizador. Por ejemplo:
Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);Usar Entity.GetAttributeValue<T>(String). para acceder al valor. Por ejemplo:
Money revenue = entity.GetAttributeValue<Money>();
Nota
Si el tipo indicado con GetAttributeValue<T>(String) es un tipo de valor que no puede ser NULL, como Boolean o DateTime, el valor devuelto será el valor predeterminado, como false o 1/1/0001 12:00:00 AM en lugar de NULL.
Usar FetchXML con FetchExpression
FetchXml es un lenguaje exclusivo de consultas basado en XML que se puede usar con consultas de ensamblado SDK mediante FetchExpression y por la API web mediante la cadena de consulta fetchXml. Más información: Consultar datos mediante FetchXML
El siguiente ejemplo muestra una consulta simple para devolver hasta 50 filas de cuenta coincidentes donde el valor address1_city es igual a Redmond, ordenado por name.
string fetchXml = @"
<fetch top='50' >
<entity name='account' >
<attribute name='name' />
<filter>
<condition
attribute='address1_city'
operator='eq'
value='Redmond' />
</filter>
<order attribute='name' />
</entity>
</fetch>";
var query = new FetchExpression(fetchXml);
EntityCollection results = svc.RetrieveMultiple(query);
results.Entities.ToList().ForEach(x => {
Console.WriteLine(x.Attributes["name"]);
});
Importante
Al recuperar filas de la tabla, solo debe solicitar los valores de columna que necesita configurando los atributos específicos usando elementos attribute en lugar de utilizar el elemento all-attributes para devolver todos los atributos.
Más información:
- Consultar datos mediante FetchXML
- Acerca de las consultas de búsqueda rápida
- Paginar resultados mediante FetchXml
- Agregar datos mediante FetchXML
- Ejemplo: uso de agregación en FetchXML
- Ejemplo: usar FetchXML con una cookie de paginación
Usar QueryExpression
La clase QueryExpression proporciona un conjunto de objetos con establecimiento inflexible de tipos que se optimiza para la manipulación en tiempo de ejecución de consultas.
El siguiente ejemplo muestra una consulta simple para devolver hasta 50 filas de cuenta coincidentes donde el valor address1_city es igual a Redmond, ordenado por name.
var query = new QueryExpression("account")
{
ColumnSet = new ColumnSet("name"),
Criteria = new FilterExpression(LogicalOperator.And),
TopCount = 50
};
query.Criteria.AddCondition("address1_city", ConditionOperator.Equal, "Redmond");
query.AddOrder("name", OrderType.Ascending);
EntityCollection results = svc.RetrieveMultiple(query);
results.Entities.ToList().ForEach(x =>
{
Console.WriteLine(x.Attributes["name"]);
});
Importante
Al recuperar filas, solo debe solicitar los valores de columna que necesita configurando los atributos específicos utilizando el constructor de clases ColumnSet. Aunque el constructor de la clase ColumnSet proporcione una sobrecarga que acepte un parámetro booleano allColumns, no debería utilizar este código de producción.
Más información:
- Crear consultas con QueryExpression
- Conjuntos de resultados grandes de página con QueryExpression
- Usar la clase QueryExpression
- Usar la clase ConditionExpression
- Use la clase ColumnSet
- Usar la clase FilterExpression
- Ejemplo: Recuperación múltiple con la clase de QueryExpression
- Ejemplo: usar QueryExpression con una cookie de paginación
Usar QueryByAttribute
La clase QueryByAttribute proporciona un conjunto de objetos fuertemente tipados que está optimizado para consultas simples y comunes de filas de tablas. A diferencia de FetchXML y QueryExpression, QueryByAttribute solo puede devolver datos de una sola tabla. No permite recuperar datos de filas de tablas relacionadas o criterios de consulta complejos.
El siguiente ejemplo muestra una consulta simple para devolver hasta 50 filas de cuenta coincidentes donde el valor address1_city es igual a Redmond, ordenado por name.
var query = new QueryByAttribute("account")
{
TopCount = 50,
ColumnSet = new ColumnSet("name")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);
EntityCollection results = svc.RetrieveMultiple(query);
results.Entities.ToList().ForEach(x =>
{
Console.WriteLine(x.Attributes["name"]);
});
Más información:
Acceder a valores con formato
Independientemente del método que utilice para consultar las tablas, los datos se devolverán como EntityCollection.Entities. Puede acceder a los valores de datos de la columna de la tabla (atributo) utilizando Entity.Attributes . Pero estos valores pueden ser de un tipo distinto al de cadena que necesitará manipular para obtener valores de cadena que puede mostrar en la aplicación.
Puede obtener acceso a los valores de cadena que usa la configuración de los entornos para dar formato mediante los valores en la colección Entity.FormattedValues .
El siguiente ejemplo muestra cómo acceder a los valores de cadena con formato para los siguientes atributos de la cuenta:
| Nombre lógico del atributo | Tipo |
|---|---|
primarycontactid |
EntityReference |
createdon |
DateTime |
revenue |
Money |
statecode |
OptionSetValue |
var query = new QueryByAttribute("account")
{
TopCount = 50,
ColumnSet = new ColumnSet("name", "primarycontactid", "createdon", "revenue", "statecode")
};
query.AddAttributeValue("address1_city", "Redmond");
query.AddOrder("name", OrderType.Ascending);
EntityCollection results = svc.RetrieveMultiple(query);
results.Entities.ToList().ForEach(x =>
{
Console.WriteLine(@"
name:{0}
primary contact: {1}
created on: {2}
revenue: {3}
status: {4}",
x.Attributes["name"],
(x.Contains("primarycontactid")? x.FormattedValues["primarycontactid"]:string.Empty),
x.FormattedValues["createdon"],
(x.Contains("revenue") ? x.FormattedValues["revenue"] : string.Empty),
x.FormattedValues["statecode"]
);
});
Nota
Las columnas de la tabla (atributos) que contienen valores nulos no se devuelven en las colecciones Attributes o FormattedValues de la consulta. Si una columna puede contener un valor nulo, debe verificar usando Contains antes de intentar acceder al valor.
Los resultados con formato aparecerán como sigue:
name:A Datum (sample)
primary contact: Rene Valdes (sample)
created on: 2/28/2018 11:04 AM
revenue: $10,000.000
status: Active
name:City Power & Light (sample)
primary contact: Scott Konersmann (sample)
created on: 2/28/2018 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
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: "El número de condiciones en la consulta superó el límite máximo".
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.
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).
Comentarios
Próximamente: a lo largo de 2024, eliminaremos gradualmente los problemas de GitHub como mecanismo de comentarios para el contenido y lo reemplazaremos por un nuevo sistema de comentarios. Para obtener más información, consulte: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de