TLDR

Für die Verwaltung von 3rd-Party-Abhängigkeiten in Schleupen.CS 3.0 Solutions wird ab PSI FV27 das neue System "Dependency-Management" verwendet. Die Quellcode-Repositories von Plattform und Fachteams wurden bis zu diesem Zeitpunkt auf das Dependency-Management portiert.

Die regelmäßige Aktualisierung der Paket-Abhängigkeiten in einer Schleupen.CS-Solution erfolgt im Dependency-Management jeweils über die in allen Quellcode-Repositories abgelegte Datei UpdateDependencies.cmd. Diese tritt an die Stelle des bisherigen Werkzeugs Update-CSDependencies.ps1, das für Solutions unter Dependency-Management nicht mehr verwendet werden kann.

Zentraler Begriff des Dependency-Management sind die sog. DependencySets - eine kohärente Zusammenstellung von Versionen für 3rd-Party-Packages - die einen einheitlichen Versionsstand über alle Schleupen.CS-Solutions hinweg sicherstellen und die versehentliche Verwendung von nicht für die Entwicklung freigegebenen Packages oder Versionen ausschließen.

Der Übersetzungsvorgang wird technisch auf den Aufruf des Befehls dotnet paket update abgebildet und resultiert in der Generierung einer paket.lock-Datei, die für jede direkte oder transitive Abhängigkeit der Solution eine feste Versionsnummer enthält, aus den u.U. lockeren Versionsbedingungen in der paket.dependencies-Datei.

Dabei sind insbesondere die Einhaltung von Lizenzbedingungen externer Abhängigkeiten (sog. 3rd-party Dependencies, Lizenzen der 3rd-Party-Komponenten in Schleupen.CS) und allgemeine Richtlinien für die Schleupen.CS-Entwicklung (z.B. Verwendung LTS-Versionen für System.*- und Microsoft.*-Packages) zu beachten.

Problemstellung

In einer Reihe von Situationen kann die Ausführung des paket-Werkzeugs fehlschlagen oder durch Überschreitung einer maximalen Ausführungszeit¹ zum Abbruch führen:

• Aufgrund unvollständiger oder widersprüchlicher Versionsbedingungen in der paket.dependencies-Datei kann bereits die initialen Erstellung einer paket.lock-Datei scheitern.
• Neu veröffentlichte Versionen von 3rd-Party-Dependencies können im zeitlichen Verlauf spontan Konflikte zwischen den Versionsbedingungen für direkt angegebene und transitive Abhängigkeiten entstehen lassen.

Um hier dennoch zum Erfolg zu kommen, müssen i.d. R. die Versionsbedingungen manuell verändert oder zusätzliche Versionshinweise in der paket.dependencies-Datei ergänzt werden, was häufig eine nichttriviale Aufgabe darstellt.

Die Ergänzung von Versionshinweisen in paket.dependencies-Dateien war eine der primären Aufgaben des Vorgängerwerkzeugs Update-CSDependencies.ps1 aus den Schleupen.XS.DevelopmentTools.
Dieses wird durch die Werkzeuge des Dependency-Mangements abgelöst und vollständig ersetzt.

Die Ausführung von Update-CSDependencies.ps1 auf einer Solution, die auf Dependency-Management umgestellt wurde, erzeugt einen Fehler.

Da aufgrund der zeitlichen Fortentwicklung sowohl von externen Abhängigkeiten als auch von Schleupen.CS-Packages eine regelmäßige Aktualisierung der paket.lock-Dateien erforderlich ist, ist das Risiko von Fehlschlägen und der daraus resultierende Pflegeaufwand der paket.dependencies-Dateien nicht zu vernachlässigen.

Weiterhin wird die Einhaltung der Entwicklungsrichtlinien bzgl. der Verwendung explizit freigegebener 3rd-Party-Packages bislang nicht unmittelbar von den technischen Werkzeugen unterstützt, denn der bislang für externe Abhängigkeiten verwendete Nexus-Feed "nuget-v3" bietet einen ungefilterten Proxy aller auf NuGet.org gelisteten Packages an und hat keinen direkten Bezug zu den Lizenzen der 3rd-Party-Komponenten in Schleupen.CS.

Lösungsansatz

Um das Fehlschlagsrisiko bei der Dependency-Aktualisierung und den damit verbundenen Aufwand für Korrekturen von der Schleupen.CS-Fachentwicklung fernzuhalten, sieht das Dependency-Management die Aufteilung des Aktualisierungsprozesses in zwei getrennte Teilprozesse vor:

1. Vorberechnung einer Menge von kohärenten Versionsständen von 3rd-Party-Dependencies (sog. DependencySets)
   -> Ausführung in der Plattform
2. Anwendung dieser kohärenten Versionsstände auf Schleupen.CS-Solutions
   -> Ausführung in der Fachentwicklung

Sobald ein DependencySet erfolgreich ermittelt wurde, besteht für seine Anwendung innerhalb einer Schleupen.CS-Solution kein Fehlschlagsrisiko mehr bezüglich der Versionsermittlung von 3rd-Party-Dependencies.

