Freigeben über

Plug-In-Code erstellen und packen

  • Artikel

In diesem Artikel werden Einschränkungen und Beschränkungen beschrieben, die Sie beim Konfigurieren und Erstellen einer Assembly für Ihr Microsoft Dataverse-Plug-In kennen müssen.

Einschränkungen der Plug-In-Assembly

Wenn Sie ein Plug-In-Projekt erstellen, beachten Sie die folgenden Einschränkungen der Ausgabeassembly.

Verwenden von .NET Framework 4.6.2

Plug-In- und benutzerdefinierte Workflowaktivität-Assembly-Projekte müssen auf .NET Framework 4.6.2 abzielen. Mit späteren Versionen des .NET Frameworks erstellte Assemblys sollten im Allgemeinen funktionieren. Wenn der Plug-In-Code jedoch Funktionen verwendet, die nach 4.6.2 eingeführt wurden, tritt ein Laufzeitfehler auf.

Begrenzen Sie Assemblys auf 16 MB

Ihre Assembly kann mehrere Plug-In-Klassen oder -Typen und sogar benutzerdefinierte Workflow-Aktivitäten enthalten, darf aber nicht größer als 16 MB sein. Als Best Practice wird empfohlen, dass Sie Plug-Ins und Workflow-Assemblys in eine einzelne Assembly konsolidieren, solange die Größe unter 16 MB bleibt.

Signieren Sie Assemblys, bevor Sie sie registrieren

Wenn Sie die Funktion abhängige Assemblys nicht verwenden, müssen Assemblys signiert werden, bevor Sie sie mit Dataverse registrieren können. Um die Assembly zu signieren, verwenden Sie die Visual Studio-Registerkarte Signierung in den Eigenschaften Ihres Projekts oder den Befehl Sn.exe (Strong Name Tool)

NuGet CoreAssemblies befinden sich in der Sandbox

Wenn Sie das Paket Microsoft.CrmSdk.CoreAssemblies NuGet zu Ihrem Projekt hinzufügen, werden auch die erforderlichen Dataverse-Assembly-Referenzen hinzugefügt, aber die Assemblys selbst werden nicht mit Ihrer Plug-In-Assembly hochgeladen. Sie existieren bereits in der Sandbox Runtime des Servers, in der Ihr Code ausgeführt wird

Abhängige Assemblys

Wichtig

Die Funktion zur abhängigen Assembly ist für die Plug-In-Entwicklung so wichtig, dass Sie deren Verwendung von Anfang an in Betracht ziehen sollten, auch wenn Sie sie nicht unmittelbar benötigen. Später im Entwicklungszyklus ist es viel schwieriger, Ihrem Plug-In-Projekt Unterstützung für abhängige Assemblys hinzuzufügen.

Wir unterstützen ILMerge nicht. Die Funktion für abhängige Assemblys bietet dieselbe Funktionalität wie ILMerge und mehr.

Verwenden Sie die Funktion für abhängige Assemblys, um andere erforderliche .NET-Assemblys oder -Ressourcen wie etwa lokalisierte Zeichenfolgen mit Ihrer Plug-In-Assembly in einem einzelnen NuGet-Paket einzuschließen, das während der Registrierung auf den Dataverse-Server hochgeladen wird.

Die NuGet-Paketdatei wird in der PluginPackage-Tabelle gespeichert. Der Inhalt des Pakets wird im Dateispeicher und nicht in der SQL-Datenbank gespeichert.

Wenn Sie Ihr NuGet-Paket hochladen, werden alle Assemblys, die Klassen enthalten, die die IPlugin-Schnittstelle implementieren, in der PluginAssembly-Tabelle registriert und dem Plug-In-Paket zugeordnet. Während Sie Ihr Projekt entwickeln und pflegen, aktualisieren Sie weiterhin die PluginPackage-Tabellenzeile. Änderungen an den zugehörigen Plug-In-Assemblys werden auf dem Server verwaltet.

Zur Laufzeit kopiert Dataverse den Inhalt des NuGet-Pakets aus der PluginPackage-Zeile und extrahiert ihn in die Sandbox-Laufzeit. Auf diese Weise sind alle für das Plug-In erforderlichen abhängigen Assemblys verfügbar.

Wichtig

Der Name und die Version des Plug-In-Pakets können nach der Erstellung nicht mehr geändert werden. Der Versuch, dies über einen API-Aufruf zu tun, führt zu einem Fehler.

Signierte Assemblys sind nicht erforderlich

Es ist nicht erforderlich, in Plug-In-Paketen verwendete Plug-In-Assemblys zu signieren.

Wenn Sie einzelne Plug-In-Assemblys ohne die Funktion „Abhängige Assemblys“ registrieren, ist eine Signatur erforderlich, da dadurch ein eindeutiger Name für die Assembly bereitgestellt wird. Bei Plug-In-Assemblys in einem Plug-In-Paket werden die Assemblys jedoch mithilfe eines anderen Mechanismus auf den Sandbox-Server geladen, sodass eine Signierung nicht erforderlich ist.

Wichtig

Wenn Sie Ihre Assemblys signieren, beachten Sie, dass signierte Assemblys keine Ressourcen verwenden können, die in nicht signierten Assemblys enthalten sind. Wenn Sie Ihre Plug-In-Assemblys oder abhängige Assemblys signieren, müssen alle Assemblys, von denen diese Assemblys abhängen, signiert werden.

