Tutorial: Eigene Module und Extensions entwickeln. version: 0.1 Author: Anja Beuth

Transkript

1 Tutorial: Eigene Module und Extensions entwickeln version: 0.1 Author: Anja Beuth

2 Table of contents Notwendigkeit prüfen... Ein Projekt in Visual Studio einrichten... Aufräumen... Web.config austauschen... Verweise hinzufügen... Projekt konfigurieren... Grundsätzliche Vorgehensweise... Modul erstellen... Methode»Dispose()«... Setter/Getter»Extensions«... Methode»Configure()«... Extension erstellen... Methoden definieren... Modul einbinden... Datei portieren... web.config

3 Requirements Der Entwickler benötigt für dieses Tutorial den Zugriff auf das Installationsverzeichnis der onion.net Render Engine. Für die lokale Entwicklung sollte eine aktuelle Distribution auf dem Entwicklerrechner zur Verfügung stehen. Weiterhin sind Kenntnisse in der Programmierung mit C# und im Umgang mit einer geeigneten Entwicklungsumgebung wie z.b. Visual Studio von Vorteil. C# Tutorials (MSDN) Galileo Open Book "C#" von Eric Gunnerson Visual Studio Description Dieses Tutorial beschreibt die Entwicklung und Verwendung eines eigenen Moduls mit einer Extension zur projektspezifischen Erweiterung des XSLT-Standardsprachumfangs mit der Entwicklungsumgebung "Microsoft Visual Studio 2010". Signs and symbols Boxes marked with an arrow symbol and a green border contains instruction of what to do next. This kind of boxes contains tips and tricks. Source code is shown in blue boxes. 1

4 1 Notwendigkeit prüfen 1 Notwendigkeit prüfen Bevor eine Erweiterung in C# programmiert wird, sollte geprüft werden, ob dies wirklich notwendig ist. Die Erweiterbarkeit ist zwar kein Problem, jedoch zeigt die Erfahrung, dass XSL-Transformationen, die direkt über den Editor geändert werden können, wesentlich besser wartbar sind. Spätere Erweiterungen oder Bugfixes von C#-Extensions erfordern immer einen Entwickler mit entsprechenden Kenntnissen. Darüber hinaus muss zum Einspielen der Neuerungen ein Deployment der entsprechenden Dateien auf das Produktivsystem stattfinden. Wenn auch Änderungen an der web.config notwendig sind, hat dies also auch den Neustart der Webanwendung zur Folge. Die Aktualisierung ist also aufwändiger als das Ausleihen, Bearbeiten und Zurückgeben einer Methode im onion.net Editor. Nur wenn die zu implementierende Funktion nicht oder nur mit großem Aufwand mit XSLT umsetzbar ist, lohnt sich der Einsatz einer Extension. Vor der Eigentwicklung sollte aber überprüft werden, ob nicht bereits eine Erweiterung zur Verfügung steht, die die Anforderungen erfüllt oder die Umsetzung mit XSLT auf einfache Weise ermöglicht. Eine Übersicht über die bereits vorhandenden Erweiterungen findet sich auf der Seite Extensions (Referenz). 2 Ein Projekt in Visual Studio einrichten Für die onion.net Entwicklung sollte zunächst ein entsprechendes Visual Studio Projekt eingerichtet werden. Dieses sollte eine "ASP.NET Webanwendung" sein. Da Extensions für die onion.net Renderengine entwickelt werden, bietet sich für den Projektnamen die Kombination "Projektname.Renderengine" an. Auf diese Weise können der Projektmappe später noch andere Projekte hinzugefügt werden, die beispielsweise den Editor erweitern oder einen WebService oder WindowsService für das Projekt beinhalten. 2

5 2 Ein Projekt in Visual Studio einrichten Description: Dialog "Neues Projekt" im Visual Studio zum Erstellen einer "ASP.NET Webanwendung" namens "Projektname.Renderengine" 2.1 Aufräumen Nach dem Anlegen erzeugt Visual Studio automatisch eine Reihe von Dateien, die in einem typischen Webprojekt benötigt werden. Für die Entwicklung für onion.net werden die meisten dieser Dateien nicht benötigt. Sie können die Dateien zwar als Vorlagen weiter im Projekt behalten. Wir empfehlen aber, die nicht benötigten Elemente zu löschen. Dies macht das Projekt viel übersichtlicher und auch besser wartbar. Es werden nur die folgenden Elemente benötigt: Properties, Verweise, Global.asax, Web.config. Die folgende Grafik zeigt den Projektmappen-Explorer vor und nach dem Aufräumen. 3

