ConditionalCode

Eine leistungsstarke Visual Studio Code-Erweiterung zur Verwaltung und Kontrolle von bedingtem Code in Business Central-Anwendungen. Ermöglicht die einfache Verwaltung verschiedener Code-Versionen und Plattform-spezifischer Implementierungen.

Hauptfunktionen

1. Versions-Management

• Multi-Version Support: Verwalten Sie mehrere Versionen Ihrer Business Central-Anwendung in einem einzigen Projekt
• Version-Switching: Nahtloses Umschalten zwischen verschiedenen BC-Versionen (z.B. 26.0.0.0, 25.0.0.0)
• Plattform-spezifische Anpassungen: Separate Verwaltung von Cloud- und On-Premise-Versionen

2. Bedingter Code

• Intelligente Code-Markierung: Nutzen Sie //CondiCodeStart und //CondiCodeEnd zur Kennzeichnung versionsspezifischen Codes
• Automatische Code-Aktivierung: Code wird basierend auf der gewählten Version automatisch aktiviert/deaktiviert
• Syntax-Highlighting: Spezielle Hervorhebung der bedingten Code-Bereiche

3. App-Paket-Management

• Automatische App-Signierung: Integrierte Azure Key Vault-Unterstützung für App-Signierung
• Paket-Konvertierung: Tools zum Konvertieren zwischen .app und .zip Formaten
• Symbol-Extraktion: Automatische Extraktion von Symbolen und Dokumentation aus Apps

Detaillierte Einrichtung

Voraussetzungen

• Visual Studio Code
• Business Central AL Language Extension
• Azure Key Vault (für App-Signierung) Dokumentation

Installation

1. Marketplace Installation

   • Öffnen Sie Visual Studio Code
   • Drücken Sie Ctrl+Shift+X um den Extensions Marketplace zu öffnen
   • Geben Sie "ConditionalCode" in die Suchleiste ein
   • Klicken Sie auf die Extension von "profor software GmbH"
   • Klicken Sie auf den blauen "Install" Button
   • Neu starten Sie VS Code nach der Installation

2. Manuelle Installation

   • Laden Sie die neueste .vsix-Datei aus den Releases herunter
   • Öffnen Sie VS Code
   • Drücken Sie Ctrl+Shift+X für die Extensions-Ansicht
   • Klicken Sie auf das "..." Menü (Weitere Aktionen)
   • Wählen Sie "Install from VSIX..."
   • Navigieren Sie zur heruntergeladenen .vsix-Datei und wählen Sie diese aus
   • Bestätigen Sie die Installation und starten Sie VS Code neu

Erste Schritte

1. Projekt-Konfiguration a. Version erstellen:

   • Öffnen Sie die Command Palette mit Ctrl+Shift+P
   • Geben Sie "Version hinzufügen" ein (oder ConditionalCode.createversion)
   • Drücken Sie Enter

   b. Versions-Details eingeben:

   • Name der Version: Eindeutiger Name (z.B. "BC26")
   • BC Platform: Business Central Platform Version (z.B. "26.0.0.0")
   • BC Application: Application Version, meist identisch mit Platform
   • BC Target: Wählen Sie zwischen "Cloud" oder "OnPrem"
   • BC Runtime: .NET Runtime Version (z.B. "14.0")

   c. Workspace vorbereiten: Die Erweiterung erstellt und konfiguriert automatisch:

   • .vscode/ConditionalCode.json für Versionskonfigurationen
   • .allalpackages Ordner für gemeinsam genutzte Dependencies

   d. AL Objekt-Analyse: Die Erweiterung analysiert automatisch:

   • Tabellen und Tabellenbeziehungen
   • Seiten und Seitenerweiterungen
   • Codeunits und deren Abhängigkeiten
   • Reports und XMLPorts
   • Enumerationen und Schnittstellen