Die Einhaltung der Entwicklungsrichtlinie bzgl. der ausschließlichen Verwendung explizit freigegebener 3rd-Party-Packages wird dadurch erreicht, dass in DependencySets nur freigegebene 3rd-Party-Packages in akzeptierten Versionen² aufgenommen werden und dass ein separater kuratierter Feed im Nexus-Repository angelegt wird, der ausschließlich mit den Inhalten der DependencySets befüllt wird. Dieser kuratierte Feed tritt in der paket.dependencies-Datei als source-URL für externe Abhängigkeiten an die Stelle des bisherigen ungefilterten NuGet-Proxies und schließt somit per Konstruktion die Verwendung von nicht freigegebenen Packages aus. Dies gilt übrigens auch dann, wenn diese nur als transitive Abhängigkeit auftreten.

Abgrenzung

In der Praxis ist für den Erfolg einer Dependency-Aktualisierung die Einhaltung weiterer Rahmenbedingungen wichtig:

• Alle in einer Schleupen.CS-Solution verwendeten externen Abhängigkeiten müssen von den bestehenden DependencySets abgedeckt sein.
• Dies betrifft sowohl die unmittelbar in der paket.dependencies-Datei angegebenen Packages als auch die transitiven Abhängigkeiten aller Schleupen.CS-Packages.
• Die in der paket.dependencies-Datei angegebenen Schleupen.CS-Packages müssen bezüglich ihrer Versionsbedingungen kohärent sein.

DependencySets enthalten nur externe Abhängigkeiten, daher greift das Dependency-Management nicht regulierend in die Verwendung von Schleupen.CS-Packages ein.

Für die Einhaltung der Entwicklungsrichtlinien bzgl. freigegebener 3rd-Party-Packages ist es weiterhin erforderlich, dass:

• Jede Gruppe (technisch: group) in einer paket.dependencies-Datei per external_lock-Deklaration einem der verfügbaren DependencySets zugeordnet ist.
• Als source-URLs nur die u.a Nexus-Feeds verwendet werden - mit Ausnahme des NugetProxy.

Die Werkzeuge des Schleupen.CS Dependency-Managements überprüfen die Einhaltung dieser Bedingungen und brechen den Aktualisierungsvorgang einer Solution bei Verletzung einer Bedingung mit einer Fehlermeldung ab.

Es ist technisch möglich, unter Umgehung der Werkzeuge des Schleupen.CS Dependency-Managements abweichende Einträge in der paket.dependencies-Datei vorzunehmen und das paket-Werkzeug direkt auszuführen - mit allen Risiken eines Fehlschlags bei der Versionsaktualisierung und mglws. Verwendung nicht freigegebener 3rd-Party-Packages.
Ein solches Vorgehen verlässt die Spezifikation des Schleupen.CS Dependency-Managements und erhält keinen Support durch die Plattform.

Prozesse

Die Prozesse des Dependency-Managements werden von der Plattform durch mehrere Werkzeuge unterstützt, die jeweils als dotnet-tools bereitgestellt werden.

Es empfiehlt sich, diese Tools stets auf einem aktuellen Stand zu halten (z.B. durch Ausführung von dotnet tool update vor jeder Verwendung).

Bei Verwendung der UpdateDependencies.cmd-Datei, die im Rahmen der Migration von Schleupen.CS-Solutions auf das Dependency-Management neu bereitgestellt wurden, erfolgt diese Aktualisierung der relevanten dotnet-tools automatisch.

Regelmäßige Aktualisierung in Fach-Solutions

Die regelmäßige Aktualisierung der Dependencies einer Schleupen.CS-Solution im Dependency-Management erfolgt i.d.R. durch den Aufruf der im Repository abgegegten UpdateDependencies.cmd-Datei innerhalb des aus der Quellcodeverwaltung abgerufenen Solution-Verzeichnisses.

Der einfachste Weg zur relgelmäßigen Aktualisierung der Dependencies ist die Verwendung der Datei UpdateDependencies.cmd, die Rahmen der Umstellung auf das Dependency-Management in allen Quellcode-Repositories neu angelegt wurde.
Diese Datei enthält Befehle für die Aktualisierung der relevanten dotnet-tools (cspaket und dependencies-apply) einen Aufruf von dotnet dependencies-apply mit den jeweils auf die enthaltene Solution angepassten Parametern.

Beispielablauf

Regelfall

Die Dependency-Aktualisierung in einer hypothetischen Solution Schleupen.CS.My kann nach folgendem Ablauf erfolgen:

cd ...\cs-Schleupen.CS.My
...\cs-Schleupen.CS.My> git pull
...\cs-Schleupen.CS.My> UpdateDependencies.cmd
...\cs-Schleupen.CS.My> git commit -m "chore:Dependencies aktualisiert"
...\cs-Schleupen.CS.My> git push

Direkte Verwendung des dotnet-tools

