Umbraco Code Camp

Original von Per Ploug Hansen

Unser erster Tag der Entwicklung wird sich mit der Vorbereitung unseres Projekts für den agilen Entwicklungsprozess befassen. Da wir uns für die nächsten 24 Tage nicht ständig mit dem Zippen von Dateien, bereitstellen von Manifest-Dateien oder dem manuellen Durchführen der täglichen Builds herumärgern wollen, besteht unsere erste Projektaufgabe darin ein professionelle Infrastruktur einzurichten.

Diese Infrastruktur soll folgende Anforderungen erfüllen:

1. eine teamfähige Quelltext-Verwaltung,
2. ein Build-Server,
3. eine saubere Projektstruktur, die alle erforderlichen Dateien beinhaltet,
4. ein Package-Manifest für die Installation des Packages in Umbraco,
5. ein NAnt Skript, welches das Package zusammenstellt, das Manifest automatisiert, zippt usw.,
6. einige zusätzliche Werkzeuge, um die Dateien an das Package zu übergeben.

Quelltext-Verwaltung

Das alte Package Blog 4 Umbraco existiert bereits auf Codeplex, daher belassen wir es dort und modifizieren einfach das bestehende Projekt, so dass es unseren Anforderungen entspricht. Der Quelltext und die Problemverfolgung (Source & Issue-Tracker) finden sich unter:

http://www.codeplex.com/blog4umbraco

Build-Server

Wir verwenden bei Umbraco bereits TeamCity für unsere Build-Prozesse zu Contour, Courier und Concierge. Es ist einfach einzurichten, hat eine phantastische Bedienoberfläche und arbeitet perfekt mit NAnt und Subversion zusammen - es ist wirklich sehr zu empfehlen. Da es bereits ausreichende Dokumentationen zu TeamCity gibt, will ich hier nicht mehr dazu schreiben, aber es ist einfach phantastisch. Der Build-Prozess funktioniert einfach und man muss sich um nichts irgendwelche Sorgen machen. Da wir NAnt für den Code-Build verwenden, können wir den Build-Prozess auch lokal testen, indem wir einfach die NAnt-Skripte auf dem lokalen Entwicklungsrechner ausführen.

TeamCity ist hier zu finden: http://www.jetbrains.com/teamcity

Projektstruktur

Wir packen alles in unser Visual Studio Projekt um sicherzugehen, dass es jederzeit und überall erstellt werden kann, daher wird es auch unsere NAnt-Skripte und Package-Manifest Dateien enthalten. Diese können damit auch einfach bearbeitet werden. Für die eigentlichen Projektdateien haben wir folgende einfache Struktur eingerichtet:

• Solution items
  enthält die NAnt-Skripte, die Package-Manifests sowie die Hilfsprogramme und zusätzlichen Werkzeuge
• Css
  alle Stilvorlagen für die Darstellung
• EventHandlers
  Klassen, die in das Umbraco Event-Modell eingreifen
• Images
  Bilder für die Darstellung
• Library
  die XSLT-Erweiterungen für das Blog
• Scripts
  alle JavaScript-Dateien
• Templates
  die Dokumentvorlagen (Master template files)
• UserControls
  die Benutzersteuerelemente für Makros
• Xslt
  die XSLT-Dateien für die Makros

Damit ist dann alles erforderliche in der Quelltextverwaltung und unser Build-Server kann es jede Nacht abholen, um daraus ein hübsches Package und ein Hotfix zusammenzupacken.

Package-Manifest

Das Package-Manifest ist der Teil des Projekts, der Umbraco anweist, wie die verschiedenen Elemente des Pakets installiert werden sollen. Es enthält Verweise zu allen Dateien, Dokumentvorlagen, Makros, CSS-Dateien usw. Normalerweise werden Packages einfach im Umbraco-Backoffice erzeugt, dort steht im Entwickler-Bereich unter Packages > Erstellte Packages der Umbraco-Packager zur Verfügung. Wir wollen jedoch jede Nacht eine aktuelle Package-Datei erstellt wissen und wer will extra dafür schon jede Nacht aufstehen? Statt dessen erzeugen wir einmalig ein sehr einfaches Package mit dem Umbraco-Packager. Dieses Package enthält alle Dokumenttypen, Dokumentvorlagen und weitere Elemente, die voraussichtlich nicht verändert werden müssen und natürlich auch ein passendes Package-Manifest. Dieses Manifest wird nun bei jedem Build automatisch aktualisiert, um es auf dem neuesten Stand zu halten.

Für dieses Projekt installieren wir einfach das bisherige Blog-Package und erzeugen danach ein neues Package mit allen Dokumentvorlagen, Stilvorlagen, Makros usw. Das enthaltene Package-Manifest fügen wir dann mit in die Visual Studio Projektmappe ein.

NAnt Skripte

NAnt ist ein für .NET geschriebenes Werkzeug zum automatisierten Erzeugen von Programmen aus Quelltext (Wikipedia). Allerdings kann es weitaus mehr, als nur den Quelltext übersetzen. In diesem Projekt richten wir NAnt so ein, dass es (und nicht wir) folgende Aufgaben ausführt:

