Buildpipeline

Wo die Verschleierung läuft

Standardmäßig führt das Paket Babel direkt nach CoreCompile aus, und zwar auf der Assembly, die der Compiler gerade in den Zwischenordner geschrieben hat, $(IntermediateOutputPath)$(TargetFileName), also in den Ordner obj. Jeder spätere Schritt des Builds arbeitet dann mit der verschleierten Assembly: die Kopie nach bin, die Erzeugung von .deps.json, die Satelliten-Assemblys und beim Veröffentlichen das Trimming, die Einzeldateibündelung, die ReadyToRun- oder NativeAOT-Kompilierung und das Verpacken in ein APK oder ein App-Bundle.

Diese Reihenfolge ist der Grund, das Paket in Projekten im SDK-Stil zu verwenden. Das .NET SDK schreibt den IL-Code nach der Kompilierung um, und Babel muss die Assembly vorher sehen. Eine Assembly aus bin oder aus dem Veröffentlichungsordner hat diese Schritte bereits durchlaufen. Die Aufgabe von Hand nach CoreCompile zu platzieren, ist fehleranfällig, weil die genaue Abfolge der Ziele vom Projekttyp und von der SDK-Version abhängt. Das Paket löst das für Sie.

Zwei weitere Regeln halten die IDE reaktionsfähig:

• Entwurfszeitbuilds werden übersprungen. Visual Studio und Codeanalysetools führen ständig Hintergrundbuilds aus. Das Paket fügt den Verschleierungsschritt in diese Builds nicht ein.
• Die Verschleierung läuft nur, wenn der Compiler gelaufen ist. Ein inkrementeller Build, der die Assembly auf dem aktuellen Stand vorfindet, überspringt auch Babel, sodass die bereits verschleierte Assembly in obj nie zweimal verarbeitet wird.

Den Verschleierungsschritt verschieben

Drei Eigenschaften ändern den Einfügepunkt:

Wenn Sie eine dieser Eigenschaften setzen, wird die Standardplatzierung nach CoreCompile ausgeschaltet. Mit BabelAfterTargets oder BabelBeforeTargets verarbeitet Babel weiterhin die Zwischen-Assembly. Läuft das gewählte Ziel erst, nachdem die Ausgabe kopiert wurde, lassen Sie BabelInputFile und BabelOutputFile auf $(TargetPath) zeigen.

Ein typischer Anwendungsfall ist eine Windows-Forms-Anwendung mit lokalisierten Ressourcen. Dort sollte Babel laufen, sobald die Satelliten-Assemblys erzeugt sind, damit es auch diese verarbeiten kann:

<PropertyGroup>
  <BabelAfterTargets>CoreGenerateSatelliteAssemblies</BabelAfterTargets>
</PropertyGroup>

Abfolge der Ziele und Erweiterungspunkte

Der Verschleierungsschritt ist das Ziel ObfuscateBuild. Es bereitet zuerst die Konfiguration der Babel-Aufgabe vor und führt sie dann aus:

ObfuscateBuild
├─ ObfuscateSettings
│  ├─ ObfuscateDefaultSettings      renaming defaults, license lookup, babelRules.xml, search directories
│  ├─ ObfuscateFrameworkSettings    selects the assembly to process (obj, or $(TargetPath))
│  ├─ ObfuscateSetupBabelFiles      BabelInputFile / BabelOutputFile, GenerateDebug when a PDB exists
│  ├─ ObfuscateCustomSettings       empty, yours to redefine
│  ├─ SetupObfuscate                empty, yours to redefine
│  └─ ConfigureBabel                empty, yours to redefine
└─ Obfuscate
   ├─ BeforeObfuscate               empty, yours to redefine
   ├─ CoreObfuscate                 runs the Babel task
   └─ AfterObfuscate                empty, yours to redefine

Definieren Sie ein leeres Ziel in der Projektdatei neu, um an dieser Stelle eigene Schritte auszuführen:

CoreObfuscate stellt zwei Ausgaben bereit, die Sie in AfterObfuscate lesen können: die Eigenschaft BabelExitCode und das Element @(BabelCommandLineArgs), das die Befehlszeile enthält, wenn BabelProvideCommandLineArgs den Wert true hat.

Die Konfiguration der Aufgabe überschreiben

Das Paket konfiguriert die Babel-Aufgabe aus dem Projekt: die Suchverzeichnisse aus den Referenzen, den Schlüssel für den starken Namen, die PDB-Datei, die Regeldatei. Wenn die Standardwerte nicht passen, ändern Sie sie in BeforeObfuscate. Das folgende Beispiel erzwingt die Erzeugung von Debugsymbolen und ersetzt die Suchverzeichnisse durch den Ausgabeordner:

<Target Name="BeforeObfuscate">
  <!-- Override computed properties -->
  <PropertyGroup>
    <GenerateDebug>true</GenerateDebug>
  </PropertyGroup>
 
  <!-- Replace the Babel search directories -->
  <ItemGroup>
    <BabelSearchDirectories Remove="@(BabelSearchDirectories)" />
    <BabelSearchDirectories Include="$(TargetDir)" />
  </ItemGroup>
</Target>