Falls die Verwendung des UpdateDependencies.cmd nicht möglich sein sollte - z.B. weil die Datei noch erstellt werden muss - kann stattdessen unmittelbar auf das dotnet-tool schleupen.xs.pi.dependencymanagement.application zugegriffen werden:

cd ...\cs-Schleupen.CS.My
...\cs-Schleupen.CS.My> git pull
...\cs-Schleupen.CS.My> dotnet tool update cspaket
...\cs-Schleupen.CS.My> dotnet tool update schleupen.xs.pi.dependencymanagement.application
...\cs-Schleupen.CS.My> dotnet dependencies-apply Execute <Parameters>
...\cs-Schleupen.CS.My> git commit -m "chore:Dependencies aktualisiert"
...\cs-Schleupen.CS.My> git push

In vielen Fällen kann der Platzhalter <Parameters> leer bleiben, ansonsten können hier

• die Positionen der paket.dependencies- und paket.lock-Dateien in abweichenden Pfaden
• die Zuordnungen von DependencySets zu Gruppen der paket.dependencies-Datei
• Spezialkonfigurationen für bestimmte Sonderfälle

angegeben werden.

Das Kommando Execute ist ein Sammelbefehl zur Ausführung der Detail-Befehle ApplyExternalLock, EnsureSolutionDefaults, ConsolidatePackageSources, ValidateVersions und CheckPackages.,
Falls der erste Teilbefehl scheitert, werden die nachfolgenden Teilbefehle nicht ausgeführt, um die Log-Ausgabe übersichtlich zu halten.

Sonderfälle

In Sonderfällen - z.B. in Quellcode-Repositories mit abweichender Verzeichnisstruktur - muss der Aufruf des Execute - Kommandos in seine Teil-Kommandos aufgelöst werden, um diese mit den jeweils geeigneten Parametern aufzurufen.

Für Quellcode-Repository mit Solution-Datei im Unterverzeichnis "CS.Foo" resultiert dies in:

cd ...\cs-Schleupen.CS.Foo
...\cs-Schleupen.CS.Foo> git pull
...\cs-Schleupen.CS.Foo> dotnet tool update cspaket
...\cs-Schleupen.CS.Foo> dotnet tool update schleupen.xs.pi.dependencymanagement.application
...\cs-Schleupen.CS.Foo> dotnet dependencies-apply ApplyExternalLock CS.Foo\paket.dependencies \
                         -lf Foo\paket.lock
...\cs-Schleupen.CS.Foo> dotnet dependencies-apply EnsureSolutionDefaults CS.Foo\
...\cs-Schleupen.CS.Foo> dotnet dependencies-apply ConsolidatePackageSources CS.Foo\paket.dependencies \
                         -lf Foo\paket.lock
...\cs-Schleupen.CS.Foo> dotnet dependencies-apply ValidateVersions CS.Foo\paket.lock
...\cs-Schleupen.CS.Foo> dotnet dependencies-apply CheckPackages CS.Foo\paket.lock
...\cs-Schleupen.CS.Foo> git commit -m "chore:Dependencies aktualisiert"
...\cs-Schleupen.CS.Foo> git push

Regelmäßige Aktualisierung der DependencySets in der Plattform

Die regelmäßige Aktualisierung der DependencySets in der Plattform erfolgt durch Anwendung des Prepare-Werkzeugs (dotnet dependencies-prepare Execute) auf den in der Plattform gepflegten paket.dependencies-Dateien der DependencySets.

Das Kommando Execute ist ein Sammelbefehl zur Ausführung der Detail-Befehle PrepareExternalLock, ValidateVersions und CheckPackages., Falls der erste Teilbefehl scheitert, werden die nachfolgenden Teilbefehle nicht ausgeführt, um die Log-Ausgabe übersichtlich zu halten.
Intern werden im Rahmen von PrepareExteranlLock die folgenden Schritte in potentiell mehreren Schleifendurchläufen ausgeführt:
1. Analyse und ggf. strukturelle Anpassung der paket.dependencies-Datei
2. eingebettete Ausführung von dotnet paket update
3. Analyse der resultierenden paket.lock-Datei auf Konformität mit den bestehenden Versionseinschränkungen
4. bei Bedarf Ergänzung von Versionshinweisen in der paket.dependencies-Datei und Rücksprung zu Schritt 2.
5. Erzeugung der external_lock-Datei aus der finalen paket.lock-Datei

Da die Aktualisierung eines DependencySets selbst nicht durch eine zugeordnete external_lock-Datei kontrolliert wird, können in dieser Phase weiterhin die bekannten Versionskonflikte oder ggf. Überschreitungen der maximalen Ausführungszeit des paket-Tools auftreten.
Zur Konfliktauflösung müssen dann die bekannten Strategien eingesetzt werden, bis eine kohärente paket.lock-Datei generiert werden kann.

