Entitätsklassenvorgänge mithilfe des SDK für .NET

  • Artikel

Wenn Sie mit Microsoft Dataverse-Daten mithilfe des SDK für .NET arbeiten, verwenden Sie die Entity-Klasse mit später Bindung oder mit erstellten Entitätsklassen mithilfe früher Bindung. Die erstellten Entitätsklassen erben von der Entity Klasse, deshalb ist das Verstehen der Entity Klasse für jeden Stil wichtig.

In diesem Kapitel werden einige der am häufigsten verwendeten Eigenschaften und Methoden der Entity-Klasse beschrieben.

Logischer Entitätsname

Wenn Sie eine neue Instanz der Klasse Entity unter Verwendung des spät gebundenen Stils instanziieren, müssen Sie einen gültigen String-Wert angeben, um zu spezifizieren, um welchen Entity-Typ es sich handelt. Die LogicalName ist in den Metadaten der Entität (Tabellendefinition) definiert.

Wenn Sie die frühe Bindung verwenden, ist dieser Wert vom Konstruktor der Webressourcen generierten Klasse festgelegt. Beispiel: var account = new Entity("account");

Wenn Sie in Ihrem Code später den String-Wert abrufen wollen, der den Entity-Typ beschreibt, können Sie die Eigenschaft LogicalName verwenden. Dies ist für die vielen APIs hilfreich, die einen logischen Entitätsnamen als Parameter erfordern.

Entitäts.ID

Wenn Sie die Klasse Entity instanziieren, unabhängig davon, ob Sie den spät gebundenen oder den früh gebundenen Stil verwenden, hat sie keine eindeutige ID. Wenn Sie eine Entität erstellen, möchten Sie sie nicht festlegen, können jedoch vom System festgelegt werden beim Erstellen (Speichern).

Wenn Sie eine Entität abrufen, ist ein Primärschlüsselattributwert enthalten, ob sie diesen angefordert haben oder nicht. Der Primärschlüsselattributname ist für jeden Entitätstyp unterschiedlich. Generell ist der Name des Primärschlüsselattributs die Entität logicalname + id. Für ein Konto ist es accountid und für einen Kontakt ist es contactid.

Wenn Sie den Primärschlüsselwert mithilfe des Primärschlüsselattributs abrufen oder festlegen, kann die Id-Eigenschaft auch verwendet werden, um auf den Wert zuzugreifen, ohne dass Sie sich an den Namen des Primärschlüsselattributs erinnern müssen.

Früh gebundener Zugriff auf Tabellenspalten

Wenn Sie die frühe Bindung verwenden, um Klassen zu erstellen, finden Sie typisierte Eigenschaften für jedes Attribut in der Klasse. Die Eigenschaften für die Attribute verwenden AttributeMetadata.SchemaName und auf diese kann direkt auf die Klasseninstanz Entity zugegriffen werden.

Beispiel: ''

//Using the early-bound Account entity class
var account = new Account();
// set attribute values
// string primary name
account.Name = "Contoso";
// Boolean (Two option)
account.CreditOnHold = false;
// DateTime
account.LastOnHoldTime = new DateTime(2017, 1, 1);
// Double
account.Address1_Latitude = 47.642311;
account.Address1_Longitude = -122.136841;
// Int
account.NumberOfEmployees = 500;
// Money
account.Revenue = new Money(new decimal(5000000.00));
// Picklist (Option set)
account.AccountCategoryCode = new OptionSetValue(1); //Preferred customer

Spät gebundener Zugriff auf Tabellenspalten

Die Daten, die in einer einzelnen Entität enthalten sind in Entity.Attributes Eigenschaft verfügbar sind. Diese Eigenschaft ist ein AttributeCollection, die einen ganzen Satz Methoden bereitstellt, um neue Attribute hinzuzufügen und zu überprüfen, ob ein Attribut vorhanden ist ode zum Entfernen von Attributen.

Erkennen von Spaltennamen und Datentypen

