Sélectionner des colonnes à l’aide de FetchXml

  • Article

Comme décrit dans Interroger des données à l’aide de FetchXml, démarrez votre requête en sélectionnant une table à l’aide de l’élément entity.

Utilisez l’élément attribute pour sélectionner les colonnes à renvoyer avec votre requête. Par exemple :

<fetch>
  <entity name='account'>
    <attribute name='accountclassificationcode' />
    <attribute name='createdby' />
    <attribute name='createdon' />
    <attribute name='name' />
  </entity>
</fetch>

Cette requête renvoie les colonnes AccountClassificationCode, CreatedBy, CreatedOn et Name des 5 000 premières lignes de la table Compte. Si vous avez besoin de plus de lignes ou si vous souhaitez itérer dans des jeux de données plus petits, découvrez comment paginer des résultats à l’aide de FetchXml.

Pour chaque attribut que vous souhaitez renvoyer, ajoutez un élément attribute et définissez la valeur de l’attribut name sur le LogicalName de la colonne.

Utilisez l’élément attribute pour sélectionner les colonnes de l’entité de ​​votre requête et toutes les tables jointes à l’aide de l’élément link-entity. Découvrez comment joindre des tables à l’aide de FetchXml.

Important

Nous déconseillons fortement de renvoyer toutes les colonnes d’une table. Le renvoi de toutes les colonnes ralentira l’exécution de vos applications et peut provoquer des erreurs de délai d’attente. Vous devez spécifier le nombre minimum de colonnes à récupérer avec vos données. Si vous ne spécifiez pas de colonnes ou si vous utilisez l’élément all-attributes, les données de toutes les colonnes sont renvoyées.

Valeurs mises en forme

Les données saisies renvoyées peuvent ne pas être adaptées à l’affichage dans votre application. Les valeurs formatées sont des valeurs de chaîne renvoyées avec la requête que vous pouvez afficher dans votre application.

Examinons d’abord les résultats sans utiliser de valeurs formatées.

Cette méthode SimpleOutput accède uniquement aux valeurs de la collection Entity.Attributes.

/// <summary>
/// Output the entity attribute values
/// </summary>
/// <param name="service">The authenticated IOrganizaitonService instance</param>
static void SimpleOutput(IOrganizationService service) {

    string fetchXml = @"<fetch>
            <entity name='account'>
                <attribute name='accountclassificationcode' />
                <attribute name='createdby' />
                <attribute name='createdon' />
                <attribute name='name' />
            </entity>
            </fetch>";

    FetchExpression fetchExpression = new(fetchXml);

    //Retrieve the data
    EntityCollection entityCollection = service.RetrieveMultiple(query: fetchExpression);

    var table = new ConsoleTables.ConsoleTable("classificationcode", "createdby", "createdon", "name");

    foreach (var entity in entityCollection.Entities ) {

        var accountclassificationcode = entity.GetAttributeValue<OptionSetValue>("accountclassificationcode").Value;
        var createdby = entity.GetAttributeValue<EntityReference>("createdby").Name;
        var createdon = entity.GetAttributeValue<DateTime>("createdon");
        var name = entity.GetAttributeValue<string>("name");

        table.AddRow(accountclassificationcode, createdby, createdon, name);

    }
    table.Write();
}

Sortie :

 ----------------------------------------------------------------------------------------------
 | classificationcode | createdby           | createdon             | name                    |
 ----------------------------------------------------------------------------------------------
 | 1                  | FirstName LastName  | 8/13/2023 10:30:08 PM | Fourth Coffee (sample)  |
 ----------------------------------------------------------------------------------------------
 | 1                  | FirstName LastName  | 8/13/2023 10:30:10 PM | Litware, Inc. (sample)  |
 ----------------------------------------------------------------------------------------------
 | 1                  | FirstName LastName  | 8/13/2023 10:30:10 PM | Adventure Works (sample)|
 ----------------------------------------------------------------------------------------------

Ces valeurs peuvent ne pas être les valeurs conviviales que vous devez afficher dans une application.

  • La colonne de choix accountclassificationcode renvoie la valeur entière.
  • La référence du SDK à createdby doit utiliser la propriété EntityReference.Name
  • L’API Web renvoie la propriété de recherche _createdby_value qui possède la valeur GUID pour la colonne de recherche createdby.

Pour obtenir les valeurs conviviales souhaitées, vous devez accéder aux valeurs formatées qui peuvent être renvoyées par Dataverse.

La manière dont vous obtenez ces valeurs dépend si vous utilisez le SDK pour .NET ou l’API web.

L’exemple de méthode OutputFetchRequest décrit dans l’exemple de code FetchXml utilise les données de la collection Entity.FormattedValues ; par conséquent, les résultats de la requête ressemblent à ceci :

 --------------------------------------------------------------------------------------------------
 | accountclassificationcode | createdby           | createdon          | name                    |
 --------------------------------------------------------------------------------------------------
 | Default Value             | FirstName LastName  | 8/13/2023 10:30 PM | Fourth Coffee (sample)  |
 --------------------------------------------------------------------------------------------------
 | Default Value             | FirstName LastName  | 8/13/2023 10:30 PM | Litware, Inc. (sample)  |
 --------------------------------------------------------------------------------------------------
 | Default Value             | FirstName LastName  | 8/13/2023 10:30 PM | Adventure Works (sample)|
 --------------------------------------------------------------------------------------------------

