Daten mithilfe des SDK für .NET abfragen

  • Artikel

Das SDK für .NET bietet mehrere Methoden zum Abfragen von Daten. Jede hat verschiedene Vorteile.

Methode Vorteile
FetchExpression Verwenden Sie cie Eigenschaft FetchXML zur Erstellung von Abfragen, die Aggregate zurückgeben, wie etwa die Summe eines Wertes für alle zurückgegebenen Datensätze. Sie können mit FetchXML auch Gruppierungsvorgänge ausführen. Kann Daten aus verknüpften Tabellenzeilen (Entitätsdatensätzen) enthalten.
QueryExpression Sie haben ein stark typisiertes Objektmodell, um komplexer Abfragen zu erstellen. Unterstützt alle FetchXML-Funktionen, ausgenommen Aggregate und Gruppierung. Kann Daten aus verknüpften Tabellenzeilen (Entitätsdatensätzen) enthalten.
QueryByAttribute Ein einfacheres Objektmodel als QueryExpression Verwenden Sie QueryByAttribute für Abfragen, bei denen Sie testen, ob alle Wertkriterien für Tabellenspalten (Attribute) in Ihrer Abfrage übereinstimmen. Kann nur Daten aus einer einzelnen Tabelle (Entitätstyp) zurückgeben.
LINQ OrganizationServiceContext.QueryProvider vverwenden. zum Abfragen mithilfe der gängigen LINQ-Syntax verfassen. Alle LINQ-Abfragen werden in QueryExpression konvertiert, um die von Ihnen verwendeten Funktionen zu beschränken, die für QueryExpression verfügbar sind
In diesem Artikel stehen die Stile von Abfragen im Mittelpunkt, die zu SDK-Assemblyklassen verfügbar sind. Weitere Informationen: Erstellen von Abfragen mit LINQ (.NET Sprache integrierte Abfrage)

FetchExpression, QueryExpression, znd QueryByAttribute stammen von QueryBase abstrakten Klassen. Es gibt zwei Möglichkeiten, um Ergebnisse einer Abfrage anzuzeigen, die mit dieser Klassen definiert wird:

Hinweis

Im IOrganizationService.RetrieveMultiple Methode wird grundsätzlich bevorzugt. Es gibt keine speziellen Funktionen, die für die Verwendung der RetrieveMultipleRequest-Klasse erforderlich sind.

Beide Möglichkeiten geben EntityCollection zurück, das die Ergebnisse der Abfrage in der Sammlung Entities und in den Eigenschaften enthält, um zusätzliche Abfragen zu verwenden, um ausgelagerte Ergebnisse zu erhalten.

Hinweis

Um die Leistung zu optimieren, kann jede Abfrageanforderung maximal 5.000 Zeilen zurückgeben. Um zum größeren Resultatset zurückzugeben müssen Sie weitere Seiten anfordern.

Alle Filterbedingungen für String-Werte sind unabhängig von der Groß-/Kleinschreibung.

Tabellenspalten mit Nullwerten werden nicht zurückgegeben.

Wenn eine Tabellenspalte (Entitätsattribut) einen Nullwert enthält oder wenn das Attribut nicht in den FetchXml-Attributen enthalten war oder im ColumnSet, der Entity.Attributes Sammlung das Attribut nicht. Es gibt keinen Schlüssel, um darauf zuzugreifen oder zurückzugeben. Das Fehlen des Attributs gibt an, dass es Null ist. Bei Verwendung des früh gebundenen Stils wird dies von den generierten Entity-Klasseneigenschaften verwaltet ein Nullwert wird zurückgegeben.

Wenn Sie bei Verwendung der späten Bindung versuchen, den Wert mit einem Indexer in den Sammlungen Attributes oder FormattedValues aufzurufen, wird eine The given key was not present in the dictionary mit der Nachricht KeyNotFoundException angezeigt.

Um dieses Problem zu vermeiden, wenn Sie die späte Bindung nutzen, können Sie zwei Strategien verwenden:

  1. Verwenden Sie für ein Attribut, das nicht zulässig sein kann, die Entity.Contains(String)- Methode, um zu überprüfen, ob das Attribut, das mit einem Indexer zuzugreift, ungültig ist. Beispiel:

    Money revenue = (entity.Contains("revenue")? entity["revenue"] : null);

  2. Entity.GetAttributeValue<T>(String) vverwenden. um auf den Wert zuzugreifen. Beispiel:

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

Hinweis

Wenn der mit GetAttributeValue<T>(String) angegebene Typ ein Werttyp ist, der nicht NULL sein darf, z. B. Boolean oder DateTime , ist der zurückgegebene Wert der Standardwert, z. B. false oder 1/1/0001 12:00:00 AM anstatt NULL.

Verwendung von FetchXML mit FetchExpression

FetchXml ist eine proprietäre XML-basiert Abfragesprache, die mit SDK Assemblyabfragen mithilfe von FetchExpression und durch die WEB API mithilfe einer Abfragezeichenfolge fetchXml verwendet werden kann. Weitere Informationen: Daten mithilfe von FetchXML abfragen

Das folgende Beispiel zeigt eine einfache Abfrage, um bis zu 50 übereinstimmende Kontozeilen zurückzugeben, in denen der Wert address1_city gleich Redmond ist, sortiert nach 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"]);
});