Aufgrund der inkohärenten Caching-Implementierung des Nexus bzgl. Package-Namen und Package-Inhalt kann es bei neuen Packages (wenige Stunden alt) dazu kommen, dass der Inhalt der erkannten neueste Package-Version noch nicht im Nexus verfügbar ist und beim Download-Versuch Fehler auslöst.
In diesem Fall muss die Dependency-Aktualisierung verschoben oder die Version der betroffenen Packages auf den schon verfügbaren Stand abgesenkt werden.

Nachdem ein DependencySet verändert wurde muss vor dem push in den main-Branch des GIT-Repositories sichergestellt werden, dass alle enthaltenen Package-Versionen im Curated Feed des Nexus-Repositories vorliegen. Auch hierzu kann das Prepare-Werkzeug verwendet werden (dotnet dependencies-prepare UploadPackages).

Für die Ausführung von UploadPackages muss ein NuGetApiKey hinterlegt sein, der vom Nexus-Repository akzeptiert wird. Bei Ausführung auf der Kommandozeile kann dies über eine Umgebungsvariable NugetConfiguration__Repositories__ExternalPackageSource__NugetApiKey erfolgen.

set NugetConfiguration__Repositories__ExternalPackageSource__NugetApiKey="Hier den NuGet API Key aus Nexus eintragen."

Bei Ausführung im Debugger des VisualStudio kann der NuGetApiKey in der Konfiguration nach dem folgenden Muster hinterlegt werden.

  "NugetConfiguration": {
    "Repositories": {
      "ExternalPackageSource": {
        "UserName": "<Environment>",
        "NugetApiKey": "Hier den NuGet API Key aus Nexus eintragen."
      }
    }
  }

Zweckmäßiger Weise sollte eine JSON-Konfiguration nicht in der appconfig.json-Datei erfolgen, sondern über die Option "Geheime Benutzerschlüssel verwalten" im VisualStudio in einer separaten secrets.json-Datei.

Beispielablauf

Die Aktualisierung eines DependencySets kann nach folgendem Ablauf erfolgen:

cd ...\xs-Schleupen.XS.PI.DependencySets
xs-Schleupen.XS.PI.DependencySets> git pull
xs-Schleupen.XS.PI.DependencySets> dotnet tool update schleupen.xs.pi.dependencymanagement.preparation
xs-Schleupen.XS.PI.DependencySets> dotnet dependencies-prepare PrepareExternalLock \
                                   -df NetCore8\paket.dependencies -lf NetCore8\paket.lock \
                                   -elf NetCore8\external_lock_NetCoredotnet 
xs-Schleupen.XS.PI.DependencySets> git commit -m "chore:DependencySets aktualisiert"
xs-Schleupen.XS.PI.DependencySets> dotnet dependencies-prepare UploadPackages \
                                   -elf NetCore8\external_lock_NetCore
xs-Schleupen.XS.PI.DependencySets> git push

Anforderung neuer 3rd-Party-Dependencies

Neue 3rd-Party-Dependencies müssen zunächst vom BL Weiß für die Verwendung in der Schleupen.CS-Entwicklung genehmigt werden.

Nach erfolgter Genehmigung kann die neue Dependency unter Angabe des Ziel-Frameworks (.NET 8.0, .NET Standard 2.0, .NET Framework 4.7.2, etc.) und des genauen Versionsbereichs bei der Plattform für die Aufnahme in das zugehörige DependencySet eingereicht werden.

Migration

Die Migration einer Schleupen.CS-Solution von der bisherigen Praxis in das Dependency-Management erfolgt durch die Anwendung des Apply-Werkzeugs (dotnet dependencies-apply Execute) innerhalb des aus der Quellcodeverwaltung abgerufenen Solution-Verzeichnisses.

Die Ausführung von dotnet dependencies-apply ist idempotent und kann daher nach der erstmaligen Migration auch für die regelmäßige Aktualisierung verwendet werden.

Im Rahmen der Migration werden die paket.dependencies-Datei und alle paket.references-Dateien der Solution in ein einheitliches Format transformiert, das

• jeder Gruppe mindestens ein DependencySet zuordnet und die korrespondierende external_lock-Datei in die external_lock-URL der Gruppe einträgt,
• die source-URLs in eine einheitliche Reihenfolge sortiert³,
• die NuGet-Packages jeder Gruppe anhand ihrer Namespaces in Abschnitte zusammenfasst und sortiert, wobei jeder Abschnitt mit einer Kommentarzeile als Überschrift versehen wird.
  Die aktuell unterschiedenen Namespace-Abschnitte sind in Reihenfolge ihrer Sortierung:
  • System - System.*-Packages
  • Microsoft - Microsoft.*-Packages
  • 3rd party Schleupen - 3rd-Party-Packages mit "schleupen" als prerelease-label
  • 3rd party - sonstige 3rd-Party-Packages
  • Schleupen-Packages Schleupen.CS.* und Schleupen.XS.*, gruppiert nach den Komponenten ihrer Namespaces ohne das führende "Schleupen."
    • Schleupen.CS.X.Y.* -> "CS.X.Y"
    • Schleupen.XS.A.B.* -> "XS.A.B"
  • sonstige Schleupen-Packages, gruppiert nach den Komponenten ihrer Namespaces
    • Billing.*, Mako.*, Shared.* und weitere

