Früh gebundene Klassen für das .NET SDK generieren

Erstellen Sie früh gebundene Klassen für Ihre .NET-Projekte:

  • Verbessert die Lesbarkeit und Wartbarkeit des Codes.
  • Verringert das Risiko von Fehlern, da sie eine Typprüfung zur Kompilierzeit ermöglichen.
  • Verbessert die Produktivität der Entwickler, da Entwickler Mithilfe von IntelliSense Tabellen, Spalten und Auswahloptionen entdecken können.
  • Stellt die OrganizationServiceContext-Klasse bereit, damit Sie Dataverse-Abfragen mithilfe von LINQ schreiben und andere Funktionen zum Arbeiten mit Daten nutzen können.

Erfahren Sie mehr:

Verwenden Sie den Power Platform CLI pac modelbuilder build-Befehl, um Early-Bound-Codeklassen zu generieren. Sie können auch das CrmSvcUtil.exe Code-Generierungstool verwenden, aber für Dataverse empfehlen wir die Verwendung des pac modelbuilder build Befehls. Erfahren Sie, wie Sie CrmSvcUtil.exe verwenden, um früh gebundene Klassen für das SDK für .NET zu generieren

Wie viele Power Platform CLI-Befehle verfügt pac modelbuilder build über viele Parameter, mit denen Sie das Ergebnis steuern können. In diesem Artikel empfehlen wir Ihnen, für die meisten Anwendungsfälle zunächst den Parameter --settingsTemplateFile zu verwenden. Verwenden Sie diesen Parameter, um auf eine JSON-Datei zu verweisen, in der Sie alle anderen verfügbaren Einstellungen steuern können. Auf diese Weise müssen Sie keine lange Liste von Parametern erstellen, und Sie können die für Ihr Projekt geeignete Konfiguration aktualisieren, um die Regeneration der Klassen zu ermöglichen, wenn Sie sie benötigen.

Sie können den Buildbefehl weiterhin mit Parametern verwenden, wenn Sie dies bevorzugen. Siehe Parameter verwenden.

Starten Sie

Bevor Sie beginnen:

  1. Power Platform-CLI installieren.
  2. Stellen Sie eine Verbindung mit Ihrer Umgebung her, indem Sie Power Platform CLI-Pac-Authentifizierungsbefehle verwenden.

Verwenden Sie für den Einstieg die folgenden Schritte:

  1. Fügen Sie in Ihrem .NET-Projekt einen NuGet Paketverweis auf Folgendes hinzu:

  2. Einen Ordner namens model erstellen.

  3. Fügen Sie im Ordner model eine builderSettings.json Datei mit den folgenden Einstellungen hinzu:

    {
"emitentityetc-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
"emitEntityETC": false,
"emitfieldsclasses-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
"emitFieldsClasses": false,
"emitvirtualattributes-comment": "When set, includes the Virtual Attributes of entities in the generated code.",
"emitVirtualAttributes": false,
"entitynamesfilter-comment": "Filters the list of entities are retrieved when reading data from Dataverse.",
"entityNamesFilter": [
   "account",
   "contact"
],
"entitytypesfolder-comment": "Folder name that contains entities.",
"entityTypesFolder": "Entities",
"generateGlobalOptionSets-comment": "Emit all Global OptionSets. Note: If an entity contains a reference to a global optionset, it is emitted even if this switch is not present.",
"generateGlobalOptionSets": false,
"generatesdkmessages-comment": "When set, emits Sdk message classes as part of code generation",
"generateSdkMessages": true,
"language-comment": "The language to use for the generated proxy code. This value can be either 'CS' or 'VB'. The default language is 'CS'.",
"language": "CS",
"logLevel-comment": "Log level. The default value is 'Off'.",
"logLevel": "Off",
"messagenamesfilter-comment": "Filters the list of messages that are retrieved when reading data from Dataverse.",
"messageNamesFilter": [
   "searchautocomplete",
   "searchquery",
   "sample_*"
],
"messagestypesfolder-comment": "Folder name that contains messages.",
"messagesTypesFolder": "Messages",
"namespace-comment": "The namespace for the generated code.",
"namespace": "ExampleProject",
"optionsetstypesfolder-comment": "Folder name that contains option sets.",
"optionSetsTypesFolder": "OptionSets",
"serviceContextName-comment": "The name for the generated service context. If a value is passed in, it's used for the Service Context. If not, no Service Context is generated.",
"serviceContextName": "OrgContext",
"suppressGeneratedCodeAttribute-comment": "When set, this suppress all generated objects being tagged with the code generation engine and version",
"suppressGeneratedCodeAttribute": true,
"suppressINotifyPattern-comment": "When enabled, doesn't write the INotify wrappers for properties and classes.",
"suppressINotifyPattern": true
}

    Anmerkung

    Diese Datei ist eine geänderte Version der Datei, die Sie mithilfe pac modelbuilder build des --writesettingsTemplateFile Parameters generieren können. Erfahren Sie, wie Sie die Datei ohne Kommentare in mithilfe von Parametern erstellen.

  4. Verwenden Sie den folgenden Befehl, um früh gebundene Klassen für die verbundene Umgebung mithilfe der in builderSettings.jsonder Datei definierten Einstellungen zu generieren. Der C:\projects\exampleproject\ Pfad stellt den Pfad zu Ihrem Projekt dar und model ist der von Ihnen erstellte Ordner.

    PS C:\projects\exampleproject\model> pac modelbuilder build -o . -stf .\builderSettings.json

    Dieser Befehl verwendet diese Parameter:

    Sie können diesen Befehl auch aus dem exampleproject Verzeichnis verwenden:

    PS C:\projects\exampleproject>pac modelbuilder build -o model -stf model\builderSettings.json

