Neuerungen in NDO 3.0

In der Vergangenheit hatten wir mit NDO ein paar schwierige Versionierungsprobleme, die wir mit NDO 3.0 behoben haben. Um diese Probleme zu lösen, waren ein paar Änderungen notwendig, nach denen alte Projekte nicht mehr kompilieren. Wir beschreiben hier, welcher Art die Probleme waren und wie Sie NDO 2.1-Anwendungen wieder zum Kompilieren bringen.

Versionierungsprobleme mit NDO 2.1 und früher

NDO war früher ein Visual Studio Add-in. Das Add-in war eine Dll, die im Installationsverzeichnis von NDO lag, aber in die AppDomain von Visual Studio geladen wurde. Das bedeutet, dass das Add-in keine privaten Dlls nutzen konnte. Da das Add-in jedoch die NDO-Dlls benötigte, wurden die NDO-Dlls in den GAC installiert. Diese Dlls im GAC wurden von folgenden Applikationen geladen:

  • Vom Add-in
  • Vom Enhancer als Teil des Builds
  • Von der Applikation, die mit Hilfe von NDO entwickelt wurde

Wenn eine kleinere Veränderung an NDO vorgenommen wurde, war es also nicht damit getan, die Versionnummer von NDO zum Beispiel auf 2.1.0.300 zu setzen. Es wäre nötig gewesen, NDO komplett zu deinstallieren und eine neue Version zu installieren. Dadurch wären aber ggf. ältere Projekte zu einem NDO-Update gezwungen gewesen.

Dieses Problem wollten wir lösen. Darüber hinaus entstand ein weiteres Problem, nämlich, dass Visual Studio-Add-ins ab der Version 2015 nicht mehr unterstützt werden. Wir mussten das Add-in als Visual Studio-Extension umschreiben.

Die NDO-Build Task

Für den Enhancer stand ab ca. Mitte 2013 eine Build Task zur Verfügung. Diese Build Task und die zugehörige Targets-Datei (NDOEnhancer.Targets) lagen im NDO-Installationsverzeichnis. Das Verzeichnis wurde bei der Installation in die Registry eingetragen. Die Projektdatei (.csproj) wurde bei der Aktivierung von NDO so abgeändert, dass das NDO-Installationsverzeichnis als Property aus der Registry ausgelesen wurde und mit Hilfe des Propertys der NDOEnhancer als Target inkludiert wurde. Dazu wurden folgende Zeilen in die Projekte eingefügt:

<Target Name="AfterBuild">
   <NDOEnhancer NdoProjectFile="$(ProjectName).ndoproj" NdoPlatformTarget="$(Platform)" />
</Target>
<PropertyGroup>
   <NDOInstallPath Condition=" '$(NDOInstallPath)' == ''">$(Registry:HKEY_LOCAL_MACHINE\SOFTWARE\NDO@InstallDir)</NDOInstallPath>
</PropertyGroup>
<Import Project="$(NDOInstallPath)\NDOEnhancer.Targets" />

NDO als Visual Studio Extension (vsix)

Weil Visual Studio-Add-ins ab der Version 2015 nicht mehr unterstützt werden, wurde das Add-in als Extension umgeschrieben. Das hat Vorteile:

  • Eine Extension kann nämlich ihre eigenen privaten Dlls verwenden.
  • Extensions funktionieren auch mit der Community Edition von Visual Studio.

Wir haben die Visual Studio Extension so umgeschrieben, dass die Abhängigkeiten von der NDO.dll extrem minimiert wurden. Das bedeutet, dass die Extension auch auf längere Sicht mit einer älteren NDO-Version funktionieren wird. Sie benötigt also nicht die neueste NDO.dll. Sie bringt ihre eigene, private NDO.dll mit. Da NDO nicht mehr im GAC liegt, ist es möglich, dass die Extension eine andere Dll benutzt, wie die Applikation, die mit NDO entwickelt wird.

Wird eine neue Applikation mit der Extension konfiguriert, so wird die neueste NDO.dll von Nuget installiert.

NDO via Nuget

Sie können mit install-package ndo.dll NDO von Nuget.org installieren. Es wird jedoch empfohlen, NDO mit Hilfe der Extension zu installieren, weil dann die .ndoproj-Datei korrekt initialisiert wird und mit Hilfe der Benutzeroberfläche angepasst werden kann.