Ressourcen

Nexus-Feeds

Das Dependency-Management verwendet folgende Feeds im Nexus-Repository zur Zuweisung an source-URLs in einer paket.dependencies-Datei:

Da die Reihenfolge von source-URLs und die Platzierung von Packages relativ zu den source-URLs in paket.dependencies-Dateien eine Rolle spielt, werden die Feeds von den Werkzeugen des Dependency-Managements explizit in der o.g. Ordnung sortiert.
Diese Sortierung sollte nicht manuell verändert werden.

DependencySets

Inhalt

Aktuell sind die folgenden DependencySets definiert:

Beim Aufruf des dotnet-tools dependencies-apply kann das gewünschte DependencySet unter dem in Spalte Name der vorstehenden Tabelle angegebenen Bezeichner mit dem Parameter --externalLockFile einer Gruppe der paket.dependencies-Datei zugeordnet werden.

Für jedes DependencySet existiert zusätzlich zur main-Version noch eine Vorab-Version im Branch CI_Platform, die im Rahmen des Change-Managements für DependencySets verwendet wird.

Beispiele:

dotnet dependencies-apply -elf Main=external_lock_NetCore8

dotnet dependencies-apply -elf Main=external_lock_NetFramework@CI_Platform

• Die Verwendung von DependencySets in Schleupen.CS Solutions der Fachteams soll grundsätzlich aus dem main-Branch des Repositories https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_git/xs-Schleupen.XS.PI.DependencySets erfolgen.
• Die Verwendung von DependencySets in Schleupen.CS Solutions der Plattform soll grundsätzlich aus dem CI_Platform-Branch erfolgen.
• Die Aktualisierung von DependencySets durch die Plattform soll grundsätzlich im update-Branch erfolgen und nur die jeweiligen extenal_lock_*-Dateien in den CI_Platform-Branch überführt werden.
  Die Überführung aus CI_Platform in main soll erst nach Bereitstellung aller Plattform-APIs auf dem aktualisierten Stand erfolgen.

Ablage

Die den DependencySets zugeordneten external_lock-Dateien sind in der Quellcodeverwaltung an folgenden Positionen abgelegt:

Name	URL
NetCore8	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetCore8/external_lock_NetCore
NetCore8.Build	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetCore8.Build/external_lock_NetCore.Build
NetFramework	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework/external_lock_NetFramework
NetFramework.Build	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework.Build/external_lock_NetFramework.Build
NetFramework.NHibernate51	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework.NHibernate51/external_lock_NetFramework.NHibernate51
NetFramework.NHibernate55	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework.NHibernate55/external_lock_NetFramework.NHibernate55
NetFramework.FluentValidation6	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework.NHibernate55/external_lock_NetFramework.FluentValidation6
NetFramework.FluentValidation10	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetFramework.NHibernate55/external_lock_NetFramework.FluentValidation10
NetStandard2	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetStandard2/external_lock_NetStandard
NetStandard2.Build	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/NetStandard2.Build/external_lock_NetStandard.Build
VisualStudio18	https://tfsprod.schleupen-ag.de/tfs/DefaultCollection/CS3/_apis/git/repositories/xs-Schleupen.XS.PI.DependencySets/items?path=/VisualStudio18/external_lock_VisualStudio

Werkzeuge

Die Werkzeuge des Dependency-Management werden in Form von dotnet-tools bereitgestellt.

Für die allgemeine Verwendung zum Dependency-Management in Fach-Solution ist dies:

• dependencies-apply - dient der Migration von Solutions aus dem bisherigen Verfahren in das Dependency-Management und der regelmäßigen Dependency-Aktualisierung

Zur Aktualisierung der DependencySets in der Plattform stehen darüber hinaus bereit:

• dependencies-prepare - dient der Erstellung und Aktualisierung von DependencySets und der Pflege des kuratierten Feeds im Nexus-Proxy
• dependencies-analyze - stellt interne Werkzeuge der Plattform zur Analyse von GIT-Repositories und Build-Pipelines im Schleusen Azure DevOps Server bereit
• dependencies-migrate - stellt weitere interne Werkzeuge der Plattform zur Pflege von Build Tasks und GIT Repositories im Azure DevOps Server bereit

Alle o.g. dotnet-tools sollten regelmäßig bzw. vor ihrer Verwendung mittels dotnet tool update auf den neuesten Stand gebracht werden.

Der Rückgabewert der dotnet-tools des Dependency-Managements entspricht
- 0 bei erfolgreicher Ausführung
- einem Wert > 0 bei Ausführung mit Fehlern, die zum Abbruch führten
- einem Wert < 0 bei Ausführung mit nicht-kritischen Warnungen

dependencies-apply