Bei späten Bindungen müssen Sie die AttributeMetadata.LogicalName für die Attribute und den Datentyp kennen. Der LogicalName Ist die kleingeschriebene Version von SchemaName. Sie erkunden und tippen LogicalName für Attribute auf unterschiedliche Arten ein:

Attributtypen können die folgenden sein. Dies ist eine unvollständige Liste.

Art Beschreibung
EntityReference Ein Such-Aztribut. Eine Verknüpfung zu einem anderen Entitätsdatensatz.
BooleanManagedProperty Verwendet nur für Entitäten, die Lösungskomponenten sind, wie WebResource. Weitere Informationen: Bearbeiten von verwalteten Eigenschaften
Money Ein Attribut Währung.
OptionSetValue Ein Attribut Optionssatz Status- und Status-Attribute verwenden auch diesen Typ.
Boolean Ein Attribut Zwei Option.
Byte[] Ein Attribut Bild. Jede Entität kann über ein Bildattribut verfügen und das Attribut nennt sich entityimage. Eine URL, um das Bilds herunterzuladen. kann in einem Begleitattribut abgerufen werden namens entityimage_url. Weitere Informationen Bildattribute
DateTime Ein Attribut Datum und Uhrzeit verwendet UTC-Wert. Weitere Informationen: Verhalten und Format des Datums- und Uhrzeitattributs
Decimal Ein Dezimalzahl Attribut.
Double Ein Attribut Gleitkommazahl.
Guid Normalerweise wird der eindeutige Bezeichner für die Entität verwendet.
Int32 Ein Ganzzahl Attribut.
String Mehrere Textzeilen und Einzelne Textzeile Attribute verwenden Sie diesen Typ. Ein weiterer, weniger verbreiteter, Typ, der Zeichenfolgen verwendet, ist EntityName-Spalten, die einen Zeichenfolgenwert speichern, der den logischen Namen einer Tabelle darstellt.

Hinweis

Dateispalten sind nicht direkt von der Entität verfügbar. Sie müssen eine Reihe von Anforderungen verwenden, um Daten aus Dateispalten hoch- oder herunterzuladen. Weitere Informationen: Dateispaltendaten verwenden

Es gibt drei unterschiedliche Arten, mit Entitätsattributen mithilfe der späten Bindung zu interagieren:

  • Verwenden Sie den Indexer auf die Entity-Klasse
  • Verwenden Sie den Index in der Attributes Sammlung
  • Verwenden Sie die bereitgestellten Entity-Methoden

Verwenden Sie den Indexer auf der Klasse Entity

In den meisten Fällen können Sie mithilfe der späten Bindung mit der Sammlung interagieren, indem Sie den Indexer verwenden, um den Wert eines Attributs mithilfe des LogicalName für das Attribut festzulegen. Beispielsweise um das Namensattribut einer Firma festzulegen:

//Use Entity class with entity logical name
var account = new Entity("account");
// set attribute values
// string primary name
account["name"] = "Contoso";
// Boolean (Two option)
account["creditonhold"] = false;
// DateTime
account["lastonholdtime"] = new DateTime(2017, 1, 1);
// Double
account["address1_latitude"] = 47.642311;
account["address1_longitude"] = -122.136841;
// Int
account["numberofemployees"] = 500;
// Money
account["revenue"] = new Money(new decimal(5000000.00));
// Picklist (Option set)
account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer

Verwenden Sie den Index in der Attribut-Sammlung

Gelich wie Sie dies für die Entität tun würden, können Sie auch auf einen Wert zugreifen, indem Sie den Index in der Attributsammlung verwenden.

string accountName = account.Attributes["name"];

Verwenden Sie die Entity-Methoden

Sie können auch Entity Methoden verwenden, um den Attributwerte festzulegen oder abzurufen.

Methode Beschreibung
GetAttributeValue<T>(String) Verwenden Sie diesen Antworttyp, um einen typisierten Attributwert zurückzugeben
SetAttributeValue(String, Object) Verwenden Sie dies, um einen typisierten Attributwert zurückzugeben

Beispiel:

account.SetAttributeValue("name", "Account Name");
var accountName = account.GetAttributeValue<string>("name");

Entity.FormattedValues

