Creare un'estensione di tipo notebook di Jupyter

Questa esercitazione illustra come creare una nuova estensione di Azure Data Studio di tipo notebook di Jupyter. L'estensione rende disponibile un Jupyter Notebook di esempio che può essere aperto ed eseguito in Azure Data Studio.

In questo articolo viene spiegato come:

• Creare un progetto di estensione.
• Installare il generatore di estensioni.
• Creare l'estensione di tipo notebook.
• Eseguire l'estensione.
• Creare il pacchetto dell'estensione.
• Pubblicare l'estensione nel marketplace.

API usate

• azdata.nb.showNotebookDocument

Casi d'uso dell'estensione

Esistono diversi motivi per cui può essere utile creare un'estensione di tipo notebook:

• Condividere documentazione interattiva
• Salvare e avere accesso costante a tale notebook
• Presentare problemi di scrittura del codice che gli utenti possono seguire
• Controllare le versioni e tenere traccia degli aggiornamenti dei notebook

Prerequisiti

Azure Data Studio si basa sullo stesso framework di Visual Studio Code, quindi le estensioni per Azure Data Studio vengono compilate usando Visual Studio Code. Per iniziare, sono necessari i componenti seguenti:

• Node.js installato e disponibile in $PATH. Node.js include npm, lo strumento di gestione dei pacchetti di Node.js, che viene usato per installare il generatore di estensioni.
• Visual Studio Code per eseguire il debug dell'estensione.
• Assicurarsi che azuredatastudio sia nel percorso. Per Windows, assicurarsi di scegliere l'opzione Aggiungi a PATH in setup.exe. Per Mac o Linux, eseguire il comando Install 'azuredatastudio' in PATH dal riquadro comandi in Azure Data Studio.

Installare il generatore di estensioni

Per semplificare il processo di creazione delle estensioni, abbiamo creato un generatore di estensioni con Yeoman. Per installarlo, eseguire il comando seguente dal prompt dei comandi:

npm install -g yo generator-azuredatastudio

Creare l'estensione

Per creare un'estensione:

1. Avviare il generatore di estensioni con il comando seguente:

   yo azuredatastudio

2. Scegliere New Notebooks (Individual) (Nuovi notebook - singoli) nell'elenco dei tipi di estensione.

   

3. Seguire la procedura per specificare il nome dell'estensione. Per questa esercitazione, usare Test Notebook. Immettere quindi un nome di autore. Per questa esercitazione usare Microsoft. Infine aggiungere una descrizione.

A questo punto, è possibile procedere in modi diversi. È possibile aggiungere notebook di Jupyter già creati oppure usare i notebook di esempio forniti tramite il generatore.

Per questa esercitazione verrà usato un notebook Python di esempio:

Se sono presenti notebook che si è interessati a distribuire, rispondere che esistono notebook da distribuire. Specificare il percorso di file assoluto in cui si trovano tutti i notebook o i file markdown.

Il completamento dei passaggi precedenti consente di creare una nuova cartella con il notebook di esempio. Aprire la cartella in Visual Studio Code e si è pronti per distribuire la nuova estensione per i notebook.

Informazioni sull'estensione

Il progetto dovrebbe essere simile al seguente:

Il file vsc-extension-quickstart.md fornisce informazioni di riferimento sui file importanti. Il file README.md è la posizione in cui è possibile fornire la documentazione per la nuova estensione. Si notino i file package.json, notebook.ts e pySample.ipynb.

Se sono presenti file o cartelle che non si vuole pubblicare, è possibile includere i relativi nomi nel file .vscodeignore.

Verrà ora esaminato il file notebook.ts per comprendere le funzioni dell'estensione appena creata.

// 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.
}

Questa è la funzione principale in che viene chiamata ogni volta che si esegue l'estensione tramite il comando Launch Notebooks: Test Notebook.This is the main function in notebook.ts that's called whenever we run our extension through the command Launch Notebooks: Test Notebooks. Il nuovo comando verrà creato usando l'API vscode.commands.registerCommand. La definizione seguente all'interno delle parentesi graffe è il codice che viene eseguito ogni volta che viene chiamato il comando. Ogni notebook trovato dalla funzione processNotebooks viene aperto in Azure Data Studio tramite azdata.nb.showNotebookDocument.

Il package.json file svolge anche un ruolo importante nella registrazione del comando Launch Notebooks: Test Notebook.

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

È presente un evento di attivazione per il comando e sono stati anche aggiunti punti di aggiunta contributi specifici. Questi punti di aggiunta contributi vengono visualizzati nel marketplace in cui vengono pubblicate le estensioni, quando gli utenti esaminano l'estensione. Se si vogliono aggiungere altri comandi, assicurarsi di aggiungerli nel campo activationEvents. Per altre opzioni, vedere Eventi di attivazione.

Creare il pacchetto dell'estensione

Per condividere l'estensione con altri utenti, è necessario inserirla in un pacchetto costituito da un unico file. L'estensione può essere pubblicata nel marketplace delle estensioni di Azure Data Studio o condivisa all'interno del team o della community. A tale scopo, è necessario installare un altro pacchetto npm dalla riga di comando.

npm install -g vsce

Modificare il file README.md nel modo desiderato. Passare quindi alla directory di base dell'estensione ed eseguire vsce package. Facoltativamente, è possibile collegare un repository con l'estensione o continuare senza. Per aggiungerne uno, aggiungere una riga simile al file package.json.

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

Dopo aver aggiunto queste righe, viene creato un file my test-notebook-0.0.1.vsix e si è pronti per l'installazione e la condivisione.

Eseguire l'estensione

Per eseguire e testare l'estensione, aprire Azure Data Studio e aprire il riquadro comandi selezionando CTRL+MAIUSC+P. Trovare il comando Estensioni: installare da VSIX e passare alla cartella che contiene la nuova estensione.

L'estensione dovrebbe ora comparire nel pannello delle estensioni in Azure Data Studio. Aprire di nuovo il riquadro comandi e si troverà il nuovo comando creato con l'estensione Launch Book: Test Book. Eseguendo questo comando verrà aperto il book Jupyter per il quale è stato creato un pacchetto con l'estensione.

Congratulazioni. È stata creata la prima estensione per notebook di Jupyter ed è ora possibile distribuirla.

Pubblicare l'estensione nel marketplace

Il marketplace delle estensioni di Azure Data Studio è in costruzione. Per pubblicare, ospitare l'estensione VSIX in una posizione qualsiasi, ad esempio, in una pagina di rilascio di GitHub. Inviare quindi una richiesta pull che aggiorna questo file JSON con le informazioni sull'estensione.

Passaggi successivi

Questa esercitazione ha descritto come:

• Creare un progetto di estensione.
• Installare il generatore di estensioni.
• Creare l'estensione di tipo notebook.
• Creare l'estensione.
• Creare il pacchetto dell'estensione.
• Pubblicare l'estensione nel marketplace.

Ci auguriamo che la lettura di questo articolo sia di ispirazione per creare un'estensione personalizzata per Azure Data Studio.

Se si ha un'idea, ma non si è certi di come iniziare, aprire un problema o inviare un tweet al team: azuredatastudio.

Per altre informazioni, vedere la Guida delle estensioni di Visual Studio Code che documenta tutte le API e i modelli esistenti.