Solution Struktur

In jedem Solution-Ordner muss sich eine solution.yaml-Datei befinden, in der die relevanten Informationen zur Solution eingetragen werden müssen. Darunter fallen z. B. Name, Beschreibung, Tags und Parameter der Solution.

Auflösungsprozess

Sobald eine Solution verwendet werden soll, werden Parameterwerte in den zulässigen Dateien ersetzt und in die Projektdateien übertragen und automatisch in die Konfiguration geladen.

Dabei gilt folgendes zu beachten:

• Parameter müssen in den Dateien dem Format ${parameter_id} folgen. Für die Schreibweise der Parameter-ID wird snake_case empfohlen.
• Dateien, deren Inhalt durch die Parameterauflösung verändert wurden, werden mit dem Encoding UTF-8 geschrieben.
• Zur ParameterReplacementFileRegex-Prüfung wird nur der Dateiname herangezogen und nicht der gesamte Dateipfad.
• Parameter ohne Standardwert, optionaler Angabe und keinem eingetragenen Wert, werden mit einem leeren Wert ersetzt. Dies kann ungewolltes Verhalten verursachen und sollte vorher geprüft werden.

Definitionen

solution.yaml

Feldname	Typ	Beschreibung
FormatVersion	int	Angabe der Formatversion
CompatibleVersionRange	string	Versionsangabe im losen Semver-Format. Wird verwendet, um zu überprüfen, ob die Produktversion kompatibel ist. Wenn nein, wird die Solution ausgeblendet. Eine fehlende Angabe akzeptiert jede Version.
Tags	List (string)	Liste von Tag-IDs. Siehe tags.yaml
DisplayName	TranslatableString	Anzeigename
IconFile	string	Dateiname der Icon-Datei auf Solution-Ebene. Unterstützt werden alle gängigen Bildformate wie PNG, JPG und SVG.
ShortDescription	TranslatableString	Kurze Beschreibung einer Solution, die in der Übersicht verwendet wird.
Description	TranslatableString	Beschreibung der Solution mit Hinweisen zur Verwendung. Kann durch eine Markdown-Datei überschrieben werden (siehe unten).
Parameters	Mapping (Solution-Parameter)	Key: Parameter-ID. Wird beim Verwenden der Solution im Format ${<parameter_id>} verwendet. Wert: Solution-Parameter
ParameterReplacementFileRegex	string	Regex zum Filtern von Dateinamen bei der Parameterauflösung beim Verwenden der Solution. Keine Angabe erklärt alle Dateien als zulässig. Wenn angegeben, werden nur Treffer aufgelöst.

Solution-Parameter

Basis

Die Basiskonfiguration ist für alle Parametertypen gültig.

Feldname	Typ	Beschreibung
Label	TranslatableString	Name des Parameters
HelpText	TranslatableString	Hilfetext
Required	bool	Legt fest, ob die Angabe des Parameters erforderlich ist. Standardmäßig true.

Boolean

Dient der Angabe eines Wahrheitswertes (true/false).

Feldname	Typ	Beschreibung
Default	bool	Standardwert für die Nutzereingabe. Keine Angabe führt zu false.

Dropdown

Wird verwendet, um konstante Werte zur Auswahl zu stellen.

Feldname	Typ	Beschreibung
Default	string	Standardwert für die Nutzereingabe. Bezieht sich auf den internen Wert eines Items in der Auswahl.
Items	List (DropdownItem)	Zur Verfügung stehende Auswahl.

DropdownItem

Feldname	Typ	Beschreibung
DisplayText	TranslatableString	Anzeigename
Value	string	Interner Wert. Wird bei der Parameterauflösung verwendet.

Integer

Dient der Angabe einer Ganzzahl.

Feldname	Typ	Beschreibung
Default	int	Standardwert für die Nutzereingabe.
Min	int	Mindestwert
Max	int	Maximalwert

SecretKey

Dient der Angabe eines Secret-Keys aus einem Secret Store.

Keine zusätzlichen Felder vorhanden.

String

Dient der Angabe einer Zeichenkette.

Feldname	Typ	Beschreibung
Default	string	Standardwert für die Nutzereingabe.
MinLength	int	Mindestlänge
MaxLength	int	Maximallänge

FileName

Dient der Angabe eines Dateinamens. Unterschiede zum String-Parameter bestehen in der Validierung auf zulässige Zeichen und zur Aktualisierung der Anzeige für Konflikte.

Feldname	Typ	Beschreibung
Default	string	Standardwert für die Nutzereingabe.
MinLength	int	Mindestlänge
MaxLength	int	Maximallänge

Markdown-Beschreibung

Für die Beschreibung einer Solution kann optional eine Markdown-Datei angelegt werden. Dabei gelten folgende Benennungsregeln:

• Die Datei muss sich auf Solution-Ebene befinden (auf Ebene der solution.yaml).
• Die Basisbezeichnung ist description. Übersetzungen sind optional und können über einen _de oder _en-Suffix erfolgen.
  • Beispiel: description.md oder description_de.md
• Die Datei muss mit .md enden.
• Es werden nur Funktionen aus dem CommonMark Standard unterstützt.

Beispiel einer solution.yaml

solution.yaml

FormatVersion: 1
ParameterReplacementFileRegex: .*yaml
CompatibleVersionRange: =>5.2 <=6.0
Tags:
  - Example
IconFile: "example.svg"
DisplayName:
  DE: "Beispiel"
  EN: "Example"
ShortDescription:
  DE: "Kurze Beschreibung"
  EN: "Short description"
Parameters:
  # String-Parameter
  example_string:
    Type: "String"
    Label:
      DE: "Ein String"
      EN: "A string"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "Test"
    MinLength: 5
    MaxLength: 30
  # File-Name-Example
  example_file_name:
    Type: "FileName"
    Label:
      DE: "Ein Dateiname"
      EN: "A file name"
    HelpText:
      DE: "Hilfetext"
      EN: "Help text"
    Default: "test-file-name"
  # Integer-Parameter
  example_integer:
    Type: "Integer"
    Label:
      DE: "Beispiel Ganzzahl"
      EN: "Example integer"
    Default: 1234
    Min: 10
    Max: 9999
  # Dropdown-Parameter
  example_dropdown:
    Type: "Dropdown"
    Label:
      DE: "Beispiel Dropdown"
      EN: "Example dropdown"
    Items:
      - DisplayText:
          DE: "Option 1"
          EN: "Option 1"
        Value: "1"
      - DisplayText:
          DE: "Option 2"
          EN: "Option 2"
        Value: "2"
    Default: "1"
  # Secret-Key-Parameter
  example_secret_key:
    Type: "SecretKey"
    Label:
      DE: "Geheim"
      EN: "Secret"
  # Boolean-Parameter
  example_boolean:
    Type: "boolean"
    Label:
      DE: "Beispiel Boolean"
      EN: "Example Boolean"
    Default: true