1. Programmerzeugung aus dem Quelltext,
2. verschieben von Dateien aus dem Projekt- in den Package-Ordner,
3. verändern des Package-Manifests (XML) mit der Liste der aktuellen Dateien,
4. einfügen der Formatierungen aus den Dokumentvorlagen in das Package-Manifest (XML),
5. zufügen der Stilvorlagen zum Package-Manifest,
6. aktualisieren der Versionsnummer,
7. Komprimieren der Dateien zu einem kompletten Package als Zip-Datei,
8. Komprimieren der geänderten Dateien zu einem Hotfix, um eine bestehende Installation zu aktualisieren,
9. veröffentlichen der Dateien auf nightly.umbraco.org,
10. alles aufräumen,
11. (Kaffee kochen und die Wäsche machen).

Per ist geübt mit NAnt Skripten und er behauptet, dass ihn das Konfigurieren eines entsprechenden NAnt Skripts für die angegebenen Aufgaben höchstens 40 Minuten kostet (Pkt. 11 ausgenommen :).

Soweit so gut, doch wie müssen wir jetzt genau vorgehen, um uns auf so wunderbare Weise die Arbeit abnehmen zu lassen? Nun zunächst sollten wir uns den Quelltext von Codeplex herunterladen und uns speziell die Datei nant.build ansehen. Die darin verborgenen Geheimnisse werden in den nachfolgenden Abschnitten gelüftet.

Um NAnt für uns arbeiten zu lassen, muss es natürlich auf dem Entwicklungsrechner installiert werden. Weitere Informationen zum Herunterladen und der Installation finden sich unter: http://nant.sourceforge.net/release/0.85/help/introduction/installation.html

Um ein NAnt-Skript auszuführen öffnen wir einfach die Eingabeaufforderung (cmd.exe), wechseln zum lokalen Projektverzeichnis von blog4umbraco (mit cd) und geben hier den Befehl nant ein und starten ihn mit der Eingabetaste. NAnt wird das Skript im aktuellen Verzeichnis finden und ausführen.

Struktur eines NAnt-Skripts

Das Skript ist in verschiedene Ziele (engl. Target) unterteilt (<target> elements). Diese Ziele sind:

• Compile
• Movefiles
• Manifest
• Zip
• Publish

Diese einzelnen Ziele behandeln jeweils einen unterschiedlichen Teil des Ablaufs. Wir können alle Ziele ausführen lassen, wenn wir das Kommando nant aufrufen. Wir können aber auch nur bestimmte Teile ausführen, indem wir das Kommando nant mit dem Zielnamen als Parameter aufrufen (z.B. "nant manifest"). Da jedes Ziel von anderen Zielen abhängig sein kann (z.B. sollen Dateien vor dem Verschieben zunächst erzeugt worden sein) können entsprechende Abhängigkeiten definiert werden. Dadurch wird sichergestellt, dass alles in der richtigen Reihenfolge ausgeführt wird.

Das Projekt generieren mit NAnt

Die erste Aufgabe die wir erledigen müssen ist natürlich den Quelltext zu compilieren. Wir verwenden dazu das Programm msbuild.exe, welches Bestandteil des .NET Frameworks ist. Msbuild ist ziemlich pingelig beim Erzeugen einer Visual Studio Projektmappe und erfordert, dass keine Dateien fehlen, keine falschen Seitendeklarationen existieren usw.

Damit NAnt für uns die Projekterstellung übernimmt, rufen wir das Programm msbuild.exe direkt auf und übergeben ihm alle zur Erstellung der Projektmappe erforderlichen Parameter:

<exec program="${msbuild.app}" basedir="${root.dir}">
      <arg value="UmLaut.Umb.Blog.sln" />
      <arg value="/p:Configuration=Debug" />
      <arg value="/p:Platform=&quot;Any CPU&quot;" />
</exec>

Dokumentvorlagen ins Package-Manifest einfügen

Wir halten unsere Dokumentvorlagen im Projekt als Dateien vor, aber um sie zu installieren müssen wir die enthaltenen Formatierungen in das Package-Manifest einfügen. Diese Aufgaben werden mit Hilfe der NAnt-Aufträge loadfile und xmlpoke ausgeführt:

<loadfile file="${core.dir}\templates\Blog.master" property="blog.master" />
<xmlpoke file="${zip.dir}\package.xml" xpath="/umbPackage/Templates/Template [Alias = 'Blog']/Design" value="&lt;![CDATA[${blog.master}]]&gt;" />

Wir laden dazu die Dokumentvorlagendatei in eine Property (hier ${blog.master} ) und fügen dann ihren Inhalt als XML-Knoten in das Package-Manifest ein. Der XPath-Ausdruck gibt hier genau vor, an welcher Stelle der Wert von ${blog.master} in die XML-Struktur des Manifests einzufügen ist. Diese Technik benutzen wir nun sowohl für alle weiteren Dokumentvorlagen als auch für die Stilvorlagen (die CSS-Dateien).

