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 Übersetzung
• package.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:

1. Entpacken — Das ZIP-Archiv wird in das Benutzer-Erweiterungsverzeichnis entpackt (~/.wvdsx/extensions/wvds.assets-manager/).
2. Manifest lesen — plugin.json wird geparst und validiert.
3. Kompatibilität prüfen — engineVersion wird gegen die Host-Version geprüft.
4. Prüfsumme verifizieren — Wenn dllChecksum gesetzt ist, wird die DLL gehasht und verglichen.
5. Registrieren — Das Add-in wird in die Extension-Registry eingetragen und steht beim nächsten Start zur Verfügung.

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.

• Dateinamen im Paket sind durchgehend kleingeschrieben und verwenden Bindestriche als Trennzeichen.
• Die Verzeichnisstruktur ist flach gehalten. Verschachtelte Unterverzeichnisse unter bin/ oder media/ sind erlaubt, aber selten nötig.
• Keine temporären Dateien, Build-Artefakte oder IDE-Konfigurationen in das Paket aufnehmen.
• Das Paket sollte so klein wie möglich gehalten werden. Große Binaries (Datenbanken, vortrainierte Modelle) gehören nicht in das Paket, sondern werden bei Bedarf zur Laufzeit nachgeladen.

Weiter zum SDK oder zurück zur Übersicht.