Bei Aufruf des dotnet-Kommandos dependencies-apply mit der Option --help wird die nachfolgende Hilfe angezeigt:

> dotnet dependencies-apply --help
Description:
  Schleupen.CS Dependency Management - Application

Usage:
  Schleupen.XS.PI.DependencyManagement.Application [command] [options]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  Execute <dependenciesFile>                                 Orchestrates the execution of dependency-related tasks on a solution. [default: paket.dependencies]
  Apply, ApplyExternalLock <dependenciesFile>                Applies the specified external_lock file(s). [default: paket.dependencies]
  Consolidate, ConsolidatePackageSources <dependenciesFile>  Consolidates sources for direct and transitive Schleupen package references. [default: paket.dependencies]
  Check, CheckPackages <lockFile>                            Checks the paket.lock file for acceptable packages. [default: paket.lock]
  EnsureSolutionDefaults <directory>                         Ensures default configuration on solution files in the specified directory.
  Validate, ValidateVersions <lockFile>                      Validates the paket.lock file for supported versions. [default: paket.lock]
  Verify, VerifyWatermark <files>                            Verifies the watermark in generated files.
  WhatIf <dependenciesFile>                                  Checks the specified paket.lock file for compatibility with the specified external_lock file(s). [default: paket.dependencies]

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando Execute

Bündelt die Ausführung von ApplyExternalLock, ValidateVersions und CheckPackages.

> dotnet dependencies-apply Execute --help
Description:
  Orchestrates the execution of dependency-related tasks on a solution.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application Execute [<dependenciesFile>] [options]

Arguments:
  <dependenciesFile>  The paket.dependencies file [default: paket.dependencies]

Options:
  -elf, --externalLockFiles <externalLockFiles>                   Apply external_lock files to the associated groups
  -lf, --lockFile <lockFile>                                      The paket.lock file [default: paket.lock]
  -ih, --includeHints                                             Include version hint lines in paket.dependencies
  -vo, --versionConstraintOverrides <versionConstraintOverrides>  Apply version overrides to the associated groups
  -tlv, --targetLTSVersion <targetLTSVersion>                     Set target LTS version for Microsoft.* and System.* dependencies
  -ig, --ignoreGroups <ignoreGroups>                              Ignore specified group
  -onl, --online                                                  Check against online repository.
  -f, --force                                                     Forcibly overwrite existing locations
  -?, -h, --help                                                  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando ApplyExternalLock (Apply)

Wendet die konfigurierten DependencySets auf eine Solution an.

> dotnet dependencies-apply ApplyExternalLock --help
Description:
  Applies the specified external_lock file(s).

Usage:
  Schleupen.XS.PI.DependencyManagement.Application ApplyExternalLock [<dependenciesFile>] [options]

Arguments:
  <dependenciesFile>  The paket.dependencies file [default: paket.dependencies]

Options:
  -elf, --externalLockFiles <externalLockFiles>                   Apply external_lock files to the associated groups
  -lf, --lockFile <lockFile>                                      The paket.lock file [default: paket.lock]
  -ih, --includeHints                                             Include version hint lines in paket.dependencies
  -vo, --versionConstraintOverrides <versionConstraintOverrides>  Apply version overrides to the associated groups
  -ig, --ignoreGroups <ignoreGroups>                              Ignore specified group
  -?, -h, --help                                                  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando EnsureSolutionDefaults (Defaults)

Führt Anpassung an diversen Dateien einer Solutio aus, um ein Standard-konformes Verhalten sicherzustellen.

> dotnet dependencies-apply EnsureSolutionDefaults --help
Description:
  Ensures default configuration on solution files in the specified directory.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application EnsureSolutionDefaults <directory> [options]

Arguments:
  <directory>  The directory

Options:
  -?, -h, --help  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Die ausgeführten Anpassungen enthalten u.a.:
- Annotation von ProcessArtifacts-Projekten mit einem Tag zur Steuerung der UI-Artefaktgenerierung
- Festlegung des C#-Sprachlevels auf Version 13 in der Directory.Build.props-Datei
- Enterung aller illegalen <PackageReference>-Tags in Projektdateien

Kommando ConsolidatePackageSources (Consolidate)

Ergänzt bei Bedarf zusätzliche Hinweise in der paket.dependencies-Datei für die korrekte Zuordnung von transitiven Schleupen-Packages zu Nuget-Sources im Nexus.

> dotnet dependencies-apply ConsolidatePackageSources --help
Description:
  Consolidates sources for direct and transitive Schleupen package references.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application ConsolidatePackageSources [<dependenciesFile>] [options]

Arguments:
  <dependenciesFile>  The paket.dependencies file [default: paket.dependencies]

Options:
  -lf, --lockFile <lockFile>          The paket.lock file [default: paket.lock]
  -s, --simplify                      Simplify paket.dependencies
  -ig, --ignoreGroups <ignoreGroups>  Ignore specified group
  -?, -h, --help                      Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando CheckPackages (Check)

