====== WvdS Add-in Host ======

Der WvdS Add-in Host (WBASH) ist die Laufzeitumgebung für native Erweiterungen der Wolf Business Application Shell. Er stellt ein dokumentenorientiertes Anwendungsgerüst bereit, in das Drittanbieter eigene Funktionalität einbringen, ohne die Shell selbst verändern zu müssen.

Dieses Kapitel beschreibt die Architektur, die Verträge und die Werkzeuge, die ein Add-in-Entwickler kennen muss, um eine Erweiterung zu erstellen, zu paketieren und zu verteilen.

===== Warum ein eigenes Add-in-Modell =====

Viele Anwendungen erlauben Erweiterungen über einfache DLL-Plugins: Der Host lädt eine Bibliothek, ruft eine Funktion auf und hofft, dass alles zusammenpasst. In der Praxis führt das zu Problemen. Unterschiedliche Compiler-Versionen erzeugen inkompatible Binaries. Fehlende Versionierung macht Updates riskant. Und wenn ein Plugin abstürzt, reißt es die gesamte Anwendung mit.

WBASH geht einen anderen Weg. Jedes Add-in wird als signiertes Paket ausgeliefert, das ein maschinenlesbares Manifest enthält. Der Host liest dieses Manifest, prüft Kompatibilität und Signatur, registriert die deklarierten Beiträge und lädt die eigentliche DLL erst dann, wenn sie tatsächlich gebraucht wird. Dadurch startet die Anwendung schnell, bleibt stabil und behält die Kontrolle über ihre Oberfläche.

Das Ergebnis ist ein System, das Drittanbietern echte Erweiterbarkeit bietet, gleichzeitig aber sicherstellt, dass die Shell konsistent, performant und wartbar bleibt.

===== Grundprinzipien =====

Das Add-in-Modell baut auf vier Grundprinzipien auf, die sich durch alle Schichten ziehen.

=== Manifest vor Code ===

Ein Add-in deklariert seine Fähigkeiten in einer JSON-Datei, bevor auch nur eine Zeile Code ausgeführt wird. Der Host weiß dadurch sofort, welche Menüpunkte, Toolbar-Buttons, Seitenleisten und Dokumenttypen ein Add-in beisteuert. Die Oberfläche steht vollständig, ohne dass eine DLL geladen werden muss. Erst wenn der Benutzer tatsächlich eine Funktion aufruft, wird das Add-in aktiviert. Dieses Prinzip hält den Start schnell und den Speicherverbrauch niedrig.

=== Host kontrolliert die Shell ===

Die Shell gehört dem Host. Dokument-Tabs, deren Aktivierung, Titel, Icon und Dirty-State, das Schließen von Dokumenten, die Layout-Persistenz, der Menü- und Toolbar-Merge sowie der Kontextwechsel zwischen Dokumenten — all das liegt in der Verantwortung des Hosts. Ein Add-in liefert Inhalt und Verhalten, niemals die Shell-Mechanik selbst. Dadurch bleibt die Anwendung konsistent, unabhängig davon, wie viele Add-ins installiert sind.

=== Klare Binärschnittstelle ===

Die Kommunikation zwischen Host und Add-in läuft über COM-artige Interfaces, nicht über rohe Strings oder dynamische Arrays. Jedes Add-in exportiert genau zwei Funktionen: eine für den ABI-Handshake und eine für die Plugin-Erzeugung. Der Handshake prüft Magic-Number, ABI-Version und Compiler-Version, bevor überhaupt ein Objekt erzeugt wird. Passt etwas nicht zusammen, wird das Add-in gar nicht erst geladen. Das verhindert Abstürze durch inkompatible Binaries zuverlässig.

=== Fehlerisolierung ===

Jeder Aufruf in Add-in-Code ist in eine Schutzschicht eingebettet. Wirft ein Add-in eine Exception, fängt der Host sie ab, protokolliert den Fehler und fährt mit den übrigen Add-ins fort. Nach drei aufeinanderfolgenden Fehlern deaktiviert der Host das betroffene Add-in automatisch und informiert den Benutzer. Ein fehlerhaftes Add-in kann die Anwendung nicht zum Absturz bringen.

===== Dokumentation =====

Die Dokumentation gliedert sich in folgende Bereiche:

  * **[[architektur]]** — Das Zwei-Ebenen-Modell aus Metadaten und Runtime, der Host-Vertrag und die Abgrenzung der Verantwortlichkeiten.
  * **[[lifecycle]]** — Der vollständige Lebenszyklus eines Add-ins: Scan, Resolve, Register, Activate — mit Log-Beispielen und Troubleshooting.
  * **[[manifest]]** — Vollständige Referenz des plugin.json-Manifests mit allen Feldern und Contribution-Typen.
  * **[[paketformat]]** — Aufbau des .wvdsx-Pakets, die ZIP-Struktur, Build-Script und was hineingehört.
  * **[[sdk:start]]** — SDK-Übersicht mit Bootstrap, IHost-API, Lifecycle und Service-Referenz.
  * **[[contributions:start]]** — Alle visuellen Contribution-Typen: Commands, Menüs, Toolbar, Sidebar, StatusBar, Keybindings.
  * **[[skin-contract]]** — Der Skin-Vertrag: Farbpalette, semantische Tokens, Zustandsabbildung und Größen-Properties.
  * **[[sicherheit]]** — Signatur, Berechtigungen und das Capability-Modell.
  * **[[lokalisierung]]** — Mehrsprachigkeit über NLS-Bundles.
  * **[[sdk:script-host]]** — ScriptHost & Host-Contract: PowerShell-Scripts als Commands, ##wvds-Protokoll und WvdSHostContract-Modul.
  * **[[cli]]** — Kommandozeilen-Referenz für Installation, Deinstallation und Debugging.

===== Tutorials =====

  * **[[tutorials:hello-world]]** — Einstieg: Ein minimales Add-in von Grund auf.
  * **[[tutorials:document-view]]** — Ein Dokument-Tab mit Factory, Dirty-State und Speichern.
  * **[[tutorials:sidebar-view]]** — Ein Sidebar-Panel mit TreeView, Accordion und Kontextmenü.
  * **[[tutorials:menu-merge]]** — Cross-Plugin Menü- und Toolbar-Integration mit Merge-Verfahren.
  * **[[tutorials:script-command]]** — Einen Script-Command erstellen und mit dem Host kommunizieren.
  * **[[tutorials:command-routing]]** — Command-Routing über den ShellCommandRouter: Warum Builtin-Handler Commands feuern statt Views zu erzeugen.