Paketeinrichtung

Das Paket hosten

Die NuGet-Pakete von Babel sind nicht auf nuget.org veröffentlicht. Jeder Build, der Babel.Obfuscator referenziert, muss das Paket aus einem Feed wiederherstellen können, den Sie kontrollieren:

• Ein privater Feed wie Azure Artifacts, GitHub Packages, GitLab, MyGet oder ein selbst gehosteter NuGet-Server. Das ist die richtige Wahl für Buildserver und Teams. Das Beispiel GitHub Actions zeigt, wie Sie das Paket nach GitHub Packages hochladen und den Wiederherstellungsschritt mit einem Token authentifizieren.
• Ein lokaler Ordner, der als Paketquelle registriert ist. Das genügt für den Rechner eines einzelnen Entwicklers.

Beide Möglichkeiten sind Schritt für Schritt unter Installation beschrieben. Wie auch immer Sie sich entscheiden: Legen Sie die Feedkonfiguration in einer Datei NuGet.config neben der Projektmappe ab, damit dotnet restore das Paket auf jedem Rechner findet, auch auf CI-Agents:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="babel" value="https://nuget.pkg.github.com/YOUR_ORG/index.json" />
  </packageSources>
</configuration>

Die Paketreferenz hinzufügen

In Visual Studio

Klicken Sie im Solution Explorer mit der rechten Maustaste auf das Projekt, wählen Sie Manage NuGet Packages… (NuGet-Pakete verwalten…), wählen Sie die Paketquelle aus, die die Babel-Pakete hostet, und installieren Sie Babel.Obfuscator. Visual Studio fügt der Projektdatei eine PackageReference mit den richtigen Metadaten hinzu.

Mit der dotnet CLI

dotnet add package Babel.Obfuscator

Durch Bearbeiten der Projektdatei

Fügen Sie der .csproj- oder .vbproj-Datei das folgende Element hinzu:

<ItemGroup>
  <PackageReference Include="Babel.Obfuscator" Version="12.0.0">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
</ItemGroup>

Die beiden Metadatenelemente sind wichtig:

• PrivateAssets mit dem Wert all kennzeichnet das Paket als Entwicklungsabhängigkeit. Es wird daher nicht an die Projekte oder Pakete weitergegeben, die Ihr Projekt referenzieren.
• IncludeAssets bindet die build-Assets ein, in denen die .props- und .targets-Dateien des Pakets liegen. Fehlt build in der Liste, wird die Babel-Aufgabe nie in das Projekt eingebunden, und nichts wird verschleiert.

Mehrere Projekte in einer Projektmappe

Um mehrere Projekte zu verschleiern, ohne die Referenz zu wiederholen, legen Sie sie in einer Datei Directory.Build.props im Stammverzeichnis des Repositorys ab. Eine Bedingung hält Testprojekte und andere Projekte, die nicht ausgeliefert werden, heraus:

<Project>
  <ItemGroup Condition="!$(MSBuildProjectName.EndsWith('.Tests'))">
    <PackageReference Include="Babel.Obfuscator" Version="12.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Wenn Sie die zentrale Paketverwaltung  verwenden, deklarieren Sie die Version einmal mit einem Element PackageVersion in Directory.Packages.props und entfernen Sie das Attribut Version aus der PackageReference.

Die Lizenz aktivieren

Die Babel-Aufgabe benötigt bei jeder Ausführung eine gültige Lizenz. Das Paket sucht sie in dieser Reihenfolge:

1. Die Eigenschaft BabelLicense, wenn sie im Projekt gesetzt ist.
2. Eine Datei babel.licenses im Projektordner oder in einem übergeordneten Ordner. Es genügt daher, die Lizenzdatei neben die Projektmappendatei zu kopieren, damit sie für jedes Projekt der Projektmappe gilt.

BabelLicense akzeptiert dieselben Werte wie der Befehlszeilenschalter --license: den Pfad einer Lizenzdatei, einen Lizenzschlüssel oder den Benutzerschlüssel einer Floating-Lizenz:

<PropertyGroup>
  <!-- A license file -->
  <BabelLicense>$(MSBuildThisFileDirectory)build\babel.licenses</BabelLicense>
 
  <!-- or a license key held in an environment variable (a build server secret) -->
  <BabelLicense>$(BABEL_LICENSE)</BabelLicense>
 
  <!-- or a floating license user key -->
  <BabelLicense>floating:P1N1J-EH5VA-VGSFU-7EOK8</BabelLicense>
</PropertyGroup>

Halten Sie den Schlüssel auf Buildservern aus dem Repository heraus: Speichern Sie ihn als Geheimnis, stellen Sie ihn dem Buildschritt als Umgebungsvariable bereit und referenzieren Sie diese Variable in BabelLicense, wie es das Beispiel GitHub Actions zeigt. Floating-Lizenzen sind unter Produktaktivierung beschrieben.

Evaluierungsmodus

Wird keine Lizenz gefunden, läuft Babel im Evaluierungsmodus: Es wird nur die Umbenennung von Symbolen angewendet, und die verschleierte Assembly funktioniert nach kurzer Zeit nicht mehr, wie die Warnung W00000 im Buildprotokoll meldet. Damit eine solche Assembly den Buildserver nie verlässt, machen Sie diese Warnung zu einem Fehler:

<PropertyGroup>
  <BabelWarningsAsErrors>W00000</BabelWarningsAsErrors>
</PropertyGroup>

Erstellen und prüfen

Erstellen Sie das Projekt wie gewohnt, aus Visual Studio, mit dotnet build oder mit msbuild. Das Babel-Protokoll wird mit der durch VerboseLevel festgelegten Ausführlichkeit (standardmäßig 1) in die Buildausgabe geschrieben.

dotnet build -c Release

Um genau zu sehen, wie das Paket Babel aufruft, setzen Sie BabelProvideCommandLineArgs auf true: Die vollständige Befehlszeile wird in das Protokoll geschrieben und im Element @(BabelCommandLineArgs) gespeichert. Das ist nützlich, um ein Buildproblem mit dem Befehlszeilentool nachzustellen. GenerateLogFile schreibt das vollständige Verschleierungsprotokoll in eine Datei neben der Ziel-Assembly oder an den mit BabelLogFile festgelegten Pfad.

Vergewissern Sie sich, dass die Ausgabe verschleiert ist, indem Sie die erstellte Assembly mit einem Decompiler öffnen oder die Statistiken am Ende des Babel-Protokolls lesen. Babel verarbeitet die Assembly, die der Compiler in den Zwischenordner obj schreibt, daher sind die Kopien in bin und im Veröffentlichungsordner alle verschleiert. Siehe Buildpipeline.

Verschleierung für eine Konfiguration ausschalten

In Debug-Builds ist die Verschleierung selten erwünscht. Setzen Sie BabelEnabled in der Debug-Konfiguration auf false, und das Paket überspringt jeden Babel-Schritt, einschließlich der Anpassungen beim Veröffentlichen:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <BabelEnabled>false</BabelEnabled>
</PropertyGroup>

Dieselbe Eigenschaft lässt sich für einen einmaligen unverschleierten Build von der Befehlszeile aus umschalten:

dotnet build -c Release -p:BabelEnabled=false

Das Paket aktualisieren

Jede Babel-Version liefert eine neue Paketversion zusammen mit einer neuen Lizenzdatei. So aktualisieren Sie:

Halten Sie Babel.Obfuscator und Babel.Obfuscator.Tool auf derselben Version, wenn Sie beide verwenden.