Paketübergreifende Abhängigkeiten in Salesforce: Modellierung, Installationsreihenfolge und sichere Upgrades

Kurze Antwort: Paketübergreifende Abhängigkeitsauflösung ist der Weg, auf dem Salesforce entscheidet, welche Pakete in welchen Versionen bereits vorhanden sein müssen, bevor ein weiteres installiert oder aktualisiert werden kann. Deklariert wird sie im Array dependencies in sfdx-project.json, in Installationsreihenfolge. Stimmen Reihenfolge und Mindestversionen, sind Subscriber-Upgrades langweilig. Stimmen sie nicht, landet eine Org auf einer Version, die sie nicht mehr verlassen kann.

Was ist eine Paketabhängigkeit genau?

Eine Abhängigkeit besteht, sobald Metadaten in einem Paket Metadaten in einem anderen referenzieren: ein Flow auf einem Managed Object, eine Apex-Klasse, die eine Basisklasse erweitert, ein Field Set auf einem fremden Feld. Die praktische Folge ist eine Vorbedingung. Das referenzierte Paket muss zuerst installiert sein, in einer Version mindestens so neu wie die, gegen die Sie gebaut haben, sonst schlägt die Installation fehl.

Wie deklariert man eine Abhängigkeit zwischen Paketen?

Im Package-Directory-Eintrag von sfdx-project.json, in einer von zwei Formen:

• Ein Alias, der die Version bereits trägt: { "package": "[email protected]" }
• Paket und Version getrennt: { "package": "MyPackage", "versionNumber": "1.0.0.RELEASED" }

Drei Regeln wiegen schwerer als die Syntax.

• Die Reihenfolge ist die Installationsreihenfolge. Hat ein Paket mehrere Abhängigkeiten, wird die Liste als Reihenfolge gelesen, in der sie installiert werden müssen.
• Zirkuläre Abhängigkeiten werden nicht unterstützt. A hängt von B ab, während B von A abhängt, ist kein zu lösendes Rätsel, sondern ein zu zerlegender Entwurf.
• Mehrstufige Ketten sind möglich. C kann von B abhängen und B von A. Mit "calculateTransitiveDependencies": true deklarieren Sie nur direkte Abhängigkeiten, die indirekten werden berechnet. Ohne das müssen Sie jede Ebene selbst aufführen, dauerhaft.

Welche Pakettypen dürfen von welchen abhängen?

Das schränkt die Architektur ein, prüfen Sie es also, bevor Sie sie zeichnen.

• Managed 2GP darf von Managed 2GP und von Unlocked Packages abhängen.
• Managed 2GP darf nicht von Managed 1GP abhängen. Salesforce blockiert die Installation von Managed-2GP-Paketen in Managed-1GP-Packaging-Orgs. Wo ein Produkt es wirklich braucht, führt der Weg über einen Fall beim Salesforce Partner Support für eine individuelle Ausnahme, nicht über einen Trick im Build-Skript.
• Managed 1GP darf von Managed 1GP, Managed 2GP und Unlocked Packages abhängen.
• Unlocked Packages, die von Managed Packages abhängen, sind nicht empfohlen, und nichts Unterstütztes hängt von einem Unmanaged Package ab.

Ein 1GP-Basispaket unter einer 2GP-Erweiterung ist der mit Abstand häufigste Abhängigkeitsentwurf, der spät wieder aufgelöst werden muss, und dann ist er teuer. Lesen Sie die unterstützten Kombinationen vor dem ersten Build, nicht danach.

Wie modelliert man Pakete, damit der Graph flach bleibt?

1. Nur eine Richtung. Basis, dann Feature, dann Rand. Wollen zwei Pakete einander referenzieren, gehören die gemeinsamen Metadaten in ein drittes Paket darunter.
2. Klein und modular schlägt ein großes Paket. Erstellung und Installation sind schneller, und Sie stoßen seltener an Limits.
3. Teuer ist die Tiefe, nicht die Breite. Jede zusätzliche Ebene vervielfacht die Release-Koordination: Eine Änderung ganz unten verlangt eine neue Version auf jeder Ebene darüber, bevor ein Subscriber irgendetwas davon sieht.
4. Pinnen Sie bewusst. Eine festgepinnte Buildnummer ist reproduzierbar und langweilig. Ein Schlüsselwort wie RELEASED folgt Ihrer zuletzt veröffentlichten Version, was in der Entwicklung praktisch und im Release-Build eine Überraschung ist.

Was ist die richtige Installationsreihenfolge in einer Subscriber-Org?

