Solution Struktur

In jedem Solution-Ordner muss sich eine solution.yaml befinden. Diese Datei beschreibt die Solution fachlich und technisch.

Über die solution.yaml legen Sie unter anderem fest:

• wie die Solution in der Solution Gallery angezeigt wird
• für welche OPC-Router-Versionen sie angeboten werden soll
• welche Parameter der Anwender beim Import eingeben oder auswählen muss
• in welchen Dateien Parameterwerte ersetzt werden dürfen

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.

Praktisch bedeutet das: Jede Information, die im Zielprojekt variieren kann, sollte bewusst als Parameter modelliert werden. So vermeiden Sie Nacharbeit nach dem Import und reduzieren das Risiko unvollständiger oder fehlerhafter Projektanpassungen.

Definitionen

solution.yaml

Feldname	Typ	Beschreibung	Beispiel
FormatVersion	int	Angabe der Formatversion	1
CompatibleVersionRange	string	Versionsangabe im losen Semver-Format. Damit wird geprüft, ob die Produktversion kompatibel ist. Wenn nein, wird die Solution ausgeblendet. Eine fehlende Angabe akzeptiert jede Version.	"=>5.2 <=6.0"
Tags	List (string)	Liste von Tag-IDs. Tags dienen in der Solution Gallery als Such- und Filterhilfe, um Solutions nach Themen oder Technologien zu finden. Siehe tags.yaml	["Example"]
DisplayName	TranslatableString	Anzeigename	DE: "Beispiel"
IconFile	string	Dateiname der Icon-Datei auf Solution-Ebene. Unterstützt werden alle gängigen Bildformate wie PNG, JPG und SVG.	"example.svg"
ShortDescription	TranslatableString	Kurze Beschreibung einer Solution, die in der Übersicht verwendet wird.	DE: "Kurze Beschreibung"
Description	TranslatableString	Beschreibung der Solution mit Hinweisen zur Verwendung. Kann durch eine Markdown-Datei überschrieben werden (siehe unten).	DE: "Ausführliche Beschreibung"
Parameters	Mapping (Solution-Parameter)	Mapping aus Parameter-ID als Key und Solution-Parameter als Wert. Die Parameter-ID wird beim Verwenden der Solution im Format ${<parameter_id>} verwendet.	example_string:
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.	".*yaml"

Solution-Parameter

Parameter definieren die Werte, die ein Anwender beim Import einer Solution eingibt oder auswählt. Sie steuern damit, welche Teile der Solution an das Zielprojekt angepasst werden können, ohne die Projektdateien manuell zu bearbeiten.

Jeder Parameter besteht aus einer Parameter-ID und einer zugehörigen Konfiguration. Die Parameter-ID wird in den Projektdateien als Platzhalter im Format ${<parameter_id>} verwendet.

Wählen Sie den Parametertyp so, dass er zur erwarteten Eingabe passt. Dadurch wird die Eingabe für den Anwender klarer und fehleranfällige Freitexteingabe vermieden.

Basis

Die Basiskonfiguration gilt für alle Parametertypen.

Feldname	Typ	Beschreibung	Beispiel
Label	TranslatableString	Bezeichnung des Parameters in der Eingabemaske	DE: "Servername"
HelpText	TranslatableString	Hilfetext für den Anwender, zum Beispiel zum erwarteten Format oder zum Zweck	DE: "Geben Sie den Hostnamen für den Zielserver ein."
Required	bool	Legt fest, ob der Anwender einen Wert angeben muss. Standardmäßig true.	true

Boolean

Verwenden Sie diesen Typ für Ja-/Nein-Entscheidungen oder zum Ein- und Ausschalten einer Funktion.

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

Dropdown

Wird verwendet, um konstante Werte zur Auswahl zu stellen.

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

DropdownItem

Feldname	Typ	Beschreibung	Beispiel
DisplayText	TranslatableString	Anzeigename	DE: "Option 1"
Value	string	Interner Wert. Wird bei der Parameterauflösung verwendet.	"1"

Integer

Dient der Angabe einer Ganzzahl.

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

SecretKey

Verwenden Sie diesen Typ, wenn der Anwender einen Secret-Key aus einem vorhandenen Secret Store auswählen soll. Dadurch müssen vertrauliche Werte nicht im Klartext in der Solution oder in Projektdateien hinterlegt werden.

Keine zusätzlichen Felder vorhanden.

String

Verwenden Sie diesen Typ für freie Texteingaben, zum Beispiel URLs, Servernamen, Mandantenkennungen oder andere Bezeichner.

Feldname	Typ	Beschreibung	Beispiel
Default	string	Standardwert für die Nutzereingabe.	"server01"
MinLength	int	Mindestlänge	3
MaxLength	int	Maximallänge	50

FileName

Verwenden Sie diesen Typ, wenn der Anwender einen Dateinamen eingeben soll.
Im Unterschied zum String-Parameter wird die Eingabe auf zulässige Zeichen geprüft. Außerdem kann die Oberfläche Konflikte bei Dateinamen gezielter anzeigen.

Feldname	Typ	Beschreibung	Beispiel
Default	string	Standardwert für die Nutzereingabe.	"export.csv"
MinLength	int	Mindestlänge	3
MaxLength	int	Maximallänge	64

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

Footnotes

1. snake_case bezeichnet eine Schreibweise mit klein geschriebenen Wörtern und Unterstrichen als Trennzeichen, zum Beispiel server_url oder project_name. ↩