seeseekey.net - Invictus Deus Ex Machina

In den letzten Tagen habe ich für ein Projekt einen REST-Server geschrieben. Der Server läuft unter .NET bzw. Mono – also war ich auf der Suche nach einer passenden Bibliothek bzw. einem Framework, welches mich bei dem Aufsetzen eines solchen Servers unterstützt. Nach einem Blick auf Nancy und einigen anderen Frameworks bin ich schlussendlich bei Grapevine gelandet.

sukona.github.io

sukona.github.io

Dabei handelt es sich um eine Bibliothek, welche neben einem REST-Client auch einen REST-Server bereitstellt. Das Hauptaugenmerk der Entwicklung wird dabei auf den REST-Server gelegt. Mit Hilfe des Frameworks lässt sich ein REST-Server mittels weniger Zeilen Quellcode aufsetzen:

ServerSettings settings = new ServerSettings();
settings.Host = "localhost";
settings.Port = "1111";

RestServer server = new RestServer(settings);
server.Start();

In diesem Beispiel werden die Einstellungen für den Server angelegt und anschließend dem Server übergeben. Danach wird der Server mit der Methode Start hochgefahren. Damit verfügt man zwar über einen REST-Server, dieser verfügt allerdings über keinerlei Methoden was die praktische Verwendung eher erschwert. Ressourcen für den Server werden mittels des Attributes RestResource markiert:

[RestResource(BasePath = "/time/")]
public class TimeModule
{
    [RestRoute(PathInfo = "date")]
    public IHttpContext GetDate(IHttpContext context)
    {
        context.Response.SendResponse(Grapevine.Util.HttpStatusCode.Accepted, getDate());
        return context;
    }
}

Über das Attribut RestRoute wird eine Methode für Grapevine gekennzeichnet – das Pathinfo definiert dabei den Pfad über welchen diese aufgerufen werden kann. Durch den über das Attribut RestResource festgelegten BasePath lautet die vollständige URL für die Ressource:

http://localhost:1111/time/date

Wird diese Methode per GET aufgerufen, so wird das aktuelle Datum zurückgegeben. Damit ist ein minimaler REST-Server mit einer Ressource implementiert. Grapevine selbst ist unter der Apache Lizenz lizenziert und damit freie Software. Der Quelltext der Bibliothek befindet sich auf GitHub.

Ein REST-API von Hand entwickelt, benötigt eine Dokumentation, ein entsprechenden Server und eventuell einige Clients als Referenz. Einfacher wird es mit einem Framework wie Swagger. Unter Zuhilfenahme der Beschreibungssprache YAML können mit Hilfe des Frameworks REST-APIs, Dokumentation, Server und Clients generiert werden.

Der Swagger Editor

Der Swagger Editor

Doch Swagger versteht sich nicht nur als Framework, sondern auch als Spezifikation. Begonnen wurde mit der Entwicklung bereits im 2010; die Swagger Specification trägt seit Anfang Januar 2012 offiziell den Namen OpenAPI Specification und beschreibt eine maschinenlesbare Interfacedefinitionen einer REST-API. Ähnliches wurde unter anderem schon mit WSDL und WADL versucht – alles Konzepte bzw. Beschreibungsprachen welche an ihren eigenen Limitationen gescheitert sind und wenn überhaupt nur noch sporadisch genutzt werden.

Betreut und weiterentwickelt wird die Spezifikation nun von der Open API Initiative, zu der namenhafte Firmen wie Google, PayPal, IBM, Atlassian und Microsoft gehören. Die Spezifikation als solche ist freie Software und auf GitHub zu finden. Sie ist unter der Apache Lizenz lizenziert. Aktuell ist die Spezifikation in der Version 2.0 veröffentlicht.

Auf der offiziellen Webseite von Swagger findet sich ein Editor, mit welchem APIs definiert werden können und anschließend exportiert werden können. Der Editor kann dabei Server unter anderem in den Sprachen bzw. für die Framworks Haskel, Jax-RS, Node.js, Python, Rails und PHP erzeugen. Bei den Clients ist die Auswahl noch größer. Diese können in C#, HTML, Dart, Go, Groovy, Java, Javascript, Objective C, Perl, PHP, Ruby, Scala, Swift und vielen weiteren Sprachen erzeugt werden.

