Artikel
12/09/2016

Connect(); 2016

Band 31, Nummer 12

Xamarin Workbooks: Die (interaktive) Zukunft der technischen Dokumentation

Früher einmal waren gedruckte Fachbücher die Hauptquelle zum Erlernen neuer Programmiersprachen und SDKs. Heute finden Sie im Internet eine Unzahl von Inhalten: von Produktdokumentationen bis zu Entwicklerblogs, von Stack Overflow bis GitHub und von Podcasts zu YouTube und sogar Xamarin University-Onlinekurse.

Doch Lernhemmnisse kann es auch weiterhin noch geben: Das Konfigurieren der neuen IDE, in der Sie die Programmierung starten möchten, das Verstehen des Assistenten „Datei“ > „Neues Projekt“ und aller seiner Optionen, das Eingeben oder Kopieren von Beispielcode in ein neues oder vorhandenes Projekt, um ihn auszuprobieren, und selbst das Navigieren durch die sich ergebende Projektmappenstruktur kann für Uneingeweihte verwirrend sein. Entwickler, die von Visual Basic zu Eclipse zu Xcode gewechselt sind, verstehen genau, wie unterschiedlich diese Umgebungen sein können.

Roslyn, der Open Source .NET-Compilerdienst von Microsoft, ermöglicht neue Benutzererfahrungen, die diese Probleme beheben, weil keine IDE mehr erforderlich ist. In Lernumgebungen wie Gistlyn (bit.ly/2d00D7b) und dem neuen C#-Onlinetutorial von Microsoft (bit.ly/28WyuvW) taucht der Entwickler in Dokumentation und Code ein, ohne sich um Projektmappen und Projekte kümmern zu müssen. Durch diese neuen Tools wird das Lernen einfacher und interaktiver.

Vorstellung von Xamarin Workbooks

Mit Xamarin Workbooks steht dieses interaktive Konzept aus Dokumentation plus Liveprogrammierung für die Entwicklung von mobilen und Desktopanwendungen zur Verfügung. Zusammen mit Gerätesimulatoren bieten Workbooks die gleiche beeindruckende Erfahrung wie die erwähnten Onlinetools. Außerdem stellen sie jedoch die zusätzliche Möglichkeit bereit, mit allen nativen SDKs für Android, iOS, Mac und Windows Presentation Foundation (WPF) zu experimentieren und diese zu erlernen:

Das Erlernen der Entwicklung mobiler Xamarin-Apps wird zu einem interaktiven Erkundungsvorgang. Sie lesen nicht einfach nur die Dokumentation. Mit Workbooks können Sie native Features der mobilen App interaktiv codieren und testen.
Das Untersuchen von Online-APIs (auch von Microsoft Azure-Diensten) kann mühelos erfolgen, ohne eine Beispiel-App aufzusetzen und durch unzählige Quelldateien zu navigieren. Da Sie die gleichen Tools verwenden, mit denen Ihre mobilen Apps geschrieben werden, kann funktionierender Code aus Workbooks in Ihre Xamarin-App-Projekte kopiert werden.
Das Schreiben eigener Workbooks ist unabhängig davon, ob Sie eine Idee testen oder Ihre eigene Courseware als Unterrichtsmaterial erstellen, ganz einfach. Anstatt zum hundertsten Mal „Datei“ > „Neues Projekt“ zu verwenden, um etwas Neues auszuprobieren, können Sie ein schnelleres und einfacheres Verfahren für Ihre Experimente nutzen. Zusätzlicher Bonus: Sie können mit der Benutzeroberfläche im Simulator interagieren und den visuellen Baum in der Prüfungsansicht untersuchen.

Erste Schritte

Worum handelt es sich genau bei Workbooks? Kurz gesagt: Es handelt es sich um interaktive Livedokumentation für mobile und Desktopplattformen. Sie können die Workbooks-App für Mac und Windows unter bit.ly/2ejXBj8 herunterladen. Für Android und iOS sollten Xamarin und die Plattform-SDKs und -simulatoren auf Ihrem System installiert sein.