Wichtig

Beim Abrufen von Tabellenzeilen sollten Sie nur die benötigten Spaltenwerte anfordern, indem Sie die spezifischen Attribute mit attribute-Elementen angeben und nicht mit dem all-attributes-Element für die Rückgabe aller Attribute.

Weitere Informationen:

QueryExpression nutzen

Diese QueryExpression-Klasse stellt einen Satz stark typisierter Objekte dar, die für Ablaufmanipulation von Abfragen optimiert wird.

Das folgende Beispiel zeigt eine einfache Abfrage, um bis zu 50 übereinstimmende Kontozeilen zurückzugeben, in denen der Wert address1_city gleich Redmond ist, sortiert nach 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"]);
});

Wichtig

Beim Abrufen von Zeilen sollten Sie nur die benötigten Spaltenwerte anfordern, indem Sie die spezifischen Attribute mit dem Klassenkonstruktor ColumnSet angeben. Obwohl ColumnSet-Klassenkonstruktor eine Überladung bietet, die einem Booleschen Parameter allColumns annimmt, sollten Sie dies im Produktionscode nicht verwenden.

Weitere Informationen:

QueryByAttribute nutzen

Die Klasse QueryByAttribute stellt einen stark typisierten Satz von Objekten bereit, der für einfache, häufige Abfragen von Tabellenzeilen optimiert ist. Im Gegensatz zu FetchXML und QueryExpression kann QueryByAttribute nur Daten aus einer einzelnen Tabelle zurückgeben. Sie ermöglicht nicht das Abrufen von Daten aus verknüpften Tabellenzeilen oder komplexe Abfragekriterien.

Das folgende Beispiel zeigt eine einfache Abfrage, um bis zu 50 übereinstimmende Kontozeilen zurückzugeben, in denen der Wert address1_city gleich Redmond ist, sortiert nach 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"]);
});

Weitere Informationen:

Zugriff auf formatierte Werte

Unabhängig von der Methode, die Sie zum Abfragen von Tabellen verwenden, werden die Daten als EntityCollection.Entities zurückgegeben. Sie können auf die Datenwerte der Tabellenspalte (Attribute) zugreifen, indem Sie Entity.Attributes verwenden. Sammlung Aber diese Werte können vom Typ als Zeichenfolge, die Sie bearbeiten möchten abhängen, um Zeichenfolgenwerte abzurufen, die Sie in der Anwendung anzeigen möchten.

Sie können auf eichenfolgenwerte zugreifen, die die Umgebungseinstellungen zum Formatieren verwenden, da Werte im Entity.FormattedValues verwendet werden Sammlung

Im folgenden Beispiel wird gezeigt, wie Sie auf die gesammelten formatierten Zeichenfolgenwerte für die folgenden Firmaenattribute zugreifen:

Logischer Name des Attributs Art
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"]
  );
});

Hinweis

Tabellenspalten (Attribute), die Nullwerte enthalten, werden in der Abfrage Attributes oder in FormattedValues-Sammlungen nicht zurückgegeben. Wenn eine Spalte einen Nullwert enthalten kann, sollten Sie dies mit der Methode Contains überprüfen, bevor Sie versuchen, auf den Wert zuzugreifen.

Die formattierten Ergebnisse werden wie folgt angezeigt:

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

Konvertieren von Abfragen zwischen FetchXML und QueryExpression

Sie können QueryExpression-Abfragen in FetchXml und FetchXml-Abfragen in QueryExpression konvertieren, indem Sie die Klassen QueryExpressionToFetchXmlRequest und FetchXmlToQueryExpressionRequest verwenden.

Die Tabelle SavedQuery speichert Systemansichten für eine Tabelle (Entitätstyp) und die Tabelle UserQuery speichert gespeicherte Benutzerabfragen. Andere Tabellen können eine Abfrage auch als FetchXml-Zeichenfolge speichern. Diese Methoden ermöglichen das Konvertieren einer FetchXml-Zeichenfolge in QueryExpression, sodass sie mit dem Objektmodell bearbeitet und dann wieder in FetchXml konvertiert werden und somit als Zeichenfolge gespeichert werden kann.

Weitere Informationen: Beispiel: Konvertieren von Abfragen zwischen Fetch und QueryExpression

Grenzwerte für Abfragebedingungen

Dataverse hat einen Grenzwert von insgesamt 500 zulässigen Bedingungen in einer Abfrage. Alle Joins, die in der Abfrage enthalten sind, werden zu diesem Grenzwert hinzugezählt. Wenn eine Abfrage (und ihre Joins) 500 Bedingungen überschreitet, erhält der Benutzer beim Ausführen der Abfrage die folgende Fehlermeldung: „Die Anzahl der Bedingungen in der Abfrage hat den maximalen Grenzwert überschritten.“

In diesem Fall muss ein Benutzer entweder:

  • Reduzieren Sie die Anzahl der Bedingungen in der Abfrage.
  • Verwenden Sie die In-Klausel, die GUIDs und Zeichenfolgen mit bis zu 850 Zeichen ohne einen Grenzwert für Ganzzahlen zulässt.

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).