Neben dem Editor kann für die Erzeugung von Clients auch der Swagger Codegen genutzt werden. Dabei handelt es sich um eine Java-Anwendung um die Clients lokal auf dem eigenen Rechner zu erzeugen. Der Editor und viele weitere Tools rund um Swagger sind ebenfalls auf GitHub zu finden. – auch diese sind freie Software, welche unter der Apache Lizenz stehen.

Zur Entwicklung von Anwendungen nutze ich im Normalfall die Programmiersprache C#. In dieser gibt es sogenannte Signed und Unsigned-Datentypen. Im Deutschen würde man dazu vorzeichenbehaftete und vorzeichenlose Typen sagen. Bei einem vorzeichenbehafteten Typ wird die Hälfte des Wertebereiches für die Darstellung negativer Zahlen und die andere Hälfte für die Darstellung positiver Zahlen genutzt. Dies führt allerdings dazu das man die Hälfte des positiven Wertebereiches einbüßt. So gibt es für den UInt32 und den Int32 unter C# bzw. der CLR folgende Wertebereiche:

UInt32    0 bis 4.294.967.295
Int32    −2.147.483.648 bis 2.147.483.647

An dieser Stelle spielen vorzeichenlose Datentypen ihre Stärke aus, da sie über einen größeren Wertebereich für positive Zahlen verfügen – bei gleichem Speicherverbrauch. So ist die Nutzung vorzeichenloser Datentypen immer dann interessant, wenn man größere positive Zahlen speichern möchte. Wenn man sich nun die Datentypen bei Java anschaut, so wird man feststellen, das es unter Java keine vorzeichenlosen Typen (mit der Ausnahme des 16 Bit großen Typs char) gibt. Möchte man nun z.B. die Werte von 0 bis 255 speichern, was bei der Verarbeitung von Daten aus bestimmten Dateiformaten vorkommt, müsste man in Java hierfür einen short (16 Bit) anstatt eines byte (8 Bit) nutzen, da selbst das byte unter Java vorzeichenbehaftet ist und nur den Bereich von -128 bis 127 abbilden kann. Möchte man diesen zusätzlichen Speicherplatz nicht hergeben, so gibt es auch unter Java eine Möglichkeit größere Werte in einem byte zu speichern:

byte unsigned = (byte)200;
int value = (int)unsigned^-256;

In der ersten Zeile wird die Zahl 200 gecastet und der Variable unsigned zugewiesen. Das Bitmuster in der Variable entspricht dann der Zahl 200. Da der Typ allerdings als vorzeichenbehaftet interpretiert wird, würde ein:

System.out.println(unsigned);

zur Ausgabe der Zahl -56 führen. Möchten wir den Wert der Variable vorzeichenlos ermitteln, muss eine XOR-Operation mit -256 ausgeführt werden, welche schließlich zum Ergebnis 200 führt.

Vor einiger Zeit hatte ich die Xamarin.iOS-Trial-Lizenz des Xamarin Studio ausprobiert. Als diese abgelaufen war, fragte mich das Xamarin Studio ob ich die Lizenz verlängern oder mit der Starter-Edition fortfahren möchte. Ich entschied mich für die Starter-Edtion. Allerdings gibt es ein Problem. Xamarin Studio fragt nun bei jedem Start nach der gewünschten Option – was nicht nur nervig ist, sondern auch ein Fehler im Studio darstellt.

Das Lizenz-Pop-Up

Das Lizenz-Pop-Up

Als schnellen Workaaround kann der Account vom Xamarin Studio getrennt werden, allerdings ist das nicht die optimale Lösung. Stattdessen sollte man den Support kontaktieren und die Trial-Version aus dem Account entfernen lassen. Danach gehört das Problem der Vergangenheit an.

Wer den Weltraum betrachten möchte, kann sich ein Teleskop kaufen – wem das zu kostenintensiv ist, der kann es mit dem Wordwide Telescope von Microsoft probieren. Dabei handelt es sich um eine Windows- und Webanwendung, in welcher unterschiedliche Teleskopaufnahmen miteinander kombiniert und welche wie durch ein virtuelles Teleskop betrachtet werden können.

worldwidetelescope.org

worldwidetelescope.org

Microsoft hat die Anwendung unter der MIT-Lizenz freigegeben, damit ist das Wordwide Telescope freie Software. Der Quelltext für das ist auf GitHub zu finden – die offizielle Seite des Projektes unter worldwidetelescope.org.

Unter Xamarin Studio ist es wie in vielen IDEs möglich den Quelltext automatisch zu formatieren. Allerdings unterscheidet sich das Konzept etwas, von anderen C#/.NET IDEs wie dem Visual Studio. Xamarin Studio kennt hierbei einmal Benutzerrichtlinien und normale Einstellungen. In den Einstellungen kann die Codeformatierung für den entsprechenden Nutzer angelegt und modifiziert werden.

Die Einstellungen im Xamarin-Studio

Die Einstellungen im Xamarin Studio

Möchte man bestimmte Einstellungen allerdings auf mehreren Rechnern nutzen, so sollte man lieber eine Benutzerrichtlinie anlegen. Wenn die passenden Einstellungen in der Benutzerrichtlinie definiert sind, können sie auch als Datei exportiert und auf dem anderen Rechner importiert werden. Damit die Nutzerrichtlinie Wirkung zeigt, muss sie in den Einstellungen ausgewählt werden – damit werden die aktuellen Einstellungen mit denen der Richtlinie überschrieben. Ändert man die Richtlinie muss dieser Prozess wiederholt werden. Nachdem die Einstellungen angepasst wurden, kann die geöffnete Datei mittels Ctrl + I neu formatiert werden.

Ein Quelltext wird während der Entwicklung gewöhnlich kommentiert. Unter C# bzw. .NET gibt es dafür Kommentare nach einem bestimmen Schema. Über einer Methode könnte ein solcher Kommentar z.B. aussehen:

/// <summary>
/// Distance between a and b.
/// </summary>
/// <param name="a">The first vector.</param>
/// <param name="b">The second vector.</param>

Diese Kommentare kann die freie Software Doxygen auswerten und daraus eine Dokumentation erzeugen. Im Gegensatz zu anderen Lösungen wie Sandcastle ist Doxygen betriebsystemübergreifend verfügbar und kann somit – wie in diesem Beispiel – unter Mac OS X genutzt werden. Im ersten Schritt sollte Doxygen installiert werden. Unter Mac OS X kann dies einfach über MacPorts geschehen:

sudo port install doxygen

Nachdem Doxygen installiert ist, sucht man im Terminal den Ordner des Entwicklungsprojektes heraus und gibt dort ein:

doxygen -g projektname.doxygen

Damit wird eine Standard-Doxygen-Konfiguration erzeugt. In dieser Datei werden nun ein paar Änderungen vorgenommen:

PROJECT_NAME = "Testprojekt"
PROJECT_NUMBER = "Release Candidate 1"
OUTPUT_DIRECTORY = docs
RECURSIVE  = YES

Über den Aufruf:

doxygen projektname.doxygen

kann nun die HTML-Dokumentation des Quelltextes erzeugt erzeugt werden und diese anschließend im Browser genutzt werden.

Das Visual Studio formatiert den Quellcode automatisch nach den eingestellten Richtlinien. Wenn man nun aber die Richtlinien ändert, steht man vor dem Problem, das der Quelltext noch nach den alten Richtlinien formatiert ist.

Die Formatierungseinstellungen im Visual Studio

Die Formatierungseinstellungen im Visual Studio

Leider gibt es keine direkte Option im Visual Studio um den bestehenden Quelltext am Stück neu zu formatieren. Allerdings kommt man mit einem kleinen Makro (abgeleitet vom VS Formater Macro) an dieser Stelle weiter. Dazu wird im Visual Studio die Package Manager Console (zu finden unter Tools -> NuGet Package Manager -> Package Manager Console) geöffnet und dort folgendes eingegeben:

function f($projectItems) { $projectItems | ? { $_.Name -ne $null -and $_.Name.EndsWith( ".cs" ) -and -not $_.Name.EndsWith( ".Designer.cs" ) } | % { $win = $_.Open('{7651A701-06E5-11D1-8EBD-00A0C90F26EA}') ; $win.Activate() ; $DTE.ExecuteCommand('Edit.FormatDocument') } ; if ($projectItems) { $projectItems | % { f($_.projectItems) } } }
 
$dte.Solution.Projects | % { f($_.ProjectItems) }

Das Visual Studio öffnet nun alle *.cs Dateien in der geöffneten Solution und formatiert die Quelltexte neu. Dieser Vorgang ist dabei relativ langsam und führt bei größeren Projekten dazu das das Visual Studio einfriert. Auf Stack Overflow gibt es eine elegantere Lösung:

function FormatItems($projectItems) {
    $projectItems |
    % {
        # Write-Host "    Examining item: $($_.Name)";

        if ($_.Name -and $_.Name.ToLower().EndsWith(".cs") `
            -and (-not $_.Name.ToLower().Contains(".designer."))) {

            $win = $_.Open('{7651A701-06E5-11D1-8EBD-00A0C90F26EA}');
            $win.Activate();

            $dte.ExecuteCommand('Edit.FormatDocument');

            if (!$_.Saved) {
                Write-Host "    Saving modified file: $($_.Name)";
                $dte.ExecuteCommand('File.SaveSelectedItems');
            }

            $dte.ExecuteCommand('Window.CloseDocumentWindow');
        }

        if ($_.ProjectItems -and ($_.ProjectItems.Count -gt 0)) {
            # Write-Host "    Opening sub-items of $($_.Name)";

            FormatItems($_.ProjectItems);
        }
    };
}

$dte.Solution.Projects | % {
    Write-Host "-- Project: $($_.Name)";

    FormatItems($_.ProjectItems)
}
;

Bei dieser Lösung wird jede Datei nach der Neuformatierung, gespeichert und wieder geschlossen. Leider wird auch diese Lösung von Datei zu Datei langsamer, so das sie für größere Projekte wiederrum unbrauchbar ist. Mit der Extension Format Document gibt es eine Lösung welche schnell genug ist, allerdings funktioniert diese nur unter Visual Studio 2010. Nach einigen Anpassungen habe ich eine Version gebaut, welche auch unter Visual Studio 2012 und 2013 läuft. Das Problem an dieser Variante ist, das Dateien in Ordnern nur berücksichtigt werden wenn der Ordner im Solution Explorer geöffnet ist. Alles in allem ist keine der vorgestellten Lösungen wirklich optimal, allerdings kann man viele Fälle mit den vorgestellten Lösungen lösen.

Manchmal ruft man eine Methode unter .NET aus einem anderen Thread heraus auf. Je nachdem wie die Methode aufgerufen wird, kann es notwendig sein die Methode über Invoke aufzurufen. Mit folgendem Pattern geschieht dies nach Notwendigkeit automatisch:

private void MakeSomeFoo()
{
	MethodInvoker method=delegate
	{
		//Do some foo
		DoSomeFoo();
	};

	if(InvokeRequired) BeginInvoke(method);
	else method.Invoke();
}

Im MethodInvoker-Delegate ist der eigentliche Quellcode der Funktion zu finden. Dieser wird je nach Notwendigkeit im korrekten Thread aufgerufen.

Wenn man in einem .NET Property Grid ein DateTime-Objekt bearbeitet, so klappt ein Kalender auf, in welchem das Datum eingestellt werden kann. Anschließend kann umständlich die Uhrzeit eingestellt werden. Möchte man dieses Prozedere etwas vereinfachen, kann man für das DateTime-Objekt einen neuen UITypeEditor schreiben:

public class DateTimePickerEditor : UITypeEditor
{
	IWindowsFormsEditorService windowsFormsEditorService;
	DateTimePicker dateTimePicker=new DateTimePicker();

	public DateTimePickerEditor()
	{
		dateTimePicker.Format=DateTimePickerFormat.Custom;
		dateTimePicker.CustomFormat=String.Format("{0} {1}",
                 Application.CurrentCulture.DateTimeFormat.ShortDatePattern,
                 Application.CurrentCulture.DateTimeFormat.ShortTimePattern);
	}

	public override UITypeEditorEditStyle GetEditStyle(ITypeDescriptorContext context)
	{
		return UITypeEditorEditStyle.DropDown;
	}

	public override object EditValue(ITypeDescriptorContext context, IServiceProvider provider, object value)
	{
		if(provider!=null)
		{
			windowsFormsEditorService=provider.GetService(typeof(IWindowsFormsEditorService)) as IWindowsFormsEditorService;
		}

		if(this.windowsFormsEditorService!=null)
		{
			dateTimePicker.Value=(DateTime)value;
			windowsFormsEditorService.DropDownControl(dateTimePicker);
			value=dateTimePicker.Value;
		}

		return value;
	}
}

Nachdem der Editor fertiggestellt ist muss beim entsprechenden DateTime-Objekt noch der passende der Editor per Attribut definiert werden:

[EditorAttribute(typeof(DateTimePickerEditor), typeof(UITypeEditor))]
public DateTime DateAndTime;
{
	get
	{
		return dateAndTime;
	}
	set
	{
		dateAndTime=value;
	}
}

Damit verfügt man nun über einen Editor im Property Grid, welcher die Bearbeitung von Datum und Zeit komfortabel erlaubt.