Verstehen Sie, welche Dateien geschrieben werden

Mit beiden Befehlen erhalten Sie die folgende Ausgabe:

Connected to... Your Organization
Connected as you@yourorganization.onmicrosoft.com
Begin reading metadata from MetadataProviderService
      Begin Reading Metadata from Server
      Read 2 Entities - 00:00:00.732
      Read 0 Global OptionSets - 00:00:00.000
      Read 12 SDK Messages - 00:00:00.889
      Completed Reading Metadata from Server - 00:00:01.694
Completed reading metadata from MetadataProviderService - 00:00:01.697
Begin Writing Code Files
      Processing 2 Entities
      Wrote 2 Entities - 00:00:00.0625873
      Processing 12 Messages
      Wrote 3 Message(s). Skipped 9 Message(s) - 00:00:00.0091589
      Processing 0 Global OptionSets
      Wrote 0 Global OptionSets - 00:00:00.0000045
      Code written to C:\projects\exampleproject\model\Entities\account.cs.
      Code written to C:\projects\exampleproject\model\Entities\contact.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchquery.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchautocomplete.cs.
      Code written to C:\projects\exampleproject\model\OrgContext.cs.
      Code written to C:\projects\exampleproject\model\EntityOptionSetEnum.cs.
Completed Writing Code Files - 00:00:00.116
Generation Complete - 00:00:01.815
PS C:\projects\exampleproject\model>

Wenn Sie die Ausgabe prüfen, sehen Sie, dass nur Klassen für die Tabellen generiert werden, die durch entityNamesFilter angegeben sind, und nur die Nachrichten, die in messageNamesFilter angegeben sind. Geben Sie an, welche Tabellen (Entitäten) und Meldungen Sie in Ihrem Projekt verwenden. Andernfalls generiert der Befehl Klassen für alle Tabellen und Nachrichten.

Verwenden Sie für * in diesen Werten messageNamesFilter als Platzhalterzeichen. Dieser Filter ist nützlich, wenn Nachrichten in Ihrer Lösung ein gemeinsames Anpassungspräfix aufweisen.

pac modelbuilder build schreibt die Dateien in Ordner mit Namen, die Sie in der Einstellungsdatei steuern:

  • Entitätsklassen wechseln zu dem durch die entityTypesFolder Einstellung angegebenen Ordner.
  • Nachrichtenklassen wechseln zu dem durch die messagesTypesFolder Einstellung angegebenen Ordner.
  • Die OrganizationServiceContext-Klasse wechselt zu einer Datei mit dem durch die serviceContextName Einstellung angegebenen Namen.
  • Alle Klassen sind Teil des Namespace, den Sie in der Einstellung namespace festgelegt haben.

Anmerkung

Wenn Sie Nachrichtenklassen generieren, fügen Sie immer einen Namen für die serviceContextName Einstellung ein. Siehe Einschließen serviceContextName beim Generieren von Nachrichtenklassen.

So erscheinen die Dateien und Ordner in Visual Studio:

Beispielausgabe des Befehls „pac modelbuilder Build“ im Visual Studio Explorer

Nachdem diese Dateien in Ihr Projekt geschrieben wurden, können Sie nun früh gebundene Klassen verwenden.

Wenn Sie sie ändern möchten, löschen Sie die Dateien im model Order außer builderSettings.json, und ändern Sie die Einstellungen in builderSettings.json und generieren Sie sie erneut.

Parameter verwenden

Sie müssen die builderSettings.json Einstellungsdatei oder den --settingsTemplateFile Parameter mit pac modelbuilder build nicht verwenden. Sie können den Befehl mithilfe von Parametern direkt aufrufen. Referenzdokumentation und Beispiele finden Sie in der Referenzdokumentation zum Pac-Modellbuilder.

Wenn Sie die Einstellungsdatei builderSettings.json und den --settingsTemplateFile Parameter verwenden, können Sie Befehlszeilenparameter verwenden, um diese Einstellungen außer Kraft zu setzen.

Hier ist ein Beispiel, das zeigt, wie Dateien mithilfe der gleichen Einstellungen wie das Beispiel im Abschnitt "Erste Schritte " mithilfe von Parametern generiert werden:

PS C:\>pac modelbuilder build `
   --outdirectory C:\projects\exampleproject\model `
   --entitynamesfilter 'account;contact' `
   --generatesdkmessages `
   --messagenamesfilter 'searchautocomplete;searchquery;sample_*' `
   --namespace ExampleProject `
   --serviceContextName OrgContext `
   --suppressGeneratedCodeAttribute `
   --suppressINotifyPattern `
   --writesettingsTemplateFile

Dieses Beispiel enthält nicht alle Einstellungen, da die Standardoptionen verwendet werden. Wenn Sie den --writesettingsTemplateFile Parameter zum Generieren einer builderSettings.json Datei verwenden, werden die Kommentare im Beispiel im Abschnitt erste Schritte nicht berücksichtigt. Im Beispiel, in dem Parameter verwendet werden, wird die folgende builderSettings.json Datei in den model Ordner geschrieben:

{
  "suppressINotifyPattern": true,
  "suppressGeneratedCodeAttribute": true,
  "language": "CS",
  "namespace": "ExampleProject",
  "serviceContextName": "OrgContext",
  "generateSdkMessages": true,
  "generateGlobalOptionSets": false,
  "emitFieldsClasses": false,
  "entityTypesFolder": "Entities",
  "messagesTypesFolder": "Messages",
  "optionSetsTypesFolder": "OptionSets",
  "entityNamesFilter": [
    "account",
    "contact"
  ],
  "messageNamesFilter": [
    "searchautocomplete",
    "searchquery",
    "sample_*"
  ],
  "emitEntityETC": false,
  "emitVirtualAttributes": false
}

Beim Generieren von Nachrichtenklassen serviceContextName einschließen

Wenn Sie Nachrichtenklassen generieren, fügen Sie immer einen Namen für den serviceContextName Parameter ein, damit eine OrganizationServiceContext-Klasse mit Ihrem Code generiert wird. Diese Klasse enthält eine wichtige Eigenschaft, um die Verwendung generierter Nachrichtenklassen zu ermöglichen. Wenn Sie kein OrganizationServiceContext einfügen, erhalten Sie beim Versuch, die generierten Nachrichtenklassen zu verwenden, die folgende Fehlermeldung.

The formatter threw an exception while trying to deserialize the message: 
There was an error while trying to deserialize parameter http://schemas.microsoft.com/xrm/2011/Contracts/Services:request. 
The InnerException message was 'Error in line 1 position 700. Element 'http://schemas.microsoft.com/xrm/2011/Contracts/Services:request' contains data from a type that maps to the name 'http://schemas.microsoft.com/xrm/2011/new/:<your generated class name>'. 
The deserializer has no knowledge of any type that maps to this name. 
Consider changing the implementation of the ResolveName method on your DataContractResolver to return a non-null value for name '<your generated class name>' and namespace 'http://schemas.microsoft.com/xrm/2011/new/'.'.  
Please see InnerException for more details.

Community-Werkzeuge

Der Early Bound Generator V2 ist ein XrmToolBox-Plug-In, das von der Community erstellt wurde, um eine Benutzeroberfläche bereitzustellen, die die richtige builderSettings.json Datei generiert, und ruft den pac modelbuilder build Befehl für den Benutzer auf. Da die Benutzeroberfläche nur die builderSettings.json Datei generiert und den pac modelbuilder build Befehl aufruft, können Sie den Befehl trotzdem ohne Abhängigkeit von der XrmToolBox in einer Pipeline ausführen. Das Plugin bietet auch Konfigurationsoptionen, die pac modelbuilder nicht bietet. So lässt sich beispielsweise die Groß- und Kleinschreibung von Klassen und Eigenschaften sowie die sprachspezifische Transliteration von Zeichen explizit steuern. Early Bound Generator V2 kann dies mithilfe der Erweiterungsfunktionen von pac modelbuilder.

Anmerkung

Microsoft erweitert keine Unterstützung für von der Community entwickelte Tools. Wenn Sie Fragen zum Tool haben, wenden Sie sich an den Herausgeber. Weitere Informationen finden Sie unter XrmToolBox.

Für Dynamics 365 Customer Engagement (lokal)

Das Power Platform CLI ist für Dynamics 365 Customer Engagement lokal nicht verfügbar. Sie müssen das CrmSvcUtil.exe Codegenerierungstool verwenden, um früh gebundene Klassen zu generieren. Erfahren Sie, wie Sie CrmSvcUtil.exe verwenden, um früh gebundene Klassen für das SDK für .NET zu generieren

Spät gebundene und früh gebundene Programmierung
Beispiel: Tabellenoperationen mit früher Bindung
Entwicklertools und -ressourcen
Dataverse-Entwicklungswerkzeuge
Erfahren Sie, wie Sie CrmSvcUtil.exe verwenden, um früh gebundene Klassen für das SDK für .NET zu generieren

  • Last updated on