Direkt zum Hauptinhalt

Umgebungsvariablen verwenden

Ziel​

Eine Einstellung einmal in Ihrer Lösung deklarieren – eine API-Adresse, ein Postfach, einen Funktionsschalter – und Entwicklung, Test und Produktion sie jeweils auf ihre eigene Weise beantworten lassen, ohne die Lösung nach jedem Import zu bearbeiten.

Warum es das gibt​

Eine Lösung, die von der Entwicklung über Test in die Produktion befördert wird, soll dieselbe Lösung sein. Und doch muss sich manches, was sie tut, je Umgebung unterscheiden: der Dienst, den sie aufruft, die Adresse, von der sie sendet, ob eine Funktion eingeschaltet ist.

Ohne Umgebungsvariablen gibt es nur zwei Wege, das auszudrücken, und beide sind schlecht. Sie können Komponenten nach jedem Import bearbeiten – dann laufen Ihre Umgebungen unbemerkt auseinander, und das Auseinanderlaufen bleibt verborgen. Oder Sie codieren den Entwicklungswert fest und denken daran, ihn zu ändern – was genau bis zu dem Tag funktioniert, an dem niemand mehr daran denkt.

Eine Umgebungsvariable teilt die Einstellung in zwei Teile:

  • Die Deklaration – ihr Name, Typ, ihre Beschreibung und ihr Standardwert. Sie gehört zur Lösung und reist mit ihr.
  • Der Wert – die Antwort dieser Umgebung. Er gehört zur Umgebung und verlässt sie nie. Der Export der Lösung nimmt ihn nicht mit, und der Import der Lösung überschreibt ihn nicht.

Voraussetzungen​

  • Sie sind als Ersteller angemeldet, und eine Lösung sowie eine Umgebung sind ausgewählt.

Schritte​

Eine Variable deklarieren (meist in der Entwicklung)​

  1. Öffnen Sie Ihre Lösung und wählen Sie in der linken Navigation Umgebungsvariablen aus.
  2. Wählen Sie Neu aus.
  3. Geben Sie einen Anzeigenamen ein (zum Beispiel Invoice API URL). Darunter füllt sich der logische Name mit dem Präfix Ihres Herausgebers aus – aus invoice_api_url wird par_invoice_api_url.
  4. Wählen Sie einen Typ: Text, Zahl, Boolesch (true/false) oder JSON. Jeder für die Variable gesetzte Wert wird dagegen geprüft, in welcher Umgebung er auch eingegeben wird.
  5. Schreiben Sie eine Beschreibung. Die Mühe lohnt sich hier mehr als bei den meisten Dingen, die Sie bauen: Wer den Wert in der Produktion setzt, sind oft nicht Sie, und ein bloßer Name sagt selten, wie ein korrekter Wert aussieht.
  6. Geben Sie optional einen Standardwert ein – der überall verwendet wird, wo eine Umgebung keinen gesetzt hat. Lassen Sie ihn leer bei etwas ohne sinnvollen Standard (ein Geheimnis, eine kundenspezifische Adresse), damit eine nicht gesetzte Variable sichtbar nicht gesetzt ist statt unbemerkt falsch.
  7. Wählen Sie Speichern aus.

Den Wert dieser Umgebung setzen (in jeder Umgebung)​

  1. Öffnen Sie Umgebungsvariablen und wählen Sie die Zeile der Variablen aus (oder markieren Sie sie und wählen Sie Wert festlegen aus).
  2. Geben Sie den Wert ein, den diese Umgebung verwenden soll, und wählen Sie Speichern aus.
  3. Um zum deklarierten Standardwert zurückzukehren, leeren Sie das Feld und speichern. Das ist eine Entscheidung, und es ist der einzige Weg zurück, nachdem ein Wert gesetzt wurde.

Die Spalte Wirksamer Wert zeigt, in welchem von drei Zuständen sich jede Variable befindet:

Sie zeigtDas bedeutet
einen Wertdiese Umgebung hat ihn gesetzt
einen Wert, dann (Standardwert wird verwendet)hier wurde nichts gesetzt; der Standardwert der Lösung gilt
Nicht gesetztweder noch – hier beantwortet nichts diese Variable, und alles, was sie liest, findet nichts