Sobald NDO in einer Applikation installiert ist, kann mit

update-package ndo.dll

jederzeit auf die neueste Version von NDO upgedatet werden.

Sobald wir Änderungen an NDO vornehmen, entsteht ein neues Tag im Repository und die geänderte Dll wird als neue Version auf Nuget hochgeladen.

Update auf NDO 3.0

Sofern Sie NDO bereits als Visual Studio Package installiert haben, empfehlen wir die Deinstallation über Tools / Extensions and Updates…

Wir empfehlen außerdem die Deinstallation von NDO 2.1.

Achtung, wenn Sie alte Projekte mit NDO 2.1. warten müssen:

Bevor Sie NDO deinstallieren, kopieren Sie das Installationsverzeichnis an einen sicheren Ort.
Folgende Dateien werden daraus benötigt:
  • EnhancerX86Stub.exe
  • NDOEnhancer.BuildTask.dll
  • NDOEnhancer.exe
  • NDOEnhancer.pdb
  • NDOEnhancer.Targets
  • NDOInterfaces.dll
  • Das Provider-Verzeichnis, wenn Sie mit anderen Datenbanken als Sql Server und Access arbeiten.
Die AppDomain des Enhancers läuft im Executable-Verzeichnis Ihrer Applikation. Dort müssen die NDO.dll und NDOInterfaces.dll liegen, die von Enhancer gebraucht werden.
Dann restaurieren Sie den NDO-Registry-Eintrag:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\NDO]
"InstallDir"="C:\\Program Files (x86)\\NDO 2.1 Dev Edition\\"
In der .ndoproj-Datei muss bei den Options
<UseMsBuild>True</UseMsBuild>
stehen.

Wir empfehlen statt dessen das Update auf NDO 3.0.

Die Version 3.0 ist von der Datenzugriffsschicht her identisch mit NDO 2.1.

Entfernen Sie die Referenzen auf NDO.dll und NDOInterfaces.dll.

Wenn NDO als Build Target in Ihre Projektdatei eingebunden ist (in Versionen ab ca. Mitte 2013), dann entfernen Sie mit einem Editor die NDO-Target-Zeilen aus dem Projekt (siehe „Die NDO-Build Task“) und benennen die .ndoproj-Datei um, so dass NDO sie nicht mehr finden kann. Dann aktivieren Sie mit der neuen VS-Extension NDO. Die dabei neu erzeugte .ndoproj-Datei können Sie löschen und die alte Datei durch Umbenennen wieder reaktivieren. Das neue Build Target von NDO 3.0 sollte nun Bestandteil der .csproj-Datei sein.

Achten Sie darauf, dass in der .ndoproj-Datei unter Options die Zeile

<UseMsBuild>True</UseMsBuild>

steht.

Breaking Changes von NDO 3.0

Der Namespace NDO.Mapping wurde überarbeitet. Alle Aufzählungen sind jetzt als IEnumerable<T> implementiert. Die alten APIs haben untypisierte ArrayList-Objekte zurückgegeben, die Sie direkt indizieren konnten. Die neuen APIs geben immer IEnumerable<T> zurück.

Die häufigste Änderung, die beim Update auf 3.0 auftritt, ist wie folgt:

Statt:

Connection conn = (Connection) pm.NDOMapping.Connections[0];

heißt es nun:

Connection conn = pm.NDOMapping.Connections.FirstOrDefault();

Für FirstOrDefault benötigen Sie den Namespace System.Linq.

Wenn Sie das Mapping-API in Ihrem Projekt nicht benutzt haben, genügt es, nach dem Update auf NDO 3.0 neu zu kompilieren.

Der NDOEnhancer in der Version 3.0

Der Enhancer ist abhängig von der NDO-Dll in der jeweiligen Version. Daher kommt mit der NDO.dll auch immer der Enhancer in einem eigenen Verzeichnis mit. Nuget-Packages verfügen über ein Build-Verzeichnis, in dem der Enhancer zusammen mit der Datei NDOEnhancer.Targets liegt. Diese Datei wird in der .csproj-Datei inkludiert. Das NDOEnhancer-Target ruft dann den Enhancer auf. Auf diese Weise hat jedes Projekt seine isolierte NDO-Umgebung.