Prüft die in der angegebenen paket.lock-Datei enthaltenen Dependencies auf konforme Lizenzen (z.B. MIT, Apache, MS-PL, aber nicht GPL).

> dotnet dependencies-apply CheckPackages --help
Description:
  Checks the paket.lock file for acceptable packages.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application CheckPackages [<lockFile>] [options]

Arguments:
  <lockFile>  The paket.lock file [default: paket.lock]

Options:
  -onl, --online  Check against online repository.
  -?, -h, --help  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando ValidateVersion (Validate)

Prüft die in der angegebenen paket.lock-Datei enthaltenen Dependencies auf konforme Versionen (z.B. Einhaltung der LTS-Bedingung für Microsoft- und System-Packages).

> dotnet dependencies-apply ValidateVersions --help
Description:
  Validates the paket.lock file for supported versions.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application ValidateVersions [<lockFile>] [options]

Arguments:
  <lockFile>  The paket.lock file [default: paket.lock]

Options:
  -tlv, --targetLTSVersion <targetLTSVersion>  Set target LTS version for Microsoft.* and System.* dependencies
  -ig, --ignoreGroups <ignoreGroups>           Ignore specified group
  -?, -h, --help                               Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando VerifyWatermark (Verify)

Prüft die Gültigkeit des in eine paket.dependencies, paket.lock oder paket.references-Datei integrierten Wasserzeichens.

> dotnet dependencies-apply VerifyWatermark --help
Description:
  Verifies the watermark in generated files.

Usage:
  Schleupen.XS.PI.DependencyManagement.Application VerifyWatermark <files>... [options]

Arguments:
  <files>  Any files

Options:
  -?, -h, --help  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

Kommando WhatIf

Zeigt die bei einer Ausführung von ApplyExternalLock bzw. Execute zu erwartenden Operationen an, ohne diese tatsächlich auszuführen.

> dotnet dependencies-apply VerifyWatermark --help
Description:
  Checks the specified paket.lock file for compatibility with the specified external_lock file(s).

Usage:
  Schleupen.XS.PI.DependencyManagement.Application WhatIf [<dependenciesFile>] [options]

Arguments:
  <dependenciesFile>  The paket.dependencies file [default: paket.dependencies]

Options:
  -lf, --lockFile <lockFile>                     The paket.lock file [default: paket.lock]
  -elf, --externalLockFiles <externalLockFiles>  Apply external_lock files to the associated groups
  -ig, --ignoreGroups <ignoreGroups>             Ignore specified group
  -?, -h, --help                                 Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled
        PackageToGroupMapping: Disabled
        WriteWatermark: Enabled

dependencies-prepare

Bei Aufruf des dotnet-Kommandos dependencies-prepare mit der Option --help wird die nachfolgende Hilfe angezeigt:

> dotnet dependencies-prepare --help
Description:
  Schleupen.CS Dependency Management - Preparation

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation [command] [options]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  Execute <externalLockFile>                       Orchestrates the execution tasks on a dependency set. [default: external_lock]
  Prepare, PrepareExternalLock <externalLockFile>  Prepares the external_lock file. [default: external_lock]
  Check, CheckPackages <externalLockFile>          Checks the paket.lock file for acceptable packages. [default: external_lock]
  Validate, ValidateVersions <externalLockFile>    Validates the paket.lock file for supported versions. [default: external_lock]
  Upload, UploadPackages <externalLockFile>        Uploads all packages specified in the external_lock file to the repository. [default: external_lock]
  Delete, DeletePackages <versionedPackageNames>   Deletes the specified packages from the repository.

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Kommando Execute

Bündelt die Ausführung von PrepareExternalLock, ValidateVersions und CheckPackages.

> dotnet dependencies-prepare Execute --help
Description:
  Orchestrates the execution tasks on a dependency set.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation Execute [<externalLockFile>] [options]

Arguments:
  <externalLockFile>  The external_lock file [default: external_lock]

Options:
  -df, --dependenciesFile <dependenciesFile>     The paket.dependencies file [default: paket.dependencies]
  -lf, --lockFile <lockFile>                     The paket.lock file [default: paket.lock]
  -tlv, --targetLTSVersion <targetLTSVersion>    Set target LTS version for Microsoft.* and System.* dependencies
  -ens, --excludeNamespaces <excludeNamespaces>  The namespaces to exclude [default: Schleupen.|Billing.|Mako.|Shared.|YAEC.|DatabaseSchema.]
  -rvc, --rebuildVersionCache                    Rebuild cache of latest accepted package versions
  -onl, --online                                 Check against online repository.
  -f, --force                                    Forcibly execute, disregarding validation errors
  -?, -h, --help                                 Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Kommando PrepareExternalLock (Prepare)

Dient der Aktualisierung der external_lock_*-Datei eines DependencySets auf den aktuellen Stand der verfügbaren Packages entsprechend der in der korrespondierenden paket.dependencies-Datei angegebenen Versionseinschränkungen.