Nicht gesetzt ist der Zustand, der vor dem Produktivstart beseitigt sein muss.

Eine Variable in einem Plug-in-Schritt lesen​

In einem BS Lang-Plug-in-Schritt liefert getEnvironmentVariable("par_invoice_api_url") den wirksamen Wert für die Umgebung, in der der Schreibvorgang stattfindet. Dadurch kann ein Skript überall korrekt sein: Es nennt die Einstellung statt der Adresse.

Eine nicht gesetzte Variable wird als leere Zeichenfolge gelesen; ein Skript, das eine braucht, sollte das also melden, statt einfach weiterzumachen:

if (getEnvironmentVariable("par_invoice_api_url") == "") {
    throwValidationError("The invoice API URL is not configured in this environment.");
}

Eine fehlende Einstellung ist ein Konfigurationsfehler, kein Wert – hier deutlich zu scheitern, ist viel freundlicher, als später undurchsichtig zu scheitern.

Was im Hintergrund passiert​

Die Deklaration ist eine Lösungskomponente wie eine Tabelle oder ein Optionssatz: Sie wird gegen ein veröffentlichtes Schema validiert, gehört zum Namensraum Ihres Herausgebers und reist im Lösungspaket mit. Der Wert wird bei der Umgebung gespeichert und nie in ein Paket geschrieben.

Beim Import in eine andere Umgebung gilt:

  • Eine Variable, die zum ersten Mal ankommt, landet mit ihrem deklarierten Standardwert und ohne Wert;
  • bei einer bereits vorhandenen Variablen wird die Deklaration aktualisiert – eine umbenannte Beschriftung, ein geänderter Standardwert, eine korrigierte Beschreibung –, und ihr Wert bleibt genau so, wie diese Umgebung ihn gesetzt hat.

Diese zweite Regel ist der Grund, warum es die ganze Funktion gibt. Eine Lösung in die Produktion zu befördern, darf die Produktion nie unbemerkt auf den Endpunkt der Entwicklung umlenken.

Die Deinstallation der Lösung entfernt ihre Variablen samt Werten – dann gibt es nichts mehr zu konfigurieren.

Fehlerbehebung​

  • „‚…‘ ist kein gültiger Zahlenwert.“ (oder Boolesch/JSON) – Der Wert entspricht nicht dem deklarierten Typ. Das wird absichtlich dort geprüft, wo Sie ihn eingeben, und nicht dort, wo er später gelesen wird: Ein Skript, das es entdeckte, würde weit entfernt vom Fehler scheitern, und wahrscheinlich in der Produktion.
  • Ich habe den Typ geändert, und mein Wert ist verschwunden. – Der Wert passte nicht mehr zum neuen Typ und wurde daher gelöscht, statt als etwas erhalten zu bleiben, das nichts lesen kann. Die Variable fällt auf ihren Standardwert zurück und wird als nicht gesetzt angezeigt, was sichtbar ist. Setzen Sie ihn erneut.
  • Ich habe die Lösung importiert, und die Produktion zeigt noch den alten Wert. – Das ist beabsichtigt: Ein Import überschreibt nie den eigenen Wert einer Umgebung. Ändern Sie ihn in der Produktion im Seitenbereich Wert festlegen.
  • Mein Standardwert ist in der Produktion angekommen, mein Entwicklungswert aber nicht. – Auch das ist beabsichtigt. Der Standardwert ist Teil der Deklaration und reist mit; der Wert gehört der Umgebung und reist nicht mit.
  • Ein Skript liest eine leere Zeichenfolge. – Die Variable ist in dieser Umgebung deklariert, aber nicht gesetzt, oder der Name ist falsch geschrieben. Prüfen Sie die Spalte Wirksamer Wert; Nicht gesetzt unterscheidet diesen Fall von einem Tippfehler, der gar nicht in der Liste erscheint.
  • „In dieser Umgebung existiert bereits eine Umgebungsvariable namens ….“ – Logische Namen sind innerhalb einer Umgebung eindeutig. Wählen Sie einen anderen oder bearbeiten Sie die vorhandene Variable.

Verwandte Szenarien​