2. Code-Versionierung einrichten a. Code-Blöcke markieren:

   //CondiCodeStart VersionCompare(config.app.platform,'>=', '26.0.0.0') && TargetCompare('Cloud')
   procedure ModernCloudFeature()
   begin
       // Nur für BC 26.0 oder höher in der Cloud
   end;
   //CondiCodeEnd
   
   //CondiCodeStart VersionCompare(config.app.platform,'==', '25.0.0.0')
   procedure LegacyFeature()
   begin
       // Nur für BC 25.0
   end;
   //CondiCodeEnd
   
   //CondiCodeStart TargetCompare('OnPrem')
   procedure OnPremiseIntegration()
   begin
       // Nur für On-Premise-Installationen
   end;
   //CondiCodeEnd
   

   b. Bedingungs-Syntax und Operatoren:

   • Versions-Vergleiche:
     • VersionCompare(config.app.platform,'>=', '26.0.0.0') (exakte Version)
     • VersionCompare(config.app.platform,'>=', '26.0.0.0') (mindestens Version)
     • VersionCompare(config.app.platform,'<=', '26.0.0.0') (höchstens Version)
   • Target-Checks:
     • TargetCompare('Cloud')
     • TargetCompare('OnPrem')
   • Logische Operatoren:
     • && für UND-Verknüpfung
     • || für ODER-Verknüpfung
     • ! für NICHT

   c. Automatische Verwaltung:

   • Dynamische Aktivierung/Deaktivierung beim Versionswechsel
   • Automatische Kommentierung inaktiver Blöcke
   • Intelligentes Folding der Code-Bereiche
   • Integration mit AL-Objektverwaltung

3. App-Signing konfigurieren (optional)

   a. Umgebungsvariablen setzen:

   # Permanent für den Benutzer setzen
   [Environment]::SetEnvironmentVariable("KeyVault_clientId", "Ihre-Client-ID", "User")
   [Environment]::SetEnvironmentVariable("KeyVault_Secret", "Ihr-Client-Secret", "User")
   [Environment]::SetEnvironmentVariable("KeyVault_tenant", "Ihre-Tenant-ID", "User")
   
   # Optional: Test der Konfiguration
   $Env:KeyVault_clientId
   $Env:KeyVault_Secret
   $Env:KeyVault_tenant
   

Fortgeschrittene Funktionen

Automatisierte Build-Prozesse

1. App-Pakete erstellen

   • Versionsspezifische Builds mit ConditionalCode.buildversion
   • Automatische .app-Datei Generierung
   • Parallele Builds für mehrere Versions-Targets

2. AL-Kompilierung

   • Native AL-Compiler Integration
   • Intelligentes Dependency Management
   • Version-spezifische Compiler-Einstellungen
   • Build-Output-Verwaltung nach Version

3. Package-Management

   • .alpackages Synchronisation pro Version
   • .allalpackages für geteilte Dependencies
   • Automatisches Cleanup und Versionierung
   • App-zu-Zip Konvertierung für Analysen

4. Build-Konfiguration

   {
     "AllConfig": {
       "app": {
         "id": "com.yourcompany.app",
         "name": "Your App Name",
         "publisher": "Your Company",
         "brief": "App Description",
         "privacyStatement": "https://privacy.url",
         "EULA": "https://eula.url",
         "help": "https://help.url",
         "url": "https://company.url",
         "supportedLocales": ["de-DE", "en-US"],
         "dependencies": [],
         "idRanges": [{"from": 50000, "to": 50999}],
         "features": ["TranslationFile"]
       }
     },
     "Versions": {
       "BC26": {
         "app": {
           "version": "26.0.0.0",
           "platform": "Microsoft Dynamics 365 Business Central",
           "application": "26.0.0.0",
           "target": "Cloud",
           "runtime": "14.0"
         }
       }
     }
   }
   

Symbol-Management

• Automatische Generierung von Symbol-Referenzen
• Extraktion von Dokumentationskommentaren
• Verwaltung von Objekt-Beziehungen

Workspace-Organisation

• Automatische .gitignore-Konfiguration
• Verwaltung von versionsspezifischen Abhängigkeiten
• Strukturierte Arbeitsbereich-Organisation

Troubleshooting

Häufige Probleme und Lösungen

1. App-Signierung schlägt fehl

   a. Symptome:

   • Fehlermeldung beim Build-Prozess
   • Signatur wird nicht erstellt
   • Azure-Authentifizierungsfehler

   b. Lösungsschritte:

   # Überprüfen der Umgebungsvariablen
   $env:KeyVault_clientId
   $env:KeyVault_Secret
   $env:KeyVault_tenant
   
   

2. Versions-Konflikte

   a. Symptome:

   • Inkonsistente Code-Aktivierung
   • Unerwartetes Verhalten beim Version-Switching
   • Build-Fehler mit verschiedenen Versionen

   b. Diagnose:

   • Überprüfen Sie die ConditionalCode.json:

     {
       "Versions": {
         "BC26-Cloud": {
           "app": {
             "version": "26.0.0.0",
             "target": "Cloud"
           }
         }
       }
     }
     

   • Validieren Sie die bedingten Code-Blöcke:

     //CondiCodeStart VersionCompare(config.app.platform,'>=', '26.0.0.0')'
     // Dieser Code sollte eindeutig einer Version zugeordnet sein
     //CondiCodeEnd
     