> dotnet dependencies-prepare PrepareExternalLock --help
Description:
  Prepares the external_lock file.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation PrepareExternalLock [<externalLockFile>] [options]

Arguments:
  <externalLockFile>  The external_lock file [default: external_lock]

Options:
  -df, --dependenciesFile <dependenciesFile>     The paket.dependencies file [default: paket.dependencies]
  -lf, --lockFile <lockFile>                     The paket.lock file [default: paket.lock]
  -tlv, --targetLTSVersion <targetLTSVersion>    Set target LTS version for Microsoft.* and System.* dependencies
  -ens, --excludeNamespaces <excludeNamespaces>  The namespaces to exclude [default: Schleupen.|Billing.|Mako.|Shared.|YAEC.|DatabaseSchema.]
  -rvc, --rebuildVersionCache                    Rebuild cache of latest accepted package versions
  -f, --force                                    Forcibly execute, disregarding validation errors
  -?, -h, --help                                 Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Kommando CheckPackages (Check)

Prüft die in der angegebenen paket.lock-Datei enthaltenen Dependencies auf konforme Lizenzen (z.B. MIT, Apache, MS-PL, aber nicht GPL).

> dotnet dependencies-prepare CheckPackages --help
Description:
  Checks the paket.lock file for acceptable packages.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation CheckPackages [<externalLockFile>] [options]

Arguments:
  <externalLockFile>  The external_lock file [default: external_lock]

Options:
  -onl, --online  Check against online repository.
  -?, -h, --help  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Kommando ValidateVersions (Validate)

Prüft die in der angegebenen paket.lock-Datei enthaltenen Dependencies auf konforme Versionen (z.B. Einhaltung der LTS-Bedingung für Microsoft- und System-Packages).

> dotnet dependencies-prepare ValidateVersions --help
Description:
  Validates the paket.lock file for supported versions.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation ValidateVersions [<externalLockFile>] [options]

Arguments:
  <externalLockFile>  The external_lock file [default: external_lock]

Options:
  -tlv, --targetLTSVersion <targetLTSVersion>  Set target LTS version for Microsoft.* and System.* dependencies
  -?, -h, --help                               Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Kommando UploadPackages (Upload)

Stellt die in einem DependencySet (bzw. der korrespondierenden external_lock_*-Datei) spezifizierten Packages im Curated Feed des Nexus-Repositories bereit.

> dotnet dependencies-prepare UploadPackages --help
Description:
  Uploads all packages specified in the external_lock file to the repository.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation UploadPackages [<externalLockFile>] [options]

Arguments:
  <externalLockFile>  The external_lock file [default: external_lock]

Options:
  -ens, --excludeNamespaces <excludeNamespaces>  The namespaces to exclude [default: Schleupen.|Billing.|Mako.|Shared.|YAEC.|DatabaseSchema.]
  -?, -h, --help                                 Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Da der Index des Nexus-Repositories sich nur mit deutlicher Verzögerung aktualisier,t, kann es bei wiederholten Upload-Versuchen für dieselben Packages zu Fehlern kommen. Diese können ignoriert werden.

Kommando DeletePackages (Delete)

Löscht die angegebenen Packages aus dem Curated-Feed des Nexus-Repositories.

> dotnet dependencies-prepare DeletePackages --help
Description:
  Deletes the specified packages from the repository.

Usage:
  Schleupen.XS.PI.DependencyManagement.Preparation DeletePackages <versionedPackageNames>... [options]

Arguments:
  <versionedPackageNames>  The package names and versions

Options:
  -?, -h, --help  Show help and usage information

Feature toggles:
        BackupChangedFiles: Disabled
        FilterPaketErrors: Enabled

Feature Toggles

Feature Toggles, die das Verhalten von Kommandos des Dependency-Managements beeinflussen, können über Umgebungsvariablen verändert werden.

Beispiel:

Der Feature Toggle FilterPaketErrors kann vor der Ausführung des Kommandos dotnet dependencies-prepare Execute mit dem folgenden Kommandozeilenbefehl aktiviert werden, um Detailfehlermeldungen der Ausführung von dotnet paket update angezeigt zu bekommen:

set FeatureManagement__FilterPaketErrors=false

Fußnoten

1. Zur Behandlung von Endlosschleifen wird das paket update-Kommando nach einer maximalen Laufzeit von 3 Minuten abgebrochen. ↩︎
2. Insbesondere für solche Packages, deren Verwendung durch ihr Lizenzmodell nur in bestimmten Versionsbereichen möglich ist, erfolgt die Beschränkung auf eine akzeptable Version bereits in der Vorberechnung des DependencySets. ↩︎
3. Aus technischen Gründen muss für eine korrekte Auflösung durch paket die folgende Reihenfolge eingehalten werden:
   - externe Abhängigkeiten
   - Schleupen.CS-Packages in absteigender Ordnung der Qualitätsstufen der CD-Pipeline, i.e. RC -> Dev -> CI -> Platform_Dev -> Platform_CI
   - Schleupen.CS-Entwicklungs-Packages ↩︎