Workbooks-Dateien sind im Wesentlichen Markdowndateien mit einem YAML-Header. Sie enthalten formatierten Text und umgrenzten C#-Code. Die Dateierweiterung lautet WORKBOOK. Sie können ein Workbook mit jedem beliebigen Text-Editor schreiben. Die Xamarin Workbooks-App bietet jedoch die Möglichkeit, Workbooks zu erstellen und zu bearbeiten. Sie müssen daher das zugrunde liegende Format nicht wirklich erlernen. Das folgende Beispiel zeigt Markdownquellcode:

---
uti: com.xamarin.workbook
platform: iOS
---
# My First Workbook
Simple C# assignment will render the resulting object as a string.
```csharp
var greeting = "Hello, MSDN"
```

Abbildung 1 zeigt das sich ergebende Workbook vor und nach der Ausführung.

Abbildung 1: „MyFirst.workbook“ vor und nach der Ausführung

Ausführbare Codezellen weisen einen grauen Hintergrund auf und verwenden die gleiche Bearbeitungsbenutzeroberfläche wie Visual Studio Code. Features wie Syntaxhervorhebung, Codevervollständigung, Kompilierungsfehler und Tastenkombinationen werden unterstützt.

Wenn Sie in einer Codezelle klicken, damit sie den Fokus erhält, wird darunter eine Reihe von Aktionsschaltflächen angezeigt (wie in Abbildung 1 gezeigt). Drücken Sie die Wiedergabeschaltfläche (Pfeil im Kreis ganz links), um diese Codezelle (und den ggf. vorhergehenden Code) auszuführen. Sie können auch das gesamte Workbook gleichzeitig mithilfe des Menüs „Ausführen“ ausführen.

Nachdem der Code ausgeführt wurde, wird eine Ergebniszelle unter der Codezelle angezeigt. Sie können jeden Teil der Codezelle bearbeiten, um die Ausführungsart zu ändern oder mit der API zu experimentieren, und dann „Wiedergabe“ drücken, um den Code erneut auszuführen. (Und nochmals auszuführen. Auf diese Weise lernen Entwickler mit Workbooks: durch Lesen der Dokumentation und Ausführen und Ändern des Beispielcodes während einer Sitzung.)

Die Ergebniszelle enthält eine Darstellung des letzten Objektverweises in der Codezelle. Die Zeichenfolgendarstellung des Objekts wird standardmäßig verwendet. Workbooks unterstützt jedoch zahlreiche weitere Visualizer zum Untersuchen der Ergebnisse. Verwenden Sie das kleine Menü neben dem Ergebnis, um eine Auswahl unter den verfügbaren Visualisierungen zu treffen, beispielsweise:

C#: Eine Zeichenfolge mit Escapezeichen für C# (z. B. werden neue Zeilen als „\n“ codiert).

Nur-Text: Ein Zeichenfolgenwert ohne Escapezeichen (z. B. werden neue Zeilen als mehrzeiliger Text gerendert).

Objektmember: Rendert eine vollständige Liste der Eigenschaften des Objekts in einer Tabelle. Große, zyklische Objektdiagramme werden bei Bedarf ausgewertet, damit sie Ihre Codierung nicht verlangsamen. Sie stehen jedoch bei Bedarf (wie ein Laufzeitdebugger) für die Untersuchung zur Verfügung.

Enumerable: Erweitert automatisch eine Sammlung, damit Sie jedes Element untersuchen können. Anfangs werden nur die ersten 10 Elemente angezeigt. Sie können aber weitere Elemente durch Klicken auf die Schaltfläche „Aufzählung fortsetzen“ einblenden.

Farbe: Ein kleines Farbmuster wird zusammen mit Hex- oder RGB-Darstellungen seines Werts angezeigt.

Standort: Objekte, die eine Breitengrad-/Längengradangabe darstellen, werden auf einer Karte angezeigt (nur Mac).

Bild: Gültige Bildansichtklassen können das Bild inline im Workbook anzeigen.

Ausnahme: Hebt Ausnahmemeldungen in der Ergebniszelle hervor.

HTML: Workbooks-Autoren können die AsHtml-Methode in ihren Codezellen verwenden, damit die Ergebniszelle eine Zeichenfolge als HTML rendert.

Abbildung 2 zeigt das Visualisierer-Workbook mit Beispielen für einige Optionen.

Abbildung 2: Visualisierungsoptionen

Bis jetzt habe ich Ihnen nur Workbooks vorgestellt, die ihre Ergebnisse inline anzeigen. Noch interessanter wird es jedoch, wenn native mobile APIs mit Xamarin über Simulatoren für mobile Geräte untersucht werden.

Erlernen von Xamarin mit Workbooks

Nachdem Sie sich mit dem Ausführen von Codezellen und dem Interpretieren der Ergebnisse vertraut gemacht haben, können Sie developer.xamarin.com/workbooks besuchen und Workbooks herunterladen, um Android, iOS und Xamarin.Forms zu erlernen. Die nativen Plattform-APIs sind in Workbooks für einfache (Hinzufügen einer Bezeichnung zum Bildschirm) bis hin zu komplexen Tasks (Rendern von 3D-Inhalt, der auf Berührung reagiert) verfügbar.

Wenn Sie ein iOS-, Android- oder Xamarin.Forms-Workbook erstellen oder öffnen, wird ein Simulator für mobile Geräte gestartet (für Mac- und WPF-Workbooks (Windows Presentation Foundation) wird nur ein leeres Fenster geöffnet). Diese externen Simulatoren (oder Fenster) führen eine Agent-App aus, die mit dem Workbook kommuniziert. Es wird eine Statusmeldung angezeigt, wenn der Agent gestartet wird. Sobald der Agent ausgeführt wird, können Sie mit der Erkundung von Xamarin Workbooks beginnen.

Während Sie die Dokumentation lesen und jede Codezelle ausführen, ändert sich die App im Simulator entsprechend den neu hinzukommenden Codeausschnitten. Wenn Sie neugierig sind, wie etwas funktioniert, bearbeiten Sie den Code und führen ihn dann erneut aus. Abbildung 3 zeigt ein einfaches iOS UITableView-Beispiel, Abbildung 4 dessen Ausführung im Simulator.

Abbildung 3: „XamariniOS.workbook“

---
uti: com.xamarin.workbook
platform: iOS
packages:
- id: Newtonsoft.Json
  version: 9.0.1
---
# iOS UITableView
This example uses **Json.NET** and `WebClient` to download a file *monkeydata.json* that is used to bind to the iOS UITableView.
```csharp
#r "Newtonsoft.Json"
#load "json_monkey.csx"
```
To add a UITableView control to the screen, instantiate an instance, set the bounds, and add to the `RootViewController`. You can experiment with changing the `Frame`.
```csharp
var tableView = new UITableView();
tableView.Frame = UIScreen.MainScreen.Bounds;
RootViewController.View.AddSubview(tableView);
```
Wiring up a data source (like a generic list of `Monkey` objects) to a table requires a `UITableViewSource`. This class converts the data into `UITableViewCell` classes to be rendered.
```csharp
public class MySource : UITableViewSource
{
  string identifier = "mycell";
  public List<Monkey> Data {get;set;} = new List<Monkey>(); // C# 6
  public override nint RowsInSection (UITableView tableview, nint section)
  {
    return Data.Count;
  }
  public override UITableViewCell GetCell (UITableView tableView,
    NSIndexPath indexPath)
  {
    // First, get or create a cell
    UITableViewCell cell = tableView.DequeueReusableCell (identifier);
    if (cell == null)
    { cell = new UITableViewCell (UITableViewCellStyle.Subtitle, identifier); }
    // Then, get the data and set the UI
    cell.TextLabel.Text = Data[indexPath.Row].Name;
    cell.DetailTextLabel.Text = Data[indexPath.Row].Location;
    return cell;
  }
}
```
To display the data in the table, create the source object, assign the Monkey object list, then assign it to the table
```csharp
var source = new MySource(); // Create the class
source.Data = monkeys;       // Assign the list of strings
tableView.Source = source;   // Give it to the table view
tableView.ReloadData();      // and show on the screen
```

Abbildung 4: Workbooks und der iOS-Simulator

Workbooks kann auch eine explodierte Ansicht der zu untersuchenden Benutzeroberflächenhierarchie anzeigen. Sie können Elemente im Simulator, das 3D-Rendering oder die visuelle Strukturliste auswählen und deren Eigenschaften in einem Pad anzeigen. Wählen Sie für den Zugriff darauf auf einem Mac die Option „Ansicht“ > „Visuelle Prüfung“ aus. Unter Windows sind die Pads angedockt, und der Zugriff darauf kann jederzeit erfolgen. Wenn Sie zurück zum Code und der Dokumentation wechseln möchten, verwenden Sie das Menüelement „Ansicht“ > „Workbook“.

Untersuchen von APIs

Workbooks eignet sich auch gut für die Untersuchung anderer APIs, z. B. der durch NuGet-Pakete oder REST-Endpunkte bereitgestellten APIs. Ein Beispiel, das beides kombiniert, ist ein Workbook, das mithilfe des kostenlosen tryappservice.azure.com-Back-Ends eine Verbindung mit Azure EasyTables herstellt.

Die vollständige Workbookquelle (einschließlich der erforderlichen NuGet-Pakete) wird in Abbildung 5 gezeigt. Abbildung 6 zeigt die Ausführung des vollständigen Codes zum Speichern und Abrufen von Daten aus einer Azure EasyTable-Tabelle.

Abbildung 5: „Azure-TryAppService.workbook“

---
uti: com.xamarin.workbook
platform: WPF
packages:
- id: Microsoft.Bcl
  version: 1.1.10
- id: Newtonsoft.Json
  version: 9.0.1
- id: Microsoft.Net.Http
  version: 2.2.29
- id: Microsoft.Azure.Mobile.Client
  version: 3.0.1
---
# Azure TryAppService
Two NuGets - **Microsoft.Azure.Mobile.Client** & Newtonsoft.Json - have been added:
```csharp
#r "Newtonsoft.Json"
#r "Microsoft.WindowsAzure.Mobile"
#r "Microsoft.WindowsAzure.Mobile.Ext"
```
This `TodoItem` class matches the one configured in the TryAppService back end.
```csharp
using Newtonsoft.Json;
using Microsoft.WindowsAzure.MobileServices;
public class TodoItem
{
  [JsonProperty(PropertyName = "id")]
  public string ID {get;set;}
  [JsonProperty(PropertyName = "text")]
  public string Name {get;set;}
  [JsonProperty(PropertyName = "complete")]
  public bool Done {get;set;}
  [Version]
  public string Version { get; set; }
  public override string ToString() {
    return $"{Name} is " + (Done?"done":"not done");
  }
}
```
Sign up at [tryappservice.azure.com](https://tryappservice.azure.com/ "Try Azure for free!") **Mobile App > TodoList**. Replace the URL with *your* temporary, generated endpoint URL:
```csharp
var mobileService = new MobileServiceClient (
  "https://da0cfa57-0ee0-4-231-b9ee.azurewebsites.net/");
  // Replace this with your own
var table = mobileService.GetTable<TodoItem> ();
```
The following code creates a new `TodoItem` class, inserts it into the table on the server, and retrieves the list from the server:
```csharp
var rememberTo = new TodoItem {Name="buy apples"};
await table.InsertAsync (rememberTo);
List<TodoItem> todos = await table.Take (10).ToListAsync ();
```

Abbildung 6: Interaktives Verwenden von Azure TryAppService

Natürlich ist dies nur ein kleiner Ausschnitt von Azure. Dieses Beispiel zeigt nur im Ansatz, wie Workbooks für das Erlernen einer API genutzt werden kann.

Schreiben eigener Workbooks

Natürlich können Workbooks in Markdown geschrieben werden. Das einfachste Verfahren zum Erstellen eines eigenen Workbooks besteht jedoch im Verwenden der Workbooks-App selbst. Wählen Sie das Menüelement „Datei“ > „Neu“ aus, und wählen Sie dann eine Plattform aus: iOS und Android können unter macOS und Windows erstellt werden. Mac- und WPF-Workbooks können nur unter macOS bzw. Windows erstellt werden.

Workbooks bestehen aus drei Typen von Elementen: Textzellen, Codezellen und Ergebniszellen. Ein nagelneues Workbook enthält eine einzelne Codezelle, in der Sie sofort C#-Code eingeben und ausführen können.

Zellen können mithilfe der Aktionsschaltflächen hinzugefügt und entfernt werden, die unter einer Zelle angezeigt werden, wenn diese den Fokus besitzt. Es sind drei Schaltflächen verfügbar (siehe Abbildung 1):

Plus (+): Fügt eine neue Codezelle hinzu.
Doppeltes Anführungszeichen ("): Fügt eine neue Textzelle hinzu.
Löschen (x): Löscht die vorherige Zelle.

Alle Codezellen in einem Workbook werden im gleichen Kontext ausgeführt. Variablen und Klassen, die in einer Codezelle erstellt wurden, sind daher in nachfolgenden Codezellen verfügbar.

Text kann formatiert werden, indem Sie ihn markieren und dann die Formatierungsleiste verwenden, die in Abbildung 7 gezeigt wird. Die verfügbaren Optionen umfassen Fett, Kursiv, das Hinzufügen von Links und Codeformat sowie Aufzählungen, nummerierte Listen und Blockquotes. Außerdem sind sechs Überschriftenebenen vorhanden, und es können Bilder oder eine horizontale Trennlinie eingefügt werden.

Abbildung 7. Formatieren von Text

Codezellen unterstützen das Hervorheben von C#-Schlüsselwörtern und das Überschreiben automatischer Vervollständigung für Member und Signaturen. Fehler werden durch eine rote Unterstreichung markiert, und die Fehlermeldung wird angezeigt, wenn Sie mit der Maus darauf zeigen.

Jede Plattform besitzt wie folgt einen eigenen Mechanismus für den Zugriff auf die Benutzeroberfläche:

Android: Das Erstellen von Workbooks, die den Simulator nutzen, bedeutet, dass eine Möglichkeit vorhanden sein muss, auf die Benutzeroberfläche aus Codezellen zu verweisen. Verwenden Sie für Android den folgenden Code, um einen Verweis auf die Aktivität abzurufen, die vom Simulator verwendet wird:

var mainActivity = StartedActivities.First();
var label = new Android.Widget.TextView(mainActivity) {
  Text = "Hello, Workbooks",
  TextSize = 36
};
mainActivity.SetContentView(label);

iOS: iOS-Workbooks stellen den „RootViewController“ des Simulators bereit, damit Sie die Benutzeroberfläche durch Hinzufügen von Unteransichten wie hier gezeigt aufbauen können:

var label = new UIKit.UILabel(new CGRect(10,10,300,50)) {
  Text = "Hello, Workbooks",
  Font = UIFont.SystemFontOfSize(36)
};
RootViewController.Add(label);

WPF: Das Hinzufügen von Steuerelementen zum App-Fenster in WPF-Workbooks erfolgt durch Festlegen der Content-Eigenschaft auf „System.Windows.Application.Current.MainWindow“, beispielsweise:

var label = new System.Windows.Controls.Label {
  Text = "Hello, Workbooks",
  FontSize = 36
};
System.Windows.Application.Current.MainWindow.
  Content = label;

Workbooks enthält auch Features, mit denen Sie anspruchsvollere Codeszenarien erstellen können. Die folgenden Möglichkeiten bestehen:

Verweisen auf weitere Namespaces: Standardmäßig steht in jedem Workbook nur eine eingeschränkte Anzahl von Namespaces zur Verfügung. Einige dieser Namespaces (z. B. „System.Xml“) erfordern eine using-Klausel am Anfang der Codezelle, damit sie verwendet werden (genau wie in einer normalen C#-Datei).

Hinzufügen von NuGet-Paketen: Verwenden Sie das Menüelement „Datei“ > “Paket hinzufügen“, um einem Workbook NuGet-Pakete hinzuzufügen, und stellen Sie sicher, dass auf die Assemblys mithilfe der folgenden Syntax verwiesen wird:

#r "Microsoft.WindowsAzure.Mobile"

Für Assemblys, auf die auf diese Weise verwiesen wird, ist weiterhin die entsprechende using-Anweisung in einer Codezelle erforderlich (wie in Abbildung 6 gezeigt).

Einschließen zusätzlichen Codes: Komplexere Beispiele erfordern ggf. große Mengen Code, die das Workbook nur unübersichtlich erscheinen lassen würden, wenn sie inline angezeigt werden. Auf externe Codedateien kann durch ein Workbook mit der folgenden Syntax verwiesen werden:

#load "my-extra-code.csx"

Verwenden Sie externe Dateien, um unterstützende Klassen, Benutzeroberflächenelemente, Model- und ViewModel-Klassen oder andere Objekte zu erstellen, die für die Funktionalität des Workbooks erforderlich sind, nicht aber für die Dokumentation (und deren Änderungserfordernis durch den Benutzer unwahrscheinlich ist). Das Workbook in Abbildung 3 zeigt, wo Dateneinrichtungscode mit einer externen Datei hinzugefügt wird, damit die Anleitungen einfach lesbar bleiben.

Abrufen von Hilfe: Geben Sie „help“ als letzte Zeile in einer beliebigen Codezelle ein, um schnell die unterstützenden Methoden anzuzeigen, die im Workbook verfügbar sind.

Zusammenfassung

Xamarin Workbooks stellt zurzeit das schnellste Verfahren zum Erlernen der Entwicklung mobiler Anwendungen dar. Sie können sich umfassend über native mobile Plattformen informieren und sich mit Online-APIs vertraut machen. Es ist außerdem ganz einfach, eigene benutzerdefinierte Workbooks für Ihren Blog, für Trainingszwecke oder andere Bereiche zu erstellen. Workbooks können NuGet-Pakete enthalten und auf zusätzliche Namespaces verweisen sowie auf alle Android-, iOS-, macOS- und WPF-SDKs.

Besuchen Sie developer.xamarin.com/workbooks, um sich mit den ersten Schritten vertraut zu machen. Xamarin ist kostenlos als Bestandteil von Visual Studio Community Edition verfügbar (auch auf dem Mac), und die Workbooks-App kann kostenlos heruntergeladen und verwendet werden.

Craig Dunn ist Program Manager für die Xamarin-Dokumentation bei Microsoft. Folgen Sie ihm auf Twitter: @conceptdev oder über LinkedIn unter linkedin.com/in/conceptdev.

Unser Dank gilt den folgenden technischen Experten von Microsoft für die Durchsicht dieses Artikels: Aaron Bockover und David Britch
David Britch arbeitet in der Xamarin-Dokumentationsgruppe bei Microsoft. Er ist der Autor mehrerer Veröffentlichungen zur Softwareentwicklung, z. B. von Büchern, Leitfäden, Referenzimplementierungen, Whitepapern, Videos und Trainingskursen mit Trainingsleiter.

Aaron Bockover leitet das Team „Xamarin Workbooks & Inspector“ bei Microsoft. Er ist begeisterter .NET- und (seit der Einführung von Mono) Mono-Fan. Er kümmert sich mit Leidenschaft darum, dass andere Benutzer C# und .NET sowie die unzähligen zugehörigen Plattformen optimal nutzen können.