3. Build-System-Probleme

   a. Compiler-Fehler:

   • Überprüfen Sie die AL Language Extension Version
   • Validieren Sie die Compiler-Einstellungen in launch.json
   • Stellen Sie sicher, dass alle Dependencies verfügbar sind

   b. Performance-Probleme:

   • Aktivieren Sie das Build-Logging:

     {
       "al.enableCodeAnalysis": true,
       "al.codeAnalyzers": "${analyzerfolder}/*.dll",
       "al.enableCodeActions": true
     }
     

   • Überwachen Sie die Ressourcennutzung
   • Optimieren Sie die Anzahl paralleler Builds

Entwicklung und Beitrag

Setup für Entwickler

1. Repository klonen:

git clone https://github.com/yourusername/ConditionalCode.git
cd ConditionalCode

2. Abhängigkeiten installieren:

npm install

3. Entwicklungs-Watch starten:

npm run watch

Testing

• Nutzen Sie die integrierten Test-Tools
• Führen Sie Tests mit unterschiedlichen BC-Versionen durch
• Testen Sie Cloud- und On-Premise-Szenarien

Lizenz

MIT

Support

Bei Fragen oder Problemen:

• Erstellen Sie ein Issue im GitHub Repository
• Besuchen Sie unsere Support-Website
• Kontaktieren Sie uns über profor software GmbH

Hinweise

Standard .gitignore Einträge:

.vscode/.alcache/*.*
.vscode/.altemplates/*.*
.alpackages
/*.app
Translations/*.xlf
.vscode/launch.json
.vscode/rad.json

🧾 Cheat Sheet / Schnellreferenz

📌 Befehle (Command Palette)

Explorer Kontext (.app): JSON generieren, Dateien extrahieren, signieren (Submenü "Conditional Code").

⚙️ Einstellungen (Auszug)

Linter Regeln (wichtige Keys)

Inline deaktivieren (nächste Zeile): // al-linter-disable-next-line ObjectNamePrefix oder mehrere durch Leerzeichen / Komma. Global: // al-linter-disable-next-line all.

🧪 Linter Issue Codes

ObjectNamePrefix · FileNameMismatch · FileNameCaseMismatch · FileNameTooShort · FileNameHasTrailing · NamespacePattern · TableFieldNaming · TableFieldIds · PageFieldCaption · Versioning ·

Ausführliche Beschreibung aller Codes (Bedeutung, Beispiele, Behebung): siehe docu.md. Klickbare Codes im Problems-Panel öffnen – sofern vorhanden – die passende Wiki-Seite ALCC(####).

🧩 CondiCode Syntax

Markers: //CondiCodeStart <Expr> ... //CondiCodeEnd – inaktive Zeilen werden als //CondiCode| markiert. Mehrzeilig mit //CondiCodeContinue.

Verfügbare Variablen/Funktionen innerhalb des Ausdrucks: platform, runtime, features, tenant, debug, config, VersionCompare(a,op,b), isVersionInRange(v,min,max), TargetCompare(target), now.

Beispiele:

//CondiCodeStart platform >= 26 && TargetCompare("Cloud")
//CondiCodeStart isVersionInRange("26.0.0.0","25.0.0.0","27.0.0.0")
//CondiCodeStart features.includes("A") && !debug

✨ Completions

🔧 Quick Fix / Bulk Fix

🔐 Signierung

Erfordert Umgebungsvariablen: KeyVault_clientId, KeyVault_Secret, KeyVault_tenant (Namen identisch zum Skript). Aktivierung via Setting conditionalCode.AppSigning.

🆔 Objekt-ID Logik

Berücksichtigt app.json idRanges; ignoriert definierte Ausschlüsse; Cache invalidiert bei Save.

🧯 Troubleshooting Kurz

✅ Best Practices

Kurz halten: CondiCode Blöcke dokumentieren • CustomRegex sparsam einsetzen • PageFieldCaption erst nach Naming-Disziplin aktivieren • Eigene ID-Ranges früh definieren.

Dieser Cheat Sheet Abschnitt kann bei Erweiterung der Funktionen aktualisiert werden.