BeforeObfuscate ist auch die Stelle, an der Sie eine zweite Babel-Aufgabe auf einer Abhängigkeit ausführen, bevor die Hauptassembly verschleiert wird. Das Beispiel .NET-App veröffentlichen tut das, um die öffentliche Schnittstelle eines NuGet-Pakets mit der assemblyübergreifenden Umbenennung umzubenennen.

Ein Ziel AfterObfuscate kann die Artefakte einsammeln, die Babel erzeugt hat, zum Beispiel die Map-Datei für einen gemeinsamen Ordner, den das Beispiel Unit-Tests verwendet:

<PropertyGroup>
  <GenerateMapOutFile>true</GenerateMapOutFile>
  <BabelMapOutFile>$(IntermediateOutputPath)$(TargetFileName).map.xml</BabelMapOutFile>
</PropertyGroup>
 
<Target Name="AfterObfuscate">
  <Copy SourceFiles="$(BabelMapOutFile)" DestinationFolder="$(SolutionDir)MapOut" />
</Target>

Veröffentlichen

Weil die Verschleierung vor den Veröffentlichungsschritten stattfindet, erzeugen dotnet publish und die Veröffentlichungsprofile von Visual Studio ohne zusätzliche Konfiguration eine verschleierte Ausgabe. Das Paket nimmt darüber hinaus drei Anpassungen vor:

• Zusammengeführte und eingebettete Assemblys werden aus den zu veröffentlichenden Dateien entfernt. Das Ziel UpdateBabelFilesToPublish, das nach ComputeFilesToPublish läuft, nimmt jedes Element MergeAssembly und EmbedAssembly samt seinen .pdb- und .xml-Dateien aus den zu veröffentlichenden Dateien heraus. Setzen Sie BabelPublishEnabled auf false, um sie zu behalten.
• Die .deps.json-Dateien werden aktualisiert. Die Ziele UpdateBabelBuildDependencyFile und UpdateBabelPublishDependencyFile entfernen die zusammengeführten und eingebetteten Assemblys sowie das Paket selbst aus den Abhängigkeitsmanifesten des Builds und der Veröffentlichung, damit der Host nicht nach Assemblys sucht, die es als eigene Dateien nicht mehr gibt. Setzen Sie BabelUpdateDependencyFile auf false, um die Manifeste unverändert zu lassen.
• Debugsymbole werden in Release nicht veröffentlicht. Das Paket setzt CopyOutputSymbolsToPublishDirectory für die Release-Konfiguration auf false, sofern das Projekt die Eigenschaft nicht selbst setzt, weil PDB-Dateien einem Angreifer die Dateinamen und Zeilennummern des ursprünglichen Codes liefern. Setzen Sie sie auf true, um die Symbole trotzdem zu veröffentlichen.

Die Veröffentlichung als Einzeldatei, getrimmt oder mit AOT funktioniert mit der verschleierten Assembly, mit zwei Einschränkungen: Die Manipulationsprüfung für Desktop-Ziele kann ein Einzeldatei-Abbild nicht prüfen, und Babel warnt davor (siehe Manipulationserkennung), und für .NET MAUI unter iOS sollte der Linker auf Link SDK assemblies only gesetzt werden, wie unter .NET MAUI verschleiern erläutert.

Die Buildtools auswählen

Das Paket liefert je MSBuild-Host einen Satz von Babel-Buildtools mit und wählt ihn anhand des Hosts aus, der den Build ausführt:

Der ausgewählte Ordner steht als BabelTaskDir zur Verfügung, und BabelPackageDir zeigt auf das Stammverzeichnis des entpackten Pakets. Um einen anderen Satz von Tools zu erzwingen, setzen Sie BabelTaskDir in der Projektdatei:

<PropertyGroup>
  <BabelTaskDir>$(BabelPackageDir)tools\net8.0\</BabelTaskDir>
</PropertyGroup>

Setzen Sie die Eigenschaft in der Projektdatei oder in Directory.Build.targets, nicht in Directory.Build.props: Die eigene .props-Datei des Pakets wird nach Directory.Build.props importiert und würde den Wert überschreiben.

Um ein Babel auszuführen, das außerhalb des Pakets installiert ist, zum Beispiel das aus einem Zip-Paket babel_net* entpackte Befehlszeilentool, setzen Sie BabelPath auf dessen Ordner und bei Bedarf BabelExe auf den Namen der ausführbaren Datei (babel.exe oder babel.dll).

Buildserver

Nichts im Paket ist an einen bestimmten Rechner gebunden. Ein Projekt, das auf einem Entwickler-PC verschleiert erstellt wird, wird daher auf jedem Agent verschleiert erstellt, der das Paket wiederherstellen und eine Lizenz erreichen kann. Die Beispiele decken die gängigen Dienste ab:

• GitHub Actions: Paket in GitHub Packages, Lizenzschlüssel aus einem Geheimnis des Repositorys.
• Azure DevOps: Paket in einem Feed von Azure Artifacts, Lizenzschlüssel aus einer geheimen Pipelinevariable.
• AppVeyor: Paket im Feed des Kontos, Lizenzschlüssel aus einer verschlüsselten Variable.
• Unit-Tests: die verschleierten Assemblys in derselben Pipeline testen.

Linux-Agents und Container führen den Build tools\netX.0 von Babel aus. Hosts mit einer defekten FIPS-Konfiguration von OpenSSL brauchen die unter FIPS-Konformität beschriebenen Einstellungen.