Generieren von Klassen mit früher Bindung für das SDK für .NET

  • Artikel

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

  • Verbessert die Lesbarkeit und Wartbarkeit des Codes.
  • Verringert das Fehlerrisiko, da sie eine Typprüfung zur Kompilierungszeit ermöglichen.
  • Verbessert die Entwicklerproduktivität, da Entwickler mithilfe von IntelliSense Tabellen, Spalten und Auswahloptionen entdecken können.
  • Bietet die OrganizationServiceContext Klasse an, damit Sie Dataverse Abfragen schreiben können, die LINQ und andere Funktionen verwenden, um mit Daten zu arbeiten.

Erfahren Sie mehr:

Benutzen Sie den Power Platform CLI pac Modelersteller-Build-Befehl, um früh gebundene 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 alle anderen verfügbaren Einstellungen gesteuert werden können. Auf diese Weise müssen Sie keine lange Parameterliste erstellen und die für Ihr Projekt geeignete Konfiguration kann aktualisiert werden, um die Neugenerierung der Klassen bei Bedarf zu ermöglichen.

Natürlich können Sie den Build-Befehl weiterhin mit Parametern verwenden, wenn Sie dies bevorzugen. Siehe Parameter verwenden.

Starten Sie

Bevor Sie beginnen:

  1. Power Platform-CLI installieren.
  2. Stellen Sie mithilfe von Power Platform CLI-PAC-Authentifizierungsbefehlen eine Verbindung zu Ihrer Umgebung her

Verwenden Sie für den Einstieg die folgenden Schritte:

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

  2. Neuen Ordner names 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
}

    Hinweis

    Diese Datei ist eine modifizierte Version der Datei, die Sie mit pac modelbuilder build mit dem --writesettingsTemplateFile Parameter 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 zu generieren, indem Sie die in builderSettings.json definierten Einstellungen verwenden, wobei C:\projects\exampleproject\ den Pfad zu Ihrem Projekt darstellt und model den Ordner darstellt, den Sie erstellt haben.

    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 Verzeichnis exampleproject verwenden:

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

Verstehen Sie, welche Dateien geschrieben werden

Bei beiden Befehlen ist die folgende Ausgabe zu erwarten:

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>

Beachten Sie beim Untersuchen der Ausgabe, dass nur Klassen für die in entityNamesFilter angegebenen Tabellen und nur die in messageNamesFilter angegebenen Nachrichten generiert werden. Sie sollten angeben, welche Tabellen (Entitäten) und Nachrichten Sie in Ihrem Projekt verwenden. Andernfalls werden Klassen für alle Tabellen und Nachrichten generiert.

Sie können für messageNamesFilter * in diesen Werten als Platzhalterzeichen verwenden. Dies ist nützlich, wenn Nachrichten in Ihrer Lösung ein gemeinsames Anpassungspräfix haben.

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

  • Entitätsklassen werden in den Ordner geschrieben, der durch die Einstellung entityTypesFolder angegeben wird.
  • Nachrichtenklassen werden in den Ordner geschrieben, der durch die Einstellung messagesTypesFolder angegeben wird.
  • Die Klasse OrganizationServiceContext wird in eine Datei mit dem durch die Einstellung serviceContextName angegebenen Namen geschrieben.
  • Alle Klassen sind Teil des Namespace, den Sie in der Einstellung namespace festgelegt haben.

Hinweis

Wenn Sie Nachrichtenklassen generieren, sollten Sie immer einen Namen für die serviceContextName-Einstellung angeben. Siehe Beim Generieren von Nachrichtenklassen serviceContextName einschließen

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

Es ist nicht erforderlich, die builderSettings.json Einstellungsdatei und den --settingsTemplateFile Parameter mit pac modelbuilder build zu verwenden. Sie können den Befehl mithilfe von Parametern direkt aufrufen. Referenzdokumentation und Beispiele finden Sie in der pac Modelbuilder Build-Referenzdokumentation.

Wenn Sie die builderSettings.json Einstellungsdatei und den --settingsTemplateFile Parameter verwenden, können Sie die Parameter in der Befehlszeile verwenden, um die Einstellungen zu überschreiben.

Hier ist ein Beispiel, das zeigt, wie Dateien mit denselben Einstellungen wie im Beispiel im Abschnitt Erste Schritte unter Verwendung 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

Dies umfasst 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. Das Beispiel mit Parametern schreibt die folgende builderSettings.json Datei in den Ordner model :

{
  "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, sollten Sie immer einen Namen für die serviceContextName-Parameter angeben, sodass 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 keinen OrganizationServiceContext einschließen, erhalten Sie die folgende Fehlermeldung, wenn Sie versuchen, die generierten Nachrichtenklassen zu verwenden.

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-Tools

Der früh gebundene Generator ist ein XrmToolBox-Plug-In, das von der Community erstellt wurde, um eine Benutzeroberfläche und viele andere Konfigurationen für die Generierung früher gebundener Typen bereitzustellen.

Hinweis

Die Communitytools sind kein Produkt von Microsoft und es wird kein Support für die Communitytools angeboten. Wenn Sie Fragen zu dem Tool haben, setzen Sie sich bitte mit dem Herausgeber in Verbindung. Weitere Informationen: 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: Tabellenvorgänge 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

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