Dynamics NAV: Eigene
Erwei­terungen entwickeln

Was sind Erweiterungen?

Die neuen Funktionen der aktuellsten Version des ERP-Systems Dynamics NAV hatten wir bereits für Sie zusammengefasst. Jetzt möchten wir mit Blick auf die Erweiterungen ins Detail gehen und beschreiben in einer Schritt-für-Schritt-Anleitung, die sich vorwiegend an die Dynamics NAV-Entwickelnden richtet, wie sich diese neuen Erweiterungen entwickeln lassen.

Erweiterungen sind vorwiegend kleine Anwendungen/Add-ons, die die Hauptanwendung Dynamics NAV um zusätzliche Funktionen erweitern. Sie können aus dem Dynamics 365-Store  heruntergeladen und ohne große Mühe über die neu integrierte „Erweiterungsverwaltung“ in das bereits existierende ERP-System eingebunden werden.

Anforderungen

Bei der Entwicklung von Erweiterungen sind die folgenden Punkte zu beachten:

• Der Zugriff auf den Server (auf dem die Dynamics NAV-Datenbank läuft) muss gewährleistet sein. Auf diesem muss die „Windows PowerShell“ installiert sein und es ist ein Administratorzugriff erforderlich.

• Sie müssen der Datenbankeigentümer sein und jederzeit Tabellen erstellen, bearbeiten und löschen können.

• Da die Entwicklung einer Erweiterung vollständig in C/SIDE stattfindet, ist eine entsprechende Dynamics NAV-Entwickler-Lizenz erforderlich.

Beispielprojekt

In dieser Schritt-für-Schritt-Anleitung steht nicht die Entwicklung in Dynamics NAV im Vordergrund, sondern die Entwicklung einer Erweiterung. Daher ist das Beispielprojekt keiner realen Entwicklung nachempfunden und soll nur die Schritte aufzeigen, welche zur Erstellung einer Erweiterung notwendig sind.

Allgemeines/Vorbereitung

Die Entwicklung einer Erweiterung geschieht vollständig in Dynamics NAV. Doch vor der Entwicklung müssen alle bestehenden Objekte, welche im Rahmen der neuen Entwicklung verändert werden sollen, als Textdokument exportiert werden. Das Prinzip von Erweiterungen ist nachfolgender Abbildung zu entnehmen:

Die zuvor exportierten Objekte stellen hierbei den Punkt „Base“ und alle Objekte, die Sie neu anlegen bzw. bearbeiten werden, stellen den Punkt „Modified Base“ dar. Diese müssen nach der Entwicklung ebenfalls als Textdokument exportiert werden. Aus diesen beiden Exporten bilden sich später die „Delta-Dateien“, in denen sämtliche Änderungen erfasst werden. Mithilfe der erstellten Dateien, einem Manifest und der „Windows Power­Shell“ wird letztendlich die eigentliche Erweiterung (Dateiformat: *.navx) erzeugt, die bei einer Kundin oder einem Kunden eingespielt werden kann.

Bei dem Eintrag „AMU“ in der oberen Abbildung handelt es sich um die „Windows PowerShell“ bzw. um die von Microsoft mitgelieferte „Dynamics NAV Development Shell“, welche ausschließ­lich mit der „Windows PowerShell“ verwendet werden kann. „AMU“ steht demnach für „Application Merge Utilities“.

Oben aufgeführte Schritte werden im Nachfolgenden genau erläutert.

Für diese Anleitung legen Sie zu Beginn eine Ordnerstruktur an, so wie sie rechts stehend dargestellt wird. Diese Ordnerstruktur ist keine Pflicht, jedoch dient sie der bes­seren Übersicht und dem besseren Verständnis dieser Anleitung. Sie kann an jedem belie­bi­gen Ort angelegt werden. Die Dateien, die während der Entwicklung exportiert bzw. er­stellt werden, können aber auch in jedem beliebigen Pfad abgelegt werden.

Die Entwicklung

Die Entwicklung in dieser Anleitung beschränkt sich darauf, in der Tabelle „Land/Region“ ein neues Feld anzule­gen und auf der Seite „Länder/Regionen“ einzublenden. Wenn das Feld validiert wird, dann soll ein Fenster mit dem neuen Inhalt des Feldes angezeigt werden. Nach der obigen Beschreibung und der Anlage der Ordner­struk­tur müssen nun nachfolgende Objekte in den Ordner „Original“ exportiert werden:

• Tabelle „Land/Region“ (ID 9)
• Seite/Page „Länder/Regionen“ (ID 10)

Im Beispiel nennen Sie die exportierte Datei „Original.txt“.

Nachdem die Objekte exportiert worden sind, kann das neue Feld in der Tabelle „Land/Region“ angelegt werden.

Im Anschluss daran wird es auf der Seite „Länder/Regionen“ eingeblendet.

Mit Dynamics NAV 2016 wurden die sogenannten „Events“ eingeführt. Mit diesen möchte Microsoft erreichen, dass Code, welchen man sonst in die Trigger der Tabellen einfügen würde, in eigene Codeunits ausgelagert werden kann. Erweiterungen unterstützen nur die Verwendung von Events, das Platzieren von Code in Tabellen ist hierbei nicht möglich und würde beim späteren Erstellen der Erweiterung in einem Fehler resultieren.

Demnach wird im Rahmen dieser Entwicklung eine neue Codeunit angelegt, welche wie nachfolgend aufge­baut ist:

Die Entwicklung sollte nun auf der entsprechenden Datenbank lauffähig sein.

Der Upgrade-Code

Eine Erweiterung benötigt immer einen sogenannten Upgrade-Code, welcher sich darum kümmern soll, dass im Falle eines Upgrades der Erweiterung die archivierten Daten wiederhergestellt werden. Microsoft gibt hierbei die zwei Funktionen

• OnNavAppUpgradePerDatabase()
• OnNavAppUpgradePerCompany()

vor, welche sich in einer eigenen Codeunit befinden müssen. Der Name der Codeunit spielt keine Rolle. Le­dig­lich die Funktionen dürfen sich im Namen nicht verändern und müssen beide in der entsprechenden Code­unit vorhanden sein. Der Upgrade-Code soll die verschiedenen Objekte durchlaufen und die Daten wiederherstel­len. Die gespeicherten Daten liegen in neuen System-Tabellen im ID-Bereich 2000000150 bis 2000000166 und werden durch die oben genannten Funktionen und die Funktion „RESTOREARCHIVEDATA“ wiederher­ge­stellt. Hierbei gilt es, die jeweilig verwendeten Objekt-ID´s anzugeben. Der Upgrade-Code durchläuft in diesem Bei­spiel den ID-Bereich 50000 bis 99999.

Nachfolgend ein beispielhafter Upgrade-Code, welcher lauffähig ist:

In oben stehendem Upgrade-Code werden nachfolgende Funktionen angelegt:

• OnNavAppUpgradePerDatabase()
• OnNavAppUpgradePerCompany()
• RestoreFieldsInModifiedTables(FromField : Integer; ToField :Integer)
• RestoreExtensionTables(FromTableID: Integer; ToTableID :Integer)

Die Funktionen werden folgendermaßen befüllt:

OnNavAppUpgradePerDatabase():

leer (muss aber unbedingt vorhanden sein!)

OnNavAppUpgradePerCompany():

RestoreFieldsInModifiedTables(50000,99999);
RestoreExtensionTables(50000,99999);

RestoreFieldsInModifiedTables(FromField : Integer; ToField :Integer):

AllObj.SETRANGE("Object Type",AllObj."Object Type"::Table);

IF AllObj.FINDSET THEN
    REPEAT
        Field.SETRANGE(TableNo,AllObj."Object ID");
        Field.SETRANGE("No.",FromField,ToField);
        IF NOT Field.ISEMPTY THEN
            NAVAPP.RESTOREARCHIVEDATA("Object ID");
    UNTIL AllObj.NEXT = 0;

RestoreExtensionTables(FromTableID : Integer; TOTableID : Integer):

AllObj.SETRANGE("Object Type",AllObj."Object Type"::Table);
AllObj.SETRANGE("Object ID",FromTableID,ToTableID);

IF AllObj.FINDSET THEN
    REPEAT
        NAVAPP.RESTOREARCHIVEDATA("Object ID");
    UNTIL AllObj.NEXT = 0;

Die fertige Codeunit sollte nun wie in der oberen Abbildung aussehen.

Nachdem alle oben genannten Änderungen durchgeführt worden sind, stehen nun insgesamt vier Objekte be­reit, die exportiert werden müssen.

Die Objekte, die oben zu sehen sind, werden nun wie zuvor mit den Original-Objekten exportiert. Jedoch werden die aktuellen Objekte im Ordner „Modified“ abgelegt. In dieser Anleitung trägt die Export-Datei den Namen „Modified.txt“.

Delta-Dateien erstellen

Die „Windows PowerShell“ muss an diesem Punkt noch nicht auf dem Server ausgeführt werden. Es wird an gegebener Stelle darauf hingewiesen, wann die „Windows PowerShell“ des Servers benötigt wird.

Nachdem die „Windows PowerShell“ geöffnet worden ist, müssen nachfolgende Befehle ausgeführt werden:

Set-ExecutionPolicy RemoteSigned
Import-Module 'C:\{…}\100\RoleTailored Client\NavModelTools.ps1'

Die Abfrage, die erscheint, muss mit „Ja“ bestätigt und der Pfad für Ihr System angepasst werden.

Nachdem beide Befehle verarbeitet wurden, öffnet sich die Dynamics NAV Development Shell:

Um die Übersicht über die eingegebenen Befehle zu behalten und um den Erfolg dieser Anleitung zu gewährleisten, navigieren Sie mit der „Windows PowerShell“ in das übergeordnete Verzeichnis unserer Ordnerstruktur. Nun erstellen Sie mit nachfolgendem Befehl die Delta-Dateien:

Compare-NAVApplicationObject -DeltaPath Delta\ –ModifiedPath Modified\Modified.txt -OriginalPath Original\Original.txt

Die Ausgabe der „Windows PowerShell“ verrät Ihnen, dass wie gewünscht zwei neue Objekte vorhanden sind und zwei Objekte verändert wurden. In dem von uns erstellten Ordner „Delta“ befinden sich nun vier Dateien:

Die IDs können und dürfen sich bei den Codeunits unterscheiden.

Manifest erstellen

Das Manifest gibt Aufschluss über den Herausgebenden der Erweiterung und beinhaltet weiterhin noch einige In­for­mationen zu der Erweiterung selbst (Bsp.: „Versions-Nr.“, „Beschreibung“ etc.). Das Manifest wird eben­falls mittels „Windows PowerShell“ erstellt. Vom Ausgangspunkt des oberen Punktes muss nun nachfolgender Be­fehl abgesetzt werden:

ew-NAVAppManifestFile -Manifest (New-NAVAppManifest -Name „Land Region Erweiterung“ -Publisher "AGOLUTION GmbH" -Description "Neues Feld Kommentar zu Länder/Regionen" -Prerequisites CodeUnit=1 -Version 1.0.0.0) -Path "LandRegionErw.xml"

Das Resultat ist eine neue Manifest-Datei im Wurzelverzeichnis der Erweiterung. In diesem Fall heißt die Datei „LandRegionErw.xml“.

Diese Informationen sind in dem erstellten Manifest enthalten:

• Name: „Land Region Erweiterung“
• Herausgeber: „AGOLUTION GmbH“
• Beschreibung: „Neues Feld Kommentar zu Länder/Regionen“
• Version: 1.0.0.0

Extension-Package erstellen

Da nun alle erforderlichen Teile der Erweiterung vorhanden sind, ist es möglich, das „Extension-Package“ zu erstellen. Hierbei handelt es sich um diejenige Datei (*.navx), die der Kundin oder dem Kunden zur Verfügung gestellt wird.

Um diese Datei zu erstellen, muss mit nachfolgendem Befehl das Package erstellt werden:

New-NAVAppPackage -Manifest (Get-NAVAppManifest -Path LandRegionErw.xml) -Path LandRegionErw.Navx –SourcePath Delta\

Das Ergebnis ist eine neue Datei mit dem Namen „LandRegionErw.Navx“, welche sich im Stammverzeichnis der Erweiterung befindet.

Erweiterung veröffentlichen

Um eine Erweiterung aktiv zu nutzen, muss diese im Vorfeld zwei Schritte durchlaufen. Als Erstes muss die Er­weiterung „gepublished“ werden. Dies teilt dem Server mit, dass eine neue Erweiterung vorhanden ist und implementiert den nötigen Code in die Datenbank.

Um dies zu erreichen, verbinden Sie sich per Remote-Desktop oder Ähnlichem zum Server und öffnen auch hier die „Windows PowerShell“ als Administrator. Nun müssen erneut obige Schritte durchlaufen werden, um die Dynamics NAV Development Shell zu öffnen. Die Punkte hier noch einmal zusammengefasst:

Set-ExecutionPolicy RemoteSigned`
Import-Module 'C:\{…}\100\RoleTailored Client\NavModelTools.ps1'

Nun gilt es, das zuvor erstellte Extension-Package auf den Server zu kopieren. In diesem Fall wurde das Extension-Package auf den Desktop kopiert und per „Windows PowerShell“ direkt auf den Desktop navigiert.

Nachfolgender Befehl veröffentlicht die Erweiterung:

Publish-NAVApp -ServerInstance {Serverinstanz} -Path LandRegionErw.Navx

Der Parameter „ServerInstance“ muss mit dem korrekten Instanznamen Ihrer Datenbank übereinstimmen, auf der Sie die Erweiterung veröffentlichen möchten.

Durch den zusätzlichen Parameter -SkipVerification kann die Überprüfung auf Gültigkeit des Zertifikats der Erweiterung übersprungen werden. Dies ist immer der Fall, wenn die Erweiterung sich noch in der Entwicklung befindet. Der Code der Erweiterung wird im Nachgang (bevor er von Microsoft in den Store aufgenommen wird) durch Microsoft signiert.

Nachfolgender Befehl listet alle Erweiterungen der aktuell gewählten Serverinstanz auf. So können Sie kontrol­lieren, ob das Beispiel tatsächlich veröffentlicht worden ist:

Get-NAVAppInfo –ServerInstance {Serverinstanz}

Erweiterung installieren/deinstallieren

Der zweite Schritt, um eine Erweiterung aktiv verwenden zu können, ist die Installation. Dies ist für jeden Benutzer (mit der entsprechenden Berechtigung) über die „Erweiterungsverwaltung“ innerhalb von Dynamics NAV möglich. Zu finden ist diese unter:

Abteilungen > Verwaltung > IT-Verwaltung > Erweiterungen > Erweiterungsverwaltung

Hier lässt sich nun die neu aufgeführte Erweiterung installieren:

Mithilfe der Schaltfläche „Deinstallieren“ lässt diese sich ebenfalls im laufenden Betrieb wieder entfernen. Die Erweiterung verbleibt jedoch in der Liste der „Erweiterungsverwaltung“. Sie kann lediglich nicht mehr aktiv ge­nutzt werden. Um die Erweiterung gänzlich zu entfernen, muss in der „Windows PowerShell“ nachfolgender Befehl ausgeführt werden:

Unpublish-NAVApp –Name „Land Region Erweiterung“ -ServerInstance {Serverinstanz}

Test

Nachdem die Erweiterung erfolgreich installiert wurde, ist auf der Seite „Länder/Regionen“ (ID 10) das neue Feld „Kommentar“ eingeblendet, und auch die erstellte Codeunit wird erfolgreich mit Validierung des Feldes ausgeführt: