Entwickeln einer Jupyter Notebook-Erweiterung

Dieses Tutorial veranschaulicht, wie Sie eine neue Azure Data Studio-Erweiterung für Jupyter Notebook erstellen. Die Erweiterung enthält ein Beispiel für eine Jupyter Notebook-Instanz, die in Azure Data Studio geöffnet und ausgeführt werden kann.

In diesem Artikel wird Folgendes behandelt:

• Erstellen eines Erweiterungsprojekts
• Installieren des Erweiterungs-Generators
• Entwickeln einer Notebookerweiterung
• Ausführen der Erweiterung
• Packen der Erweiterung
• Veröffentlichen der Erweiterung im Marketplace

Verwendete APIs

• azdata.nb.showNotebookDocument

Anwendungsfälle für Erweiterungen

Es gibt verschiedene Gründe, eine Notebook-Erweiterung zu entwickeln:

• Freigeben interaktiver Dokumentationen
• Speichern des Notebooks und dauerhafter Zugriff auf dieses
• Programmieranweisungen für Benutzer
• Versionserstellung und Nachverfolgung von Notebook-Updates

Voraussetzungen

Azure Data Studio ist auf dem gleichen Framework wie Visual Studio Code aufgebaut, sodass Erweiterungen für Azure Data Studio mithilfe von Visual Studio Code erstellt werden. Sie benötigen die folgenden Komponenten:

• Node.js – installiert und in Ihrem $PATH verfügbar. Node.js enthält npm, den Node.js-Paket-Manager, der zum Installieren des Erweiterungsgenerators verwendet wird.
• Visual Studio Code zum Debuggen der Erweiterung.
• Stellen Sie sicher, dass sich azuredatastudio in Ihrem Pfad befindet. Wenn Sie unter Windows arbeiten, wählen Sie in „setup.exe“ die Option Zu PATH hinzufügen aus. Führen Sie unter macOS oder Linux über die Befehlspalette in Azure Data Studio Befehl 'azuredatastudio' in PATH installieren aus.

Installieren des Erweiterungsgenerators

Um den Prozess der Erstellung von Erweiterungen zu vereinfachen, haben wir einen Erweiterungsgenerator erstellt, der Yeoman verwendet. Um diesen zu installieren, führen Sie an der Eingabeaufforderung den folgenden Befehl aus:

npm install -g yo generator-azuredatastudio

Erstellen der Erweiterung

So erstellen Sie eine Erweiterung:

1. Starten Sie den Erweiterungs-Generator mit dem folgenden Befehl:

   yo azuredatastudio

2. Wählen Sie New Notebooks (Individual) (Neue Notebooks (einzeln)) aus der Liste der Erweiterungstypen aus:

   

3. Führen Sie die Schritte zum Ausfüllen des Erweiterungsnamens aus. Verwenden Sie für dieses Tutorial den Namen Test Notebook. Geben Sie dann einen Herausgebernamen ein. Verwenden Sie für dieses Tutorial Microsoft. Geben Sie schließlich eine Beschreibung ein.

An dieser Stelle gibt es einige Verzweigungen. Sie können entweder bereits erstellte Jupyter Notebook-Instanzen hinzufügen oder die über den Generator bereitgestellten Beispielnotebooks verwenden.

Verwenden Sie für dieses Tutorial ein Python-Beispielnotebook:

Wenn Sie über Notebooks verfügen, die Sie gern verwenden würden, geben Sie dies als Antwort an. Geben Sie den absoluten Dateipfad an, unter dem alle Notebooks oder Markdowndateien gespeichert sind.

Wenn Sie die vorherigen Schritte abschließen, wird ein neuer Ordner mit dem Beispiel-Notebook erstellt. Öffnen Sie den Ordner in Visual Studio Code. Nun sind Sie bereit, selbst eine Notebookerweiterung zu entwickeln.

Informationen zur Erweiterung

Ihr Projekt sollte derzeit wie folgt aussehen:

Die Datei vsc-extension-quickstart.md enthält einen Verweis auf die wichtigen Dateien. In der Datei README.md können Sie die Dokumentation für Ihre neue Erweiterung bereitstellen. Beachten Sie die Dateien package.json, notebook.ts und pySample.ipynb.

Wenn Dateien oder Ordner vorhanden sind, die Sie nicht veröffentlichen möchten, können Sie deren Namen in die Datei .vscodeignore einschließen.

Werfen wir einen Blick auf notebook.ts, um zu verstehen, was unsere neu erstellte Erweiterung bewirkt.

// This function is called when you run the command `Launch Notebooks: Test Notebook` from the
// command palette in Azure Data Studio. If you want any additional functionality
// to occur when you launch the book, add it to the activate function.
export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(vscode.commands.registerCommand('launchNotebooks.test-notebook', () => {
        let notebooksToDisplay: Array<string> = processNotebooks();
        notebooksToDisplay.forEach(name => {
            azdata.nb.showNotebookDocument(vscode.Uri.file(name));
        });
    }));

    // Add other code here if you want to register another command.
}

Das ist die Hauptfunktion in notebook.ts. Diese wird immer dann aufgerufen, wenn die Erweiterung über den folgenden Befehl ausgeführt wird: Launch Notebooks: Test Notebook (Notebook starten: Notebook testen). Wir erstellen den neuen Befehl mithilfe der API vscode.commands.registerCommand. Die folgende Definition in geschweiften Klammern ist der Code, der jedes Mal ausgeführt wird, wenn der Befehl aufgerufen wird. Jedes Notebook, das von der Funktion processNotebooks ermittelt wird, kann in Azure Data Studio über azdata.nb.showNotebookDocument geöffnet werden.

Die Datei package.json spielt außerdem eine wichtige Rolle beim Registrieren eines Befehls wie Launch Notebooks: Test Notebook (Notebook starten: Notebook testen).

"activationEvents": [
		"onCommand:launchNotebooks.test-notebook"
	],
	"main": "./out/notebook.js",
	"contributes": {
		"commands": [
			{
				"command": "launchNotebooks.test-notebook",
				"title": "Launch Notebooks: Test Notebook"
			}
		]
	}

Für den Befehl sind nun ein Aktivierungsereignis und spezifische Beitragspunkte vorhanden. Diese Beitragspunkte werden im Marketplace für Erweiterungen angezeigt. Dort werden Erweiterungen für Benutzer veröffentlicht. Wenn Sie weitere Befehle hinzufügen, müssen Sie diese auch dem Feld activationEvents hinzufügen. Weitere Optionen finden Sie unter Aktivierungsereignisse.

Packen der Erweiterung

Um Ihre Erweiterung für andere Benutzer freizugeben, müssen Sie sie in eine einzelne Datei packen. Ihre Erweiterung kann im Marketplace für Azure Data Studio-Erweiterungen veröffentlicht oder für Ihr Team oder Ihre Community freigegeben werden. Zu diesem Zweck müssen Sie über die Befehlszeile ein weiteres npm-Paket installieren.

npm install -g vsce

Bearbeiten Sie die README.md-Datei nach Ihren Wünschen. Navigieren Sie anschließend zum Basisverzeichnis der Erweiterung, und führen Sie vsce package aus. Optional können Sie ein Repository mit ihrer Erweiterung verknüpfen oder den Vorgang ohne Repository fortsetzen. Um ein Repository hinzuzufügen, fügen Sie der Datei package.json eine ähnliche Zeile hinzu.

"repository": {
    "type": "git",
    "url": "https://github.com/laurajjiang/testnotebook.git"
}

Sobald diese Zeilen hinzugefügt werden, wird die Datei my test-notebook-0.0.1.vsix erstellt und ist nun für die Installation bereit und kann geteilt werden.

Ausführen der Erweiterung

Um die Erweiterung auszuführen und zu testen, öffnen Sie Azure Data Studio, und öffnen Sie dann die Befehlspalette, indem Sie STRG+UMSCHALT+P drücken. Suchen Sie nach dem Befehl Extensions: Install from VSIX (Erweiterungen: Aus VSIX installieren), und navigieren Sie zu dem Ordner, der die neue Erweiterung enthält.

Ihre Erweiterung sollte nun in Ihrem Erweiterungsbereich in Azure Data Studio angezeigt werden. Öffnen Sie die Befehlspalette noch mal. Dort sehen Sie den neuen Befehl, den Sie mit der Erweiterung erstellt haben: Launch Notebook: Test Notebook (Notebook starten: Notebook testen). Bei der Ausführung sollte das Jupyter Book geöffnet werden, das wir mit unserer Erweiterung gepackt haben.

Herzlichen Glückwunsch! Sie haben Ihre erste Jupyter Notebook-Erweiterung entwickelt und können sie jetzt bereitstellen.

Veröffentlichen der Erweiterung im Marketplace

Der Marketplace für Azure Data Studio-Erweiterungen befindet sich in Bearbeitung. Zum Veröffentlichen hosten Sie die Erweiterung VSIX an einem beliebigen Ort, z. B. auf einer GitHub-Releaseseite. Senden Sie anschließend einen Pull Request, der diese JSON-Datei mit Ihren Erweiterungsinformationen aktualisiert.

Nächste Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

• Erstellen eines Erweiterungsprojekts
• Installieren des Erweiterungs-Generators
• Entwickeln einer Notebookerweiterung
• Erstellen der Erweiterung
• Packen der Erweiterung
• Veröffentlichen der Erweiterung im Marketplace

Hoffentlich hat Sie dieser Artikel dazu inspiriert, selbst eine Erweiterung für Azure Data Studio zu erstellen.

Wenn Sie eine Idee haben, aber nicht sicher sind, wie Sie anfangen sollen, erstellen Sie ein Issue, oder senden Sie einen Tweet an das Team unter azuredatastudio.

Weitere Informationen finden Sie im Visual Studio Code-Erweiterungsleitfaden. Dieser enthält alle vorhandenen APIs und Muster.