Jeder Entitätsattributwert, der in der Benutzeroberfläche angezeigt wird und keine Zeichenfolgen ist, hat einen Zeichenfolge formatierten Wert, der verwendet werden kann, um den Wert auf der Benutzeroberfläche anzuzeigen. Beispiel:

  • Geldbeträge haben Zeichenfolgenwert mit der entsprechenden Genauigkeits- und Währungsformatierung.
  • Datumswerte haben Formatierungen, die festgelegt sind abhängig davon, wie das System konfiguriert wird
  • OptionSet (Auswahlmöglichkeiten) Werte zeigen die lokalisierte Bezeichnung an, die den Integer-Wert repräsentiert

Hinweis

Formatierte Werte werden ausschließlich auf Entitäten angewendet, die abgerufen wurden. Nachdem Sie den Wert festgelegt haben, wird kein neuer WErt kalkuliert, bis Sie die Entität speichern und die Entität erneut abrufen. Der formatierte Wert wird auf dem Server erstellt.

Sie können die Werte über die FormattedValues-Sammlung eines Indexers oder die Entitätsmethode GetFormattedAttributeValue(String) aufrufen.

Beispielsweise haben beide denselben formatierten Wert:

var formattedRevenueString1 = account.FormattedValues["revenue"];
var formattedRevenueString2 = account.GetFormattedAttributeValue("revenue");

Weitere Informationen: Zugriff auf formatierte Werte

Entity.RelatedEntities

Wenn Sie einen Entity-Datensatz (Tabellenzeile) erstellen, können Sie auch eine Reihe von verwandten Entity-Datensätzen definieren, die im selben Vorgang erstellt werden sollen. Mehr Informationen: Zusammenhängende Tabellenzeilen in einem Arbeitsgang erstellen

Wenn Sie einen Entity-Datensatz mit RetrieveRequest abrufen, können Sie RelatedEntitiesQuery mit einer Abfrage setzen, um verwandte Entity-Datensätze in die Ergebnisse aufzunehmen. Weitere Informationen: Abrufen mit Bezugszeilen

Wenn Sie verwandte Entitätsdatensätze in die Ergebnisse einbeziehen, können Sie auch Werte in diesen verwandten Datensätzen aktualisieren und sie einbeziehen, wenn Sie den Entitätsdatensatz aktualisieren. Weitere Informationen: Zusammenhängende Tabellenzeilen in einem Vorgang aktualisieren

In eine EntityReference konvertieren

Viele Nachrichteneigenschaften benötigen nur eine EntityReference Verwenden Sie die Entity.ToEntityReference() Methode, um einen Entity-Datensatz in eine Entity-Referenz zu konvertieren.

Konvertieren in eine Entitätsklasse

Wenn Sie den „early-bound”-Stil verwenden, müssen Sie die Entity-Instanz in den Typ der generierten Entity-Klasse umwandeln, den Sie verwenden. Dies kann in der Regel mit einer Schnittstelle erfolgen, aber Sie können auch die Entity.ToEntity<T>() verwenden Methode verwenden.

Account account1 = (Account)retrievedEntity;
Account account2 = retrievedEntity.ToEntity<Account>();

Hinweis

Diese Methode kann nicht verwendet werden, um eine generierte Entity Klasseninstanz in eine andere generierte Klasse oder in Entity umzuwandeln. Sie können nur verwendet werden, um eine Instanz Entity zu einer der Webressourcen generierte Klassen zu konvertieren, die von diesen erben. Wenn die Entity-Instanz nicht wirklich eine Instanz der Webressourcen generierte Klasse ist, löst diese Nachricht ein Fehler aus.

Nächste Schritte

In diesen Themen wird das Arbeiten mit Dataverse-Instanzen (Tabellenzeilen) näher erläutert.

Schnellstart: SDK für .NET-Beispiel (C#)
Daten abfragen
Tabellenzeilen erstellen
Abrufen einer Tabellenzeile
Eine Tabellenzeile aktualisieren und löschen
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen
Generieren Sie Klassen für früh gebundene Programmierung

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