Einsammeln und Komprimieren der Package-Dateien

für unser Package müssen wir alle Dateien zusammenfassen, die Umbraco für die Installation benötigt. Weiterhin müssen wir Umbraco mitteilen, an welcher Stelle der Ordnerstruktur die Dateien einzufügen sind. Zu diesem Zweck erzeugen wir einen temporären Ordner und kopieren dorthin alle erforderlichen Dateien. Wir platzieren sie auch gleich in der später gewünschten Ordnerstruktur. Dazu verwenden wir einfache NAnt Befehle zum kopieren von Dateien und zum Anlegen von neuen Ordnern:

    <!-- Images -->
    <mkdir dir="${package.dir}\images" />
    <copy todir="${package.dir}\images" includeemptydirs="true" flatten="false" failonerror="false" overwrite="true">
      <fileset basedir="${core.dir}\images">
        <include name="*.*" />
      </fileset>
    </copy>

    <!-- Usercontrols -->
    <mkdir dir="${package.dir}\usercontrols\${dist.name}" />
    <copy todir="${package.dir}\usercontrols\${dist.name}" includeemptydirs="true" flatten="false" failonerror="false" overwrite="true">
      <fileset basedir="${core.dir}\usercontrols">
        <include name="*.ascx" />
      </fileset>
    </copy>

Wenn alle Dateien im Zielordner untergebracht sind führen wir ein kleines Hilfsprogramm aus, welches alle verfügbaren Dateien in der XML-Struktur des Package-Manifests registriert und sie anschließend in den Ordner kopiert, wo sie später zur Package Zip-Datei komprimiert werden. Das aktuelle Package-Format erfordert, dass alle Dateien im Stamm des Zip-Ordners angeordnet werden. Damit sich dabei nicht gleichnamige Dateien aus verschiedenen Ordnern gegenseitig überschreiben, werden alle Dateinamen durch eine GUID (Wikipedia) ersetzt. Das Hilfsprogramm  AddFilesTopackages.exe kümmert sich ebenfalls um all diese Details (das Tool ist natürlich auch Bestandteil des Blog 4 Umbraco Projekts).

    <!-- here we will append files in the package directory to the package file-->
    <!-- arguments: package.xml manifest, folder with files in correct structure, folder to send to for zipping-->
    <exec program="${root.dir}\AddFilesToPackage.exe">
      <arg value="${package.dir}\package.xml" />
      <arg value="${package.dir}" />
      <arg value="${zip.dir}" />
    </exec>

Abschließend werden wir alles in zwei Zip-Dateien komprimieren. Die eine Datei ist das installierbare Umbraco-Package mit allen Dateien, die im Stammverzeichnis ${zip.dir} verfügbar sind, das andere unser Hotfix mit den Dateien aus ${package.dir}. In letzerem besitzen die Package-Dateien bereits den korrekten Dateinamen und sind in der Ordnerstruktur korrekt angeordnet. Damit kann es einfach mittels xcopy in eine bestehende Package-Installation kopiert werden.

    <!-- Zip everything -->
    <zip zipfile="${root.dir}\package.zip" includeemptydirs="true" >
      <fileset basedir="${zip.dir}">
        <include name="*" />
        <include name="**/*" />
      </fileset>
    </zip>

    <!-- Zip hotfix -->
    <zip zipfile="${root.dir}\hotfix.zip" includeemptydirs="true" >
      <fileset basedir="${package.dir}">
        <include name="*" />
        <include name="**/*" />
        <exclude name="package.xml" />
      </fileset>
    </zip>

Dies waren alles kleine Skript-Schnipsel des NAnt-Skripts. Es ist sehr zu empfehlen, sich die komplette Datei nant.build anzusehen und weiter zu erforschen. NAnt ist ein phantastisches Werkzeug um praktisch alles zu automatisieren, und für die Durchführung von langweiligen Aufgaben wie der Aktualisierung eines Package-Manifests ist es eine wertvolle Zeiteinsparung.

Weitere Informationen und nächste Schritte

Mit NAnt, Codeplex und TeamCity an Ort und Stelle können wir nun beginnen unsere Projekterweiterungen durchzuführen. Wir brauchen uns damit keine weiteren Gedanken über den Zeitaufwand beim Erstellen und Freigeben des Packages zu machen und können damit die folgenden Schritte viel schneller und unbeschwerter ausführen.

Die nächtlichen Builds werden als Package und auch als Hotfix verfügbar sein unter: http://nightly.umbraco.org/Blog4Umbraco/

Der Quelltext findet sich auf Codeplex, wo auch Hinweise, Fehlermeldungen und Quelltextausschnitte eingegeben werden können: http://blog4umbraco.codeplex

 

Ende des ersten Kalendertürchens für den Umbraco-Weihnachtskalender! Per verspricht an dieser Stelle feierlich, dass die nächsten Türchen nicht mit NAnt-Skripten und XML vollgestopft sein werden.