Verbindungsreferenzen und Umgebungsvariablen

Der Import in die Testumgebung lief durch und der in Produktion ebenfalls. Trotzdem stehen am nächsten Morgen die Flows still oder schreiben in die SharePoint-Bibliothek der Entwicklungsumgebung. Hinter solchen Meldungen stecken fast immer dieselben zwei Bausteine: Verbindungsreferenzen und Umgebungsvariablen. Beide sind dafür gedacht, dass eine Lösung in jeder Umgebung mit den passenden Einstellungen läuft. Jedoch verursachen beide Fehler, wenn man sie wie normale Komponenten behandelt.

Was die beiden Bausteine tun

Eine Verbindungsreferenz ist ein Platzhalter für eine Verbindung. Power Automate Flows binden sich an diese Referenz und nicht direkt an eine Verbindung. Die eigentliche Verbindung (also die gespeicherte Anmeldung) gehört zur Umgebung und reist nicht mit. Beim Import wird jeder Referenz eine Verbindung der Zielumgebung zugeordnet damit Flows überhaupt eingeschaltet werden können (Microsoft Learn: Verbindungsreferenz in einer Lösung verwenden).

Eine Umgebungsvariable trennt eine Einstellung von den Komponenten welche sie nutzen ( eine Adresse etwa oder einen Schwellenwert). Sie besteht aus der Definition mit einem optionalen Standardwert und einem aktuellen Wert, der je Umgebung gesetzt wird.

Typische Fehler mit Verbindungsreferenzen

Keine Verbindung in der Zielumgebung. Gibt es für eine Referenz noch keine Verbindung kommt der Flow zwar an, bleibt aber ausgeschaltet bis jemand die Verbindung zuordnet. Das fällt meistens erst auf, wenn ein Vorgang ausbleibt.

Die falsche Person importiert. Wer einen Flow einschaltet muss alle Verbindungen darin besitzen oder sie geteilt bekommen haben. Sonst lässt sich der Flow nicht aktivieren. Importiert ein Administrator mit Verbindungen die einem Kollegen gehören, steht er genau vor diesem Fehler. Dienstkonten dem die Verbindungen gehören vermeidet dieses Problem.

Eigener Connector in derselben Lösung. Microsoft schreibt ausdrücklich, dass eigene Connectoren in einer separaten Lösung vor den Verbindungsreferenzen und Flows importiert werden müssen. Liegen sie zusammen in einer Lösung führt das laut Microsoft zu Problemen beim Import.

Deaktivierte oder verwaiste Referenzen. Eine deaktivierte Referenz legt alle Flows lahm die sie nutzen. Eine Referenz die kein Flow der Lösung verwendet, ist oft ein Überbleibsel (kann jedoch auch von einer Canvas App oder einer anderen Lösung gebraucht werden). Vor dem Löschen sollte dies also geprüft werden.

Werte gegen Standardwerte

Bei Umgebungsvariablen liegt der häufigste Fehler im Unterschied zwischen Standardwert und aktuellem Wert. Der Standardwert gehört zur Definition und darf mit der Lösung reisen. Der aktuelle Wert gilt für eine Umgebung. Ist er gesetzt, gewinnt er immer selbst wenn ein Standardwert vorhanden ist (Microsoft Learn: Umgebungsvariablen).

Der Grund dafür liegt im Export. War in der Entwicklungsumgebung ein aktueller Wert gesetzt und ist dieser Teil der Lösung, wandert er mit und überschreibt in der Zielumgebung die richtige Einstellung. Der Import meldet dabei keinen Fehler. Microsoft empfiehlt deshalb den aktuellen Wert nicht in die Lösung aufzunehmen. Das bedeutet: Die Definition gehört hinein und der Wert wird beim Deployment für die Zielumgebung gesetzt. Vor dem Export lässt sich der Wert aus der Lösung mit "Aus dieser Lösung entfernen" herausnehmen.

Zwei Folgen davon sind weniger bekannt. Ist der Wert einmal mit einer verwalteten Lösung in die Zielumgebung gekommen verschwindet er dort erst, wenn eine neue Version ohne den Wert per Upgrade eingespielt wird ( nicht per Update!). Und in einer verwalteten Lösung sieht man den aktuellen Wert nur über die Standardlösung. Wer bei der Fehlersuche in die verwaltete Lösung schaut sieht ihn möglicherweise nicht.

Der umgekehrte Fall tritt ebenfalls auf: eine Pflichtvariable ohne Standardwert und ohne mitgelieferten Wert kann zum Problem werden. Zwar fragt der Importdialog danach, aber bei einem automatisierten Deployment werden solche Werte gerne vergessen und deshalb laufen Flows und Apps erst, wenn jemand den Wert von Hand nachträgt.

Die Bereitstellungseinstellungsdatei

Für automatisierte Deployments gibt es eine Datei, die beides vorab festhält: je Verbindungsreferenz die Verbindung der Zielumgebung und je Umgebungsvariable den Wert (Microsoft Learn: Verbindungsreferenzen und Umgebungsvariablen vorab ausfüllen). Die Vorlage erzeugt die Power Platform CLI aus dem Lösungsexport:

pac solution create-settings --solution-zip MeineLoesung.zip --settings-file Produktion.json

Die leeren Felder füllt man einmal je Zielumgebung aus: die Kennung der Verbindung und den Wert der Variable. Beim Import wird die Datei mitgegeben, mit den Power Platform Build Tools oder mit "pac solution import" und dem Parameter "--settings-file". Die Dateien je Umgebung gehören in die Quellcodeverwaltung damit nachvollziehbar bleibt welche Umgebung welche Werte bekommt. Geheimnisse wie Kennwörter gehören dort nicht hinein. Dafür gibt es Umgebungsvariablen vom Typ Geheimnis (Secret) mit Azure Key Vault.

Eine Grenze sollte man kennen: Kommt eine neue Verbindungsreferenz oder Variable in die Lösung fehlt sie in der Datei bis jemand sie ergänzt. Die Datei ist also nicht einmal fertig, sondern wächst mit der Lösung.

Vor dem Import prüfen

Drei Fragen fangen die meisten dieser Fehler ab, bevor sie Produktion erreichen. Enthält die Lösung aktuelle Werte für Umgebungsvariablen und ist das gewollt? Gibt es Pflichtvariablen ohne jeden Wert? Ist für jede Verbindungsreferenz geklärt, welche Verbindung sie in der Zielumgebung bekommt und wem diese gehört?

Die ersten beiden lassen sich aus dem Lösungsexport beantworten, ebenso deaktivierte und ungenutzte Verbindungsreferenzen (diese werden beispielsweise von D365 Audit geprüft). Die dritte Frage betrifft die Umgebung und bleibt Handarbeit. Wer eine Pipeline betreibt baut die Prüfung des Exports als Schritt vor dem Import ein dann fällt ein mitgelieferter Entwicklungswert in der Pipeline auf und nicht erst in Produktion. Mehr zu den übrigen Importfehlern steht unter Häufige Fehler beim Deployment von Dynamics 365 Lösungen, eine abhakbare Liste unter Qualitätsprüfung vor dem Deployment.