6 2 Ein Projekt in Visual Studio einrichten Description: Die Projektmappe vor und nach dem Aufräumen 2.2 Web.config austauschen Es bietet sich an, in der lokalen Entwicklungsumgebung eine Version der tatsächlichen web.config der Renderengine zu haben. Diese muss bei der Entwicklung für onion.net gegebenenfalls angepasst werden. Bei der Aktualisierung kann sie dann zusammen mit der Erweiterungs-Assembly in die eigentliche onion.net-anwendung kopiert werden. Darüber hinaus ist es ja auch möglich, in der lokalen Entwicklungsumgebung eine Renderengine an den onion.net Information Server des Projektes zu binden. Mit der "echten" Konfiguration können Sie dann Ihre Entwicklung lokal testen und debuggen. 2.3 Verweise hinzufügen Da wir onion.net erweitern wollen, benötigen wir auch die entsprechenden Klassen dafür. Machen Sie dafür einen Rechtsklick auf "Verweise" rechts im Projektmappen-Explorer und wählen Sie "Verweis hinzufügen" aus. Wechseln Sie anschließend im sich öffnenden Dialog auf den Reiter "Durchsuchen" und navigieren Sie zum Ordner einer aktuellen Distribution auf Ihrem Rechner. Dort navigieren Sie in die Struktur "onion.net Render Engine" > "bin". Sie bekommen alle Bibliotheken der onion.net Renderengine angezeigt. Wählen Sie alle aus und bestätigen Sie mit Klick auf "OK". 4

7 2 Ein Projekt in Visual Studio einrichten 2.4 Projekt konfigurieren Um später korrekt mit ihrem onion.net-projekt zusammenzuspielen und eine Aktualisierung der onion.net Verweise gewährleisten zu können, sind nun noch zwei kleine Einstellungen nötig. Wechseln Sie hierfür über das Kontextmenü des Projekts in dessen Eigenschaften. Im Reiter "Anwendung" stellen Sie das Zielframework auf die Version 3.5 um. 5

8 3 Grundsätzliche Vorgehensweise Bestätigen Sie die folgende Sicherheitsabfrage durch Klick auf "Ja". Die Eigenschaften werden automatisch geschlossen. Im Projektmappen-Explorer sehen Sie, dass der Verweis "Microsoft.CSharp" mit einem Warnungssymbol gekennzeichnet ist. Diese Assembly ist erst ab dem Framework 4.0 vorhanden und wird von uns nicht benötigt. Löschen Sie den Verweis. Wechseln Sie danach erneut in die Projekteigenschaften und dort in den Reiter "Verweispfade". Fügen Sie den "bin"-ordner der Renderengine einer aktuellen Distribution hinzu. Nachdem Sie die Eigenschaften gespeichert haben, können Sie den Tab schließen. 3 Grundsätzliche Vorgehensweise Um den Funktionsumfang von XSLT zu erweitern, muss zunächst ein Modul erstellt werden. Dieses dient gewissermaßen als Container für verschiedene Extensions, die dann wiederum die eigentlichen Funktionserweiterungen in Form von Methoden bereitstellen. Wie Sie vielleicht schon in der Dokumentation für die Renderengine Konfiguration gelesen haben, werden die Module über die web.config eingebunden und konfiguriert. 4 Modul erstellen Fügen Sie Ihrem Projekt eine neue Klasse hinzu, die Sie "ProjektnameModule" nennen. 6

9 4 Modul erstellen Nun implementieren Sie das Interface "IModule", was Sie unter "Onion.RenderEngine.Modules" finden. Wenn Sie alle Member implementiert haben, sollte Ihre Klasse wie folgt aussehen: public class ProjektnameModule : IModule public void Dispose() throw new NotImplementedException(); public void Configure(IRenderEngine engine, XmlElement configuration) throw new NotImplementedException(); public IExtension[] Extensions get throw new NotImplementedException(); 4.1 Methode»Dispose()«Für die Methode»Dispose()«ist in der Regel keine spezielle Anweisung notwendig. Den Inhalt können Sie daher getrost entfernen. 7