1. Installieren oder aktualisieren Sie zuerst das unterste Paket im Graphen, das selbst keine Abhängigkeiten hat.
2. Arbeiten Sie sich Ebene für Ebene nach oben, damit jedes Paket seine Vorbedingung bei der Installation erfüllt vorfindet.
3. Installieren Sie das oberste Paket, also das, was Ihr Kunde tatsächlich gekauft hat, zuletzt.
4. Prüfen statt annehmen. Eine SOQL-Abfrage auf SubscriberPackageVersion sagt Ihnen, was in dieser Org installiert ist und in welcher Version, und das schlägt einen Blick auf die Seite Installed Packages mit Hoffnung im Gepäck.

Wenn Sie diese Reihenfolge für Ihr eigenes Produkt nicht aus dem Kopf nennen können, kann Ihr Support das in dem Moment auch nicht, in dem ein Kunde feststeckt.

Wie ändert man eine Abhängigkeit, ohne Subscriber hängen zu lassen?

• Die neue Version muss ein direkter Nachfahre der installierten sein. Subscriber können die Linie nicht überspringen, ein Paket mit gebrochener Ancestry ist also ein Paket, das manche Orgs nicht aktualisieren können.
• Beta-Pakete sind nicht upgradefähig. Ein Subscriber mit einer Beta muss deinstallieren, bevor er eine released Version installiert, und in Produktion ist das ein Gespräch über Datenverlust. Lassen Sie nie eine Beta in einer Kunden-Org zurück.
• Entfernte Metadaten werden beim Upgrade als veraltet markiert oder gelöscht. Eine Komponente von einem Paket in ein anderes zu verschieben ist hier eine Entfernung und dort eine Ergänzung, die Release-Reihenfolge zwischen beiden ist also das ganze Risiko.
• Heben Sie Mindestversionen schrittweise an. Die geforderte Version eines Basispakets um mehrere Releases anzuheben, erzwingt eine Upgrade-Kette bei Subscribern, die keine geplant hatten.

Die Reihenfolge, die funktioniert, wenn sich ein Basispaket ändert: Basisversion veröffentlichen, Subscriber über eine empfohlene Version oder ein Push Upgrade darauf bringen, und erst dann das abhängige Paket veröffentlichen, das sie voraussetzt. Wer die beiden vertauscht, erzeugt ein Upgrade, das an einer Vorbedingung scheitert, in einer Org, die Sie weder sehen noch von Ihrer Seite reparieren können.

Was sollte man automatisieren?

1. Den Graphen bei jedem Pipeline-Lauf aus sfdx-project.json aufbauen und den Build bei einem Zyklus scheitern lassen.
2. Die gesamte Kette jedes Mal in der deklarierten Reihenfolge in eine saubere Scratch Org installieren, damit Reihenfolgefehler beim Build auffallen und nicht in einer Kunden-Org.
3. Installierte Versionen je Subscriber-Org festhalten, damit der Support die Frage beantworten kann, bevor er sie dem Kunden stellt.

Serpent beherrscht paketübergreifende Abhängigkeitsauflösung, 1GP-, 2GP- und Managed-Package-Workflows sowie Versionsmanagement über Subscriber-Orgs in jedem Tarif, auch im kostenlosen. Weitere Packaging-Playbooks finden Sie in unserer SF-Guides-Bibliothek.

FAQ

Darf ein Managed-2GP-Paket von einem Managed-1GP-Paket abhängen?

Standardmäßig nicht. Salesforce blockiert die Kombination, und eine individuelle Ausnahme wird über einen Fall beim Salesforce Partner Support beantragt.

Muss ich transitive Abhängigkeiten auflisten?

Nur wenn Sie wollen. Mit "calculateTransitiveDependencies": true deklarieren Sie direkte Abhängigkeiten, die indirekten werden berechnet. Ohne das muss jede Ebene von Hand in der Liste stehen.

Was passiert, wenn zwei Pakete voneinander abhängen?

Nichts Gutes, denn zirkuläre Abhängigkeiten werden nicht unterstützt. Ziehen Sie die gemeinsamen Metadaten in ein tieferes Paket, von dem beide abhängen.

Welches Paket aktualisiere ich in einer Subscriber-Org zuerst?

Das unterste im Graphen. Abhängigkeiten kommen vor den Paketen, die sie brauchen, in derselben Reihenfolge wie bei der Installation.

Warum scheitert das Upgrade meines Kunden mit einem Abhängigkeitsfehler?

Meist an einer Mindestversion. Das installierte Basispaket ist alter als das, was Ihr neues Release verlangt: Basispaket zuerst aktualisieren, dann erneut versuchen.