Wenn signierte Assemblys von nicht signierten Assemblys abhängen, erhalten Sie eine Fehlermeldung wie diese: „Die Datei oder Assembly AssemblyName, Version=Version, Culture=neutral, PublicKeyToken=null oder eine ihrer Abhängigkeiten konnte nicht geladen werden. Es ist eine Assembly mit starkem Namen erforderlich.“

Einschränkungen abhängiger Assemblies

Bei der Verwendung von Plug-In-abhängigen Assemblys gelten die folgenden Einschränkungen:

  • Workflow-Erweiterungen, auch bekannt als benutzerdefinierte Workflow-Aktivitäten, werden nicht unterstützt.
  • Lokale Umgebungen werden nicht unterstützt.
  • Nicht verwalteter Code wird nicht unterstützt. Sie können keine Verweise auf nicht verwaltete Ressourcen einfügen.

Leistungsüberlegungen beim Importieren oder Registrieren eines Plug-In-Pakets

Plug-In-Pakete, die Assemblys mit einer großen Anzahl (Hunderte oder Tausende) von Klassen enthalten, die IPlugin implementieren, benötigen für den Import in Dataverse relativ viel Zeit.

Wir haben Importzeiten von fünfzehn (15) Minuten für tausend Plug-In-Typen festgestellt. Diese Dauer gilt unabhängig davon, ob Sie eine Lösung mithilfe eines API-Aufrufs oder über die Web-Benutzeroberfläche importieren oder das Paket mit dem Plug-In-Registrierungstool registrieren.

Plug-In-Paket erstellen

Sie können Ihre Plug-In-Assembly und alle abhängigen Assemblys zusammen in einem NuGet-Paket platzieren und das Paket dann registrieren und auf den Dataverse-Server hochladen. Wenn Ihr Plug-In-Projekt zur Laufzeit keine abhängigen Assemblys außer denen benötigt, die im Microsoft.CrmSdk.CoreAssemblies-NuGet-Paket enthalten sind, müssen Sie kein Paket erstellen.

Erfahren Sie, wie Sie ein Plug-In-Paket mit PAC CLI erstellen und registrieren und wie Sie ein Plug-In-Paket mit Visual Studio erstellen und registrieren.

Alle Projekte müssen im SDK-Stil sein

Ein Plug-In-Paket darf nur benutzerdefinierte Assemblys enthalten, die aus einer Projektdatei in einem bestimmten Format erstellt wurden, das als SDK-Stil bekannt ist. Die Nichtbeachtung dieser Regel führt zu einem Fehler („Datei kann nicht gefunden werden“), wenn versucht wird, das Paket mit dem Plug-In-Registrierungstool zu registrieren.

Wichtig

Alle MSBuild-Projekte, bei denen die resultierende kompilierte Assembly einem Plug-In-Paket hinzugefügt werden soll, müssen im „SDK-Stil“-Format vorliegen.

Bei einem Projekt im SDK-Stil handelt es sich um ein Projekt, bei dem der Inhalt der CSPROJ-Datei des Projekts die folgende Codezeile enthält: <Project Sdk="Microsoft.NET.Sdk">.

Wenn Sie ein Plug-In-Projekt mit einem unserer Tools erstellen, beispielsweise dem Befehl Power Platform CLI pac plugin init, hat die Plug-In-Projektdatei das richtige Format. Hier sehen Sie ein Beispiel für eine solche Projektdatei.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net462</TargetFramework>
    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
    <FileVersion>1.0.0.0</FileVersion>
    <ProjectTypeGuids>{4C25E9B5-9FA6-436c-8E19-B395D2A65FAF};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
  </PropertyGroup>
  ...
</Project>

Wenn Sie der Visual Studio-Lösung ein weiteres Projekt hinzufügen, beispielsweise ein Klassenbibliotheksprojekt, können Sie mit den folgenden Schritten ein Projekt im SDK-Stil erstellen.

  1. Fügen Sie in Visual Studio das neue Projekt mithilfe einer .NET- oder .NET Standard-Vorlage zu Ihrer Lösung hinzu. Zielen Sie nicht auf .NET Framework.
  2. Bearbeiten Sie die Projektdatei, indem Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen klicken und Projektdatei bearbeiten auswählen, oder öffnen Sie einfach die .csproj-Datei des Projekts in einem separaten Editor.
  3. Sie sollten die Zeile <Project Sdk="Microsoft.NET.Sdk"> in der Projektdatei sehen. Ändern Sie die TargetFramework-Eigenschaft in <TargetFramework>net462</TargetFramework> und speichern Sie die Datei.
  4. Überprüfen Sie Ihre Lösungsbuilds, und schon sind Sie fertig.

Weitere Informationen: .NET-Projekt-SDKs

Verlassen Sie sich nicht auf System.Text.Json

Da das Microsoft.CrmSdk.CoreAssemblies-NuGet-Paket eine Abhängigkeit von System.Text.Json hat, können Sie zur Entwurfszeit auf System.Text.Json-Typen verweisen. Allerdings handelt es sich bei der System.Text.Json.dll-Datei in der Sandbox Runtime möglicherweise nicht um die gleiche Version, auf die Sie in Ihrem Projekt verweisen. Wenn Sie System.Text.Json verwenden müssen, sollten Sie die Funktion für abhängige Assemblys verwenden und sie explizit in Ihr NuGet-Paket einschließen.

Nächster Schritt

Siehe auch

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