10 4 Modul erstellen 4.2 Setter/Getter»Extensions«Da die aus XSLT aufrufbaren Funktionen in Extensions eingebettet sind, muss dem Modul noch mitgeteilt werden, welche Extensions ihm zugeordnet sind. Dies geschieht in einer globalen Variable "Extensions", die vom Typ "IExtension[]" ist und die Sichtbarkeit "private" besitzt. Fügen Sie die globale Variable hinzu und erweitern Sie den Getter, sodass das Feld auch außerhalb der Klasse abgefragt werden kann. public class ProjektnameModule : IModule private IExtension[] extensions; public void Dispose() public void Configure(IRenderEngine engine, XmlElement configuration) throw new NotImplementedException(); public IExtension[] Extensions get return extensions; 4.3 Methode»Configure()«In der Methode»Configure()«werden notwendige Konfigurationen für das Modul vorgenommen. In den meisten Fällen und für den Anfang ist das lediglich das Initialisieren des Feldes»extensions«. public void Configure(IRenderEngine engine, XmlElement configuration) extensions = new IExtension[] new ProjetktnameExtension() ; Die Methode bekommt aber zwei Parameter übergeben, die für weitere Konfigurationen genutzt werden können. IRenderEngine engine Dieser Parameter enthält die aktuelle RenderEngine, in dessen Kontext das Modul eingebettet ist beziehungsweise aufgerufen wird. Sie kann auch über den Konstruktor in die Extension übergeben werden, um dort beispielsweise auf Datenobjekte zuzugreifen. XmlElement configuration 8

11 5 Extension erstellen Beim Einbinden des Moduls in der web.config können Sie zusätzliche Konfigurationen über untergeordnete XML-Elemente vornehmen. Dies können zum Beispiel Zugangsdaten etwa für einen Mailserver sein oder ein Connection String zu einer zusätzlichen Datenbank, in die Sie speichern möchten. 5 Extension erstellen Wir haben im vorigen Schritt zwar dem Modul eine Extension zugewiesen. Die müssen wir allerdings noch erstellen. Legen Sie dazu analog zum Modul eine Klasse namens "ProjektnameExtension" an. Diese Klasse muss das Interface "IExtension" implementieren. Danach sieht Ihre Klasse etwa wie folgt aus: public class ProjektnameExtension : IExtension public string Namespace get throw new NotImplementedException(); Mit dem Getter legen Sie fest, unter welchem Namensraum die Erweiterung später im XML eingebunden werden soll. Üblicherweise wird hier die Domain der späteren Live-Seite ggf. mit dem aktuellen Jahr als Zusatz genommen. public string Namespace get return " Ein Namensraum ist üblicherweise mit einem Präfix verknüpft. Aus dem Assistenten zum Hinzufügen neuer Namensräume kennen Sie ja bereits die Funktionalität, dass automatisch ein bestimmtes Präfix mit dem Namespce verknüpft wird, um eine konsistente Nutzung zu gewährleisten. Ein solches Präfix können Sie auch für Ihre eigene Extension definieren. Dies geschieht über ein "ExtensionDocumentationAttribute", welches Sie wie folgt der Klasse hinzufügen: [ExtensionDocumentation(ExamplePrefix = "ext")] public class ProjektnameExtension : IExtension... 9

12 6 Modul einbinden 5.1 Methoden definieren Nun können Sie beliebige Methoden für Ihre Extension definieren. Analog zum "ExtensionDocumentationAttribute" gibt es ein "ExtensionMethodAttribute". Damit können Sie unabhängig vom C#-konformen Code einen Namen definieren, unter dem die Methode im XSLT aufgerufen werden kann. [ExtensionMethod(Name = "helloworld")] public string HelloWorld() return "Hello World!"; 6 Modul einbinden 6.1 Datei portieren Beim Erstellen des Projektes in Visual Studio wird eine.dll-datei ("Projektname.Renderengine.dll") im Projektordner angelegt. Diese muss in das "preview/bin"-verzeichnis des onion.net-projektes kopiert werden. Damit steht die Erweiterung zur Verfügung. 6.2 web.config Damit Ihre Extension in den XSL-Transformationen verfügbar ist, muss das Modul in der web.config hinzugefügt werden. Erweitern Sie dafür den Abschnitt <modules> um folgende Zeile: <module type="projektname.renderengine.projektnamemodule, Projektmame.Renderengine" /> Der Teil vor dem Komma gibt direkt das Modul an, der Teil hinter dem Komma den entsprechenden Namensraum. Falls Ihre Extension noch nicht im Assistenten zu Aktualisierung der Namensräume auftaucht, starten Sie die Editor Webanwendung durch Ändern und Abspeichern der web.config neu, damit sich die Konfiguration aktualisiert. 10