Virtuelle Arbeitsbereiche

Erweiterungen wie die GitHub Repositories-Erweiterung öffnen VS Code für einen oder mehrere Ordner, die von einem Dateisystemanbieter unterstützt werden. Wenn eine Erweiterung einen Dateisystemanbieter implementiert, befinden sich die Arbeitsbereichsressourcen möglicherweise nicht auf der lokalen Festplatte, sondern sind virtuell, auf einem Server oder in der Cloud gespeichert, und Bearbeitungsvorgänge finden dort statt.

Diese Konfiguration wird als virtueller Arbeitsbereich bezeichnet. Wenn ein virtueller Arbeitsbereich in einem VS Code-Fenster geöffnet ist, wird dies durch eine Beschriftung in der Remote-Anzeige unten links angezeigt, ähnlich wie bei anderen Remote-Entwicklungsfenstern.

Nicht alle Erweiterungen können mit virtuellen Ressourcen arbeiten und benötigen möglicherweise Ressourcen auf der Festplatte. Einige Erweiterungen verwenden Tools, die einen Festplattenzugriff benötigen, synchronen Dateizugriff erfordern oder nicht über die notwendigen Dateisystemabstraktionen verfügen. In diesen Fällen zeigt VS Code dem Benutzer in einem virtuellen Arbeitsbereich an, dass er in einem eingeschränkten Modus läuft und dass einige Erweiterungen deaktiviert sind oder mit eingeschränkter Funktionalität arbeiten.

Im Allgemeinen möchten Benutzer, dass so viele Erweiterungen wie möglich in virtuellen Arbeitsbereichen funktionieren und eine gute Benutzererfahrung beim Durchsuchen und Bearbeiten von Remote-Ressourcen haben. Diese Anleitung zeigt, wie Erweiterungen gegen virtuelle Arbeitsbereiche testen können, beschreibt Änderungen, um sie für virtuelle Arbeitsbereiche nutzbar zu machen, und stellt die Fähigkeitseigenschaft virtualWorkspaces vor.

Die Änderung einer Erweiterung, um mit virtuellen Arbeitsbereichen zu arbeiten, ist auch ein wichtiger Schritt für die gute Arbeit in VS Code für das Web. VS Code für das Web läuft vollständig im Browser, und Arbeitsbereiche sind aufgrund der Browser-Sandbox virtuell. Weitere Informationen finden Sie im Leitfaden Web-Erweiterungen.

Ist meine Erweiterung betroffen?

Wenn eine Erweiterung keinen ausführbaren Code hat, sondern rein deklarativ ist, wie z. B. Themes, Tastenkombinationen, Snippets oder Grammatik-Erweiterungen, kann sie in einem virtuellen Arbeitsbereich ausgeführt werden und es sind keine Änderungen erforderlich.

Erweiterungen mit Code, d. h. Erweiterungen, die einen main-Einstiegspunkt definieren, erfordern eine Überprüfung und möglicherweise eine Änderung.

Führen Sie Ihre Erweiterung in einem virtuellen Arbeitsbereich aus

Installieren Sie die GitHub Repositories-Erweiterung und führen Sie den Befehl GitHub-Repository öffnen... aus der Befehlspalette aus. Der Befehl zeigt eine Schnellauswahl an, in die Sie jede GitHub-URL einfügen oder nach einem bestimmten Repository oder Pull Request suchen können.

Dadurch wird ein VS Code-Fenster für einen virtuellen Arbeitsbereich geöffnet, in dem alle Ressourcen virtuell sind.

Überprüfen Sie, ob der Erweiterungscode für virtuelle Ressourcen bereit ist

Die VS Code API-Unterstützung für virtuelle Dateisysteme gibt es schon seit geraumer Zeit. Sie können sich die API für Dateisystemanbieter ansehen.

Ein Dateisystemanbieter wird für ein neues URI-Schema (z. B. vscode-vfs) registriert, und Ressourcen in diesem Dateisystem werden durch URIs mit diesem Schema dargestellt (vscode-vfs://github/microsoft/vscode/package.json).

Prüfen Sie, wie Ihre Erweiterung mit URIs umgeht, die von den VS Code-APIs zurückgegeben werden

• Gehen Sie niemals davon aus, dass das URI-Schema file ist. URI.fsPath kann nur verwendet werden, wenn das URI-Schema file ist.
• Achten Sie auf Verwendungen des fs Node.js-Moduls für Dateisystemoperationen. Verwenden Sie nach Möglichkeit die API vscode.workspace.fs, die an den entsprechenden Dateisystemanbieter delegiert.
• Prüfen Sie auf Drittanbieterkomponenten, die von einem fs-Zugriff abhängen (z. B. ein Sprachserver oder ein Node.js-Modul).
• Wenn Sie ausführbare Dateien und Aufgaben über Befehle ausführen, prüfen Sie, ob diese Befehle in einem virtuellen Arbeitsbereichsfenster sinnvoll sind oder ob sie deaktiviert werden sollten.

Signalisieren Sie, ob Ihre Erweiterung virtuelle Arbeitsbereiche verarbeiten kann

Die Eigenschaft virtualWorkspaces unter capabilities in package.json wird verwendet, um zu signalisieren, ob eine Erweiterung mit virtuellen Arbeitsbereichen funktioniert.

Keine Unterstützung für virtuelle Arbeitsbereiche

Das folgende Beispiel deklariert, dass eine Erweiterung virtuelle Arbeitsbereiche nicht unterstützt und von VS Code in diesem Setup nicht aktiviert werden sollte.

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": false,
      "description": "Debugging is not possible in virtual workspaces."
    }
  }
}

Teilweise und vollständige Unterstützung für virtuelle Arbeitsbereiche

Wenn eine Erweiterung mit virtuellen Arbeitsbereichen funktioniert oder teilweise funktioniert, sollte sie "virtualWorkspaces": true definieren.

{
  "capabilities": {
    "virtualWorkspaces": true
  }
}

Wenn eine Erweiterung funktioniert, aber eine eingeschränkte Funktionalität aufweist, sollte sie dem Benutzer die Einschränkung erklären

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": "limited",
      "description": "In virtual workspaces, resolving and finding references across files is not supported."
    }
  }
}

Die Beschreibung wird in der Erweiterungsansicht angezeigt

Die Erweiterung sollte dann die Funktionen deaktivieren, die in einem virtuellen Arbeitsbereich nicht unterstützt werden, wie unten beschrieben.

Standard

"virtualWorkspaces": true ist der Standard für alle Erweiterungen, die die Fähigkeit virtualWorkspaces noch nicht ausgefüllt haben.

Beim Testen von virtuellen Arbeitsbereichen haben wir jedoch eine Liste von Erweiterungen zusammengestellt, die unserer Meinung nach in virtuellen Arbeitsbereichen deaktiviert werden sollten. Die Liste finden Sie in Issue #122836. Diese Erweiterungen haben standardmäßig "virtualWorkspaces": false.

Natürlich sind Erweiterungsautoren besser in der Lage, diese Entscheidung zu treffen. Die virtualWorkspaces-Fähigkeit in package.json einer Erweiterung überschreibt unseren Standard, und wir werden unsere Liste schließlich einstellen.

Funktionalität deaktivieren, wenn ein virtueller Arbeitsbereich geöffnet wird

Befehle und Ansichtskonfigurationen deaktivieren

Die Verfügbarkeit von Befehlen und Ansichten sowie viele andere Beiträge können über Kontextschlüssel in When-Klauseln gesteuert werden.

Der Kontextschlüssel virtualWorkspace wird gesetzt, wenn alle Arbeitsbereichsordner auf virtuellen Dateisystemen liegen. Das folgende Beispiel zeigt den Befehl npm.publish nur in der Befehlspalette an, wenn nicht in einem virtuellen Arbeitsbereich.

{
  "menus": {
    "commandPalette": [
      {
        "command": "npm.publish",
        "when": "!virtualWorkspace"
      }
    ]
  }
}

Der Kontextschlüssel resourceScheme wird auf das URI-Schema des aktuell ausgewählten Elements im Datei-Explorer oder des im Editor geöffneten Elements gesetzt.

Im folgenden Beispiel wird der Befehl npm.runSelectedScript nur im Kontextmenü des Editors angezeigt, wenn die zugrunde liegende Ressource auf der lokalen Festplatte liegt.

{
  "menus": {
    "editor/context": [
      {
        "command": "npm.runSelectedScript",
        "when": "resourceFilename == 'package.json' && resourceScheme == file"
      }
    ]
  }
}

Virtuelle Arbeitsbereiche programmatisch erkennen

Um zu prüfen, ob der aktuelle Arbeitsbereich aus Nicht-file-Schemata besteht und virtuell ist, können Sie den folgenden Quellcode verwenden.

const isVirtualWorkspace =
  workspace.workspaceFolders &&
  workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

Spracherweiterungen und virtuelle Arbeitsbereiche

Was sind die Erwartungen an die Sprachunterstützung für virtuelle Arbeitsbereiche?

Es ist nicht realistisch, dass alle Erweiterungen vollständig mit virtuellen Ressourcen arbeiten können. Viele Erweiterungen verwenden externe Tools, die einen synchronen Dateizugriff und Dateien auf der Festplatte benötigen. Daher ist es in Ordnung, nur eine eingeschränkte Funktionalität bereitzustellen, wie z. B. die Basis- und die Einzeldatei-Unterstützung, wie unten aufgeführt.

A. Grundlegende Sprachunterstützung

• TextMate-Tokenisierung und -Farbgebung
• Sprachspezifische Bearbeitungsunterstützung: Klammerpaare, Kommentare, Regeln beim Eingeben, Faltungsmarkierungen
• Code-Schnipsel

B. Einzeldatei-Sprachunterstützung

• Dokumentsymbole (Gliederung), Faltung, Auswahlbereiche
• Dokumenthervorhebungen, semantische Hervorhebungen, Dokumentfarben
• Vervollständigungen, Hover, Signaturhilfe, Referenzen/Deklarationen finden basierend auf Symbolen in der aktuellen Datei und auf statischen Sprachbibliotheken
• Formatierung, Verknüpfte Bearbeitung
• Syntaxvalidierung und semantische Validierung derselben Datei und Code Actions

C. Dateiübergreifende, arbeitsbereichsbewusste Sprachunterstützung

• Referenzen über Dateien hinweg
• Arbeitsbereichssymbole
• Validierung aller Dateien im Arbeitsbereich/Projekt

Die reichhaltigen Spracherweiterungen, die mit VS Code geliefert werden (TypeScript, JSON, CSS, HTML, Markdown), sind bei der Arbeit mit virtuellen Ressourcen auf die Unterstützung einzelner Dateien beschränkt.

Deaktivieren einer Spracherweiterung

Wenn die Arbeit an einer einzelnen Datei keine Option ist, können Spracherweiterungen auch entscheiden, die Erweiterung in einem virtuellen Arbeitsbereich zu deaktivieren.

Wenn Ihre Erweiterung sowohl Grammatiken als auch eine reichhaltige Sprachunterstützung bereitstellt, die deaktiviert werden muss, werden auch die Grammatiken deaktiviert. Um dies zu vermeiden, können Sie eine grundlegende Spracherweiterung (Grammatiken, Sprachkonfiguration, Snippets) getrennt von der reichhaltigen Sprachunterstützung erstellen und zwei Erweiterungen haben.

• Die grundlegende Spracherweiterung hat "virtualWorkspaces": true und stellt die Sprach-ID, die Konfiguration, die Grammatik und die Snippets bereit.
• Die reichhaltige Spracherweiterung hat "virtualWorkspaces": false und enthält die main-Datei. Sie trägt zur Sprachunterstützung und zu Befehlen bei und hat eine Erweiterungsabhängigkeit (extensionDependencies) von der grundlegenden Spracherweiterung. Die reichhaltige Spracherweiterung sollte die Erweiterungs-ID der etablierten Erweiterung beibehalten, damit der Benutzer die volle Funktionalität durch die Installation einer einzigen Erweiterung weiterhin nutzen kann.

Sie können diesen Ansatz bei den integrierten Spracherweiterungen sehen, wie z. B. JSON, das aus einer JSON-Erweiterung und einer JSON-Sprachfeature-Erweiterung besteht.

Diese Trennung hilft auch bei Nicht vertrauenswürdigen Arbeitsbereichen, die im Eingeschränkten Modus ausgeführt werden. Reichhaltige Spracherweiterungen erfordern oft Vertrauen, während grundlegende Sprachfeatures in jeder Konfiguration ausgeführt werden können.

Sprachselektoren

Wenn Sie einen Anbieter für ein Sprachfeature registrieren (z. B. Vervollständigungen, Hover, Code Actions usw.), stellen Sie sicher, dass Sie die von dem Anbieter unterstützten Schemata angeben.

return vscode.languages.registerCompletionItemProvider(
  { language: 'typescript', scheme: 'file' },
  {
    provideCompletionItems(document, position, token) {
      // ...
    }
  }
);

Was ist mit der Unterstützung im Language Server Protocol (LSP) für den Zugriff auf virtuelle Ressourcen?

Es wird daran gearbeitet, die Unterstützung für Dateisystemanbieter in LSP zu integrieren. Verfolgen Sie dies in Issue #1264 des Language Server Protocol.