Ein WvdS Add-in wird als .wvdsx-Datei ausgeliefert. Diese Datei ist ein gewöhnliches ZIP-Archiv mit einer festgelegten inneren Struktur. Der Dateiname folgt dem Schema {publisher}.{name}-{version}.wvdsx, also beispielsweise wvds.assets-manager-1.2.0.wvdsx.
Das Format orientiert sich am Prinzip der VSIX-Pakete aus dem VSCode-Ökosystem. Es bündelt alles, was der Host braucht, um ein Add-in zu installieren und zu betreiben: Manifest, Binaries, Medien, Übersetzungen und Dokumentation. Der Benutzer installiert das Paket über die Kommandozeile oder per Drag-and-Drop in die Erweiterungsverwaltung.
Zurück zur Übersicht.
wvds.assets-manager-1.2.0.wvdsx
│
├── plugin.json ← Manifest (Pflicht)
├── README.md ← Dokumentation für die Erweiterungsliste
├── CHANGELOG.md ← Änderungshistorie
├── LICENSE ← Lizenzdatei
│
├── bin/ ← Binaries
│ ├── AssetsManager.dll ← Haupt-DLL des Add-ins
│ ├── libssl-3.dll ← Abhängigkeit (z.B. OpenSSL)
│ └── libcrypto-3.dll ← Abhängigkeit
│
├── media/ ← Icons und Grafiken
│ ├── asset-open.svg ← Command-Icon
│ ├── asset-list.svg ← Command-Icon
│ └── navigator.svg ← Sidebar-View-Icon
│
├── themes/ ← Theme-Dateien (optional)
│ └── highlight.json ← Skin-Token-Definitionen
│
├── package.nls.json ← Standard-Übersetzung (Fallback)
├── package.nls.de.json ← Deutsche Übersetzung
├── package.nls.en.json ← Englische Übersetzung
│
└── data/ ← Beliebige Daten des Add-ins
└── templates/
└── default-asset.json ← Vorlagen, Konfigurationen etc.
Nur eine einzige Datei ist zwingend erforderlich: plugin.json. Ohne dieses Manifest kann der Host das Paket nicht interpretieren. Alle anderen Dateien sind optional, werden aber dringend empfohlen.
Das Manifest liegt im Wurzelverzeichnis des Archivs. Es beschreibt das Add-in vollständig: Identität, Kompatibilität, Aktivierung und Contributions. Der Host liest diese Datei zuerst und entscheidet anhand ihres Inhalts, ob das Add-in installiert werden kann.
Das main-Feld im Manifest verweist auf die DLL relativ zum Wurzelverzeichnis des Archivs. Im Beispiel oben wäre der Wert „main“: „bin/AssetsManager.dll“. Der Host löst diesen Pfad nach der Installation relativ zum Installationsverzeichnis auf.
Die README-Datei wird in der Erweiterungsliste als Detailbeschreibung angezeigt. Sie sollte erklären, was das Add-in tut, welche Voraussetzungen es hat und wie man es konfiguriert. Markdown-Formatierung wird vom Host gerendert.
Die Haupt-DLL und alle ihre Abhängigkeiten gehören in das bin/-Verzeichnis. Der Host setzt das Arbeitsverzeichnis vor dem Laden auf diesen Pfad, damit Windows die Abhängigkeiten findet.
Typische Abhängigkeiten sind Bibliotheken wie OpenSSL, SQLite oder andere native DLLs, die das Add-in zur Laufzeit benötigt. Diese Abhängigkeiten werden im Paket mitgeliefert, nicht auf dem Zielsystem vorausgesetzt. Das stellt sicher, dass das Add-in auf jedem Rechner funktioniert, unabhängig davon, was dort installiert ist.
Wichtig: Die DLL muss mit derselben Free Pascal Compiler-Version gebaut werden, die auch der Host verwendet. Der ABI-Handshake (siehe Architektur) prüft das automatisch und lehnt inkompatible Binaries ab.
Icons und Grafiken für Commands, Toolbar-Buttons und Sidebar-Views gehören in das media/-Verzeichnis. Der Host unterstützt SVG- und PNG-Dateien. SVG wird bevorzugt, weil es bei verschiedenen DPI-Einstellungen scharf bleibt.
Die Pfade im Manifest sind relativ zum Paketwurzel, also media/asset-open.svg und nicht ./media/asset-open.svg oder ein absoluter Pfad.
NLS-Dateien (Natural Language Support) liegen im Wurzelverzeichnis des Pakets. Sie ermöglichen die Übersetzung aller Texte, die im Manifest mit %schlüssel%-Platzhaltern versehen sind.
package.nls.json — Standard-Übersetzung (Fallback, wenn keine passende Sprache gefunden wird)package.nls.de.json — Deutsche Übersetzungpackage.nls.en.json — Englische Übersetzung
Der Host wählt die passende Datei anhand der konfigurierten Anwendungssprache aus. Fehlt eine Übersetzung, greift er auf package.nls.json zurück. Ausführliche Dokumentation zur Mehrsprachigkeit steht unter Lokalisierung.
Theme-Add-ins (kind: theme) oder Add-ins, die zusätzlich zum Code ein eigenes Theme mitbringen, legen ihre Theme-Dateien im themes/-Verzeichnis ab. Der Pfad wird im Manifest unter contributes.themes[].path referenziert.
Theme-Dateien enthalten Farbdefinitionen nach dem Skin-Vertrag. Sie können die Palette, Tokens, Zustandsfarben und Größen-Properties des Hosts überschreiben.
Das data/-Verzeichnis steht für beliebige Dateien zur Verfügung, die das Add-in zur Laufzeit benötigt: Vorlagen, Standardkonfigurationen, Beispieldaten oder andere Ressourcen. Der Pfad zu diesem Verzeichnis steht dem Add-in über IExtensionContext.ExtensionPath zur Verfügung.
Die Installation eines .wvdsx-Pakets erfolgt über die Kommandozeile:
wdochost --install-extension wvds.assets-manager-1.2.0.wvdsx
Der Host führt dabei folgende Schritte durch:
~/.wvdsx/extensions/wvds.assets-manager/).plugin.json wird geparst und validiert.engineVersion wird gegen die Host-Version geprüft.dllChecksum gesetzt ist, wird die DLL gehasht und verglichen.Die Deinstallation entfernt das Verzeichnis und den Registry-Eintrag:
wdochost --uninstall-extension wvds.assets-manager
Für wiederholbare Builds empfiehlt sich ein Build-Wvdsx.ps1-Script, das Kompilierung und Paketierung automatisiert. Das folgende Muster zeigt die wesentlichen Schritte:
# --- 1. Kompilieren --- $buildResult = Invoke-LazbuildProject -ProjectDir $PSScriptRoot if (-not $buildResult) { Write-Error 'Build failed.'; return } # --- 2. Version aus plugin.json lesen --- $manifest = Get-Content (Join-Path $PSScriptRoot 'plugin.json') -Raw | ConvertFrom-Json $version = $manifest.version $packageName = "$($manifest.publisher).$($manifest.name)-$version.wvdsx" # --- 3. Staging-Verzeichnis aufbauen --- $staging = Join-Path $env:TEMP "wvdsx-staging-$(Get-Random)" New-Item -Path $staging -ItemType Directory | Out-Null Copy-Item (Join-Path $PSScriptRoot 'plugin.json') $staging Copy-Item (Join-Path $PSScriptRoot 'package.nls*.json') $staging $binDir = Join-Path $staging 'bin' New-Item -Path $binDir -ItemType Directory | Out-Null Copy-Item $dllPath (Join-Path $binDir 'MyPlugin.dll') # media/, sql/, themes/ etc. nach Bedarf kopieren # --- 4. ZIP erstellen --- $outPath = Join-Path $PSScriptRoot "dist\$packageName" Compress-Archive -Path "$staging\*" -DestinationPath $outPath -Force # --- 5. Prüfsumme ausgeben --- $hash = (Get-FileHash $outPath -Algorithm SHA256).Hash.ToLower() Write-Host "Package: $outPath" Write-Host "SHA256: $hash" # --- 6. Aufräumen --- Remove-Item $staging -Recurse -Force
Das erzeugte .wvdsx-Paket kann über die Kommandozeile installiert oder direkt in das Benutzer-Erweiterungsverzeichnis entpackt werden.
bin/ oder media/ sind erlaubt, aber selten nötig.