Cette méthode GetRowValues extrait une liste de valeurs de chaîne pour un enregistrement de Entity.FormattedValues quand elles sont disponibles.

/// <summary>
/// Returns the values of a row as strings
/// </summary>
/// <param name="columns">The names of the columns</param>
/// <param name="entity">The entity with the data</param>
/// <returns></returns>
static List<string> GetRowValues(List<string> columns, Entity entity)
{
   List<string> values = new();
   columns.ForEach(column =>
   {
      if (entity.Attributes.ContainsKey(column))
      {
            // Use the formatted value if it available
            if (entity.FormattedValues.ContainsKey(column) &&
            !string.IsNullOrWhiteSpace(entity.FormattedValues[column]))
            {
               values.Add($"{entity.FormattedValues[column]}");
            }
            else
            {
               // When an alias is used, the Aliased value must be converted
               if (entity.Attributes[column] is AliasedValue aliasedValue)
               {
                  // When an EntityReference doesn't have a Name, show the Id
                  if (aliasedValue.Value is EntityReference lookup &&
                  string.IsNullOrWhiteSpace(lookup.Name))
                  {
                        values.Add($"{lookup.Id:B}");
                  }
                  else
                  {
                        values.Add($"{aliasedValue.Value}");
                  }
               }
               else
               {
                  // Use the simple attribute value
                  values.Add($"{entity.Attributes[column]}");
               }
            }
      }
      // Null values are not in the Attributes collection
      else
      {
            values.Add("NULL");
      }

   });
   return values;
}

En savoir plus sur les valeurs formatées :

Alias de colonne

Les alias de colonne sont généralement utilisés pour les opérations d’agrégation, mais ils fonctionnent également pour des opérations de sélection simples, nous pouvons donc les présenter ici.

Utilisez l’attribut alias de l’attribut pour spécifier un nom de colonne unique pour les résultats renvoyés.

Chaque colonne renvoyée doit avoir un nom unique. Par défaut, les noms de colonnes renvoyés pour la table de votre requête sont les valeurs LogicalName des colonnes. Tous les noms logiques de colonnes sont uniques pour chaque table, il ne peut donc pas y avoir de noms en double dans cet ensemble.

Lorsque vous utilisez un élément link-entity pour joindre des tables, les noms de colonnes par défaut suivent cette convention d’affectation de noms : {Linked table LogicalName}.{Column LogicalName}. Cela évite les noms de colonne en double. Vous pouvez remplacer ce paramètre en utilisant un alias unique. Vous pouvez également définir une valeur alias pour link-entity représentant la table jointe.

Le comportement que vous voyez lors de l’utilisation d’alias de colonne dépend si vous utilisez le SDK pour .NET ou l’API Web.

Cette méthode SimpleAliasOutput utilise des alias plutôt que les noms logiques des colonnes. Pour cette raison, les résultats sont renvoyés sous la forme AliasedValue. Pour accéder à la valeur de types complexes comme OptionSetValue ou EntityReference, vous devez effectuer un cast de la valeur.

Cette méthode utilise le package NuGet ConsoleTables.

/// <summary>
/// Output the entity attribute values with aliases
/// </summary>
/// <param name="service">The authenticated IOrganizaitonService instance</param>
static void SimpleAliasOutput(IOrganizationService service)
{
    string fetchXml = @"<fetch top='3'>
            <entity name='account'>
              <attribute name='accountclassificationcode' alias='code' />
              <attribute name='createdby' alias='whocreated' />
              <attribute name='createdon' alias='whencreated' />
              <attribute name='name' alias='companyname' />
            </entity>
          </fetch>";

    FetchExpression fetchExpression = new(fetchXml);

    //Retrieve the data
    EntityCollection entityCollection = service.RetrieveMultiple(query: fetchExpression);

    var table = new ConsoleTables.ConsoleTable("code", "whocreated", "whencreated", "companyname");

    foreach (var entity in entityCollection.Entities)
    {

        var code = ((OptionSetValue)entity.GetAttributeValue<AliasedValue>("code").Value).Value;
        var whocreated = ((EntityReference)entity.GetAttributeValue<AliasedValue>("whocreated").Value).Name;
        var whencreated = entity.GetAttributeValue<AliasedValue>("whencreated").Value;
        var companyname = entity.GetAttributeValue<AliasedValue>("companyname").Value;

        table.AddRow(code, whocreated, createdon, companyname);

    }
    table.Write();
}

Sortie :

 ----------------------------------------------------------------------------------
 | code | whocreated           | whencreated           | companyname              |
 ----------------------------------------------------------------------------------
 | 1    | FirstName LastName   | 8/13/2023 10:30:08 PM | Fourth Coffee (sample)   |
 ----------------------------------------------------------------------------------
 | 1    | FirstName LastName   | 8/13/2023 10:30:10 PM | Litware, Inc. (sample)   |
 ----------------------------------------------------------------------------------
 | 1    | FirstName LastName   | 8/13/2023 10:30:10 PM | Adventure Works (sample) |
 ----------------------------------------------------------------------------------

Notes

La classe AliasedValue a deux propriétés qui vous indiquent les valeurs EntityLogicalName et AttributeLogicalName d’origine si vous en avez besoin.

Étapes suivantes

Découvrez comment joindre des tables.

Joindre des tables

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).