Was sind Erweiterungen?

In unserem vorherigen Blog-Beitrag What‘s New in Dynamics NAV 2017 hat mein Kollege Martin bereits die neuen Funktionen der aktuellsten Version des ERP-Systems Dynamics NAV zusammengefasst. Jetzt möchten wir – was die Erweiterungen angeht – ins Detail gehen und beschreiben in einer Schritt-fĂŒr-Schritt-Anleitung, die sich vorwiegend an die Dynamics NAV-Entwickler richtet, wie sich diese neuen Erweiterungen entwickeln lassen.

Erweiterungen sind vorwiegend kleine Anwendungen/kleine Addons, die die Hauptanwendung Dynamics NAV um weitere Funktionen erweitern. Sie können aus dem Dynamics365-Store heruntergeladen und ohne große MĂŒhe ĂŒber die neu integrierte „Erweiterungsverwaltung“ in das bereits existierende ERP-System eingebunden werden.

Anforderungen

FĂŒr die Entwicklung von Erweiterungen sind die folgenden Dinge 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 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 liegt 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 wir 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. Mit Hilfe der erstellten Dateien, einem Manifest und der „Windows Power­Shell“ wird letztendlich die eigentlich Erweiterung (Dateiformat: *.navx) erzeugt, die bei 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 wir zu Beginn eine Ordnerstruktur, wie sie rechts stehend dargestellt wird, an. Diese Ordnerstruktur ist keine Pflicht, jedoch dient sie zur bes­seren Übersicht und zum besseren VerstĂ€ndnis dieser Anleitung. Sie kann an jedem belie­bi­gen Ort angelegt werden. Die wĂ€hrend der Entwicklung exportierten bzw. er­stellten Dateien können aber auch in jedem beliebigen Pfad abgelegt werden.

Die Entwicklung

Die Entwicklung 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)

In unserem Beispiel benennen wir die exportierte Datei mit „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 wiedergestellt 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 der 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 wie nachfolgend befĂŒllt:

OnNavAppUpgradePerDatabase():

leer (muss aber unbedingt vorhanden sein!)

OnNavAppUpgradePerCompany():

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

RestoreFieldsInModifiedTables(FromField : Integer; ToField :Integer):

Name Type Subtype
AllObj Record AllObj
Field Record Field

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

Name Type Subtype
AllObj Record AllObj

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.

Oben zu sehende Objekte werden nun wie zuvor mit den Original-Objekten exportiert. Jedoch werden die aktuellen Objekte in den 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 erscheinende Abfrage mit „Ja“ bestĂ€tigen und den Pfad fĂŒr Ihr System anpassen.

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 wir mit der „Windows PowerShell“ in das ĂŒbergeordnete Verzeichnis unserer Ordnerstruktur. Nun erstellen wir 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 uns, 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 Herausgeber der Erweiterung und beinhaltet weiterhin noch einige In­for­mationen zu der Erweiterung selber (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:

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

Nun, da 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 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 wir uns 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 unser 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 das Installieren der Selbigen. 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:

Mit Hilfe 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 worden ist, 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:

Schlagwörter

  • Anleitung
  • Dynamics NAV
  • Erweiterungen
  • NAV 2016
  • NAV 2017
  • Tutorial