Configuration du package

Héberger le package

Les packages NuGet de Babel ne sont pas publiés sur nuget.org. Chaque build qui référence Babel.Obfuscator doit pouvoir le restaurer depuis un flux que vous contrôlez :

• Un flux privé, tel qu’Azure Artifacts, GitHub Packages, GitLab, MyGet ou un serveur NuGet auto-hébergé. C’est le bon choix pour les serveurs de build et les équipes. L’exemple GitHub Actions montre comment envoyer le package vers GitHub Packages et comment authentifier l’étape de restauration avec un jeton.
• Un dossier local déclaré comme source de packages, ce qui suffit pour la machine d’un seul développeur.

Les deux options sont décrites pas à pas dans Installation. Quelle que soit celle que vous choisissez, conservez la configuration du flux dans un fichier NuGet.config à côté de la solution, afin que dotnet restore trouve le package sur chaque machine, agents de CI compris :

<?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>

Ajouter la référence de package

Depuis Visual Studio

Faites un clic droit sur le projet dans Solution Explorer (Explorateur de solutions), choisissez Manage NuGet Packages… (Gérer les packages NuGet), sélectionnez la source de packages qui héberge les packages Babel et installez Babel.Obfuscator. Visual Studio ajoute au fichier de projet une PackageReference avec les métadonnées correctes.

Depuis le CLI dotnet

dotnet add package Babel.Obfuscator

En modifiant le fichier de projet

Ajoutez l’élément suivant au fichier .csproj ou .vbproj :

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

Les deux éléments de métadonnées ont leur importance :

• PrivateAssets réglé sur all marque le package comme dépendance de développement : il n’est donc pas propagé aux projets ou aux packages qui référencent le vôtre.
• IncludeAssets intègre les ressources build, où se trouvent les fichiers .props et .targets du package. Sans build dans la liste, la tâche Babel n’est jamais raccordée au projet et rien n’est obfusqué.

Plusieurs projets dans une solution

Pour obfusquer plusieurs projets sans répéter la référence, placez-la dans un fichier Directory.Build.props à la racine du dépôt. Une condition écarte les projets de test et les autres projets qui ne sont pas livrés :

<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>

Si vous utilisez la gestion centralisée des packages , déclarez la version une seule fois avec un élément PackageVersion dans Directory.Packages.props et retirez l’attribut Version de la PackageReference.

Activer la licence

La tâche Babel a besoin d’une licence valide à chaque exécution. Le package en recherche une dans cet ordre :

1. La propriété BabelLicense, lorsqu’elle est définie dans le projet.
2. Un fichier babel.licenses dans le dossier du projet ou dans l’un de ses dossiers parents. Il suffit donc de copier le fichier de licence à côté du fichier de solution pour tous les projets de la solution.

BabelLicense accepte les mêmes valeurs que l’option de ligne de commande --license, à savoir le chemin d’un fichier de licence, une clé de licence ou la clé utilisateur d’une licence flottante :

<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>

Sur les serveurs de build, gardez la clé hors du dépôt : stockez-la comme secret, exposez-la à l’étape de build sous forme de variable d’environnement et référencez cette variable depuis BabelLicense, comme le fait l’exemple GitHub Actions. Les licences flottantes sont décrites dans Activation du produit.

Mode d’évaluation

Lorsqu’aucune licence n’est trouvée, Babel s’exécute en mode d’évaluation : seul le renommage des symboles est appliqué, et l’assembly obfusqué cesse de fonctionner après une courte période, comme le signale l’avertissement W00000 dans le journal du build. Pour qu’un tel assembly ne quitte jamais le serveur de build, transformez cet avertissement en erreur :

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

Générer et vérifier

Générez le projet comme d’habitude, depuis Visual Studio, avec dotnet build ou avec msbuild. Le journal de Babel est écrit dans la sortie du build avec le niveau de détail défini par VerboseLevel (1 par défaut).

dotnet build -c Release

Pour voir exactement comment le package appelle Babel, réglez BabelProvideCommandLineArgs sur true : la ligne de commande complète est écrite dans le journal et enregistrée dans l’élément @(BabelCommandLineArgs), ce qui est utile pour reproduire un problème de build avec l’outil en ligne de commande. GenerateLogFile écrit le journal d’obfuscation complet dans un fichier à côté de l’assembly cible, ou à l’emplacement défini par BabelLogFile.

Vérifiez que la sortie est obfusquée en ouvrant l’assembly généré avec un décompilateur, ou en lisant les statistiques affichées à la fin du journal de Babel. Babel traite l’assembly que le compilateur écrit dans le dossier intermédiaire obj : les copies présentes dans bin et dans le dossier de publication sont donc toutes obfusquées. Voir Pipeline de build.

Désactiver l’obfuscation pour une configuration

L’obfuscation est rarement souhaitée dans les builds Debug. Réglez BabelEnabled sur false dans la configuration Debug et le package ignore toutes les étapes de Babel, ajustements de publication compris :

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

La même propriété peut être modifiée depuis la ligne de commande pour un build ponctuel non obfusqué :

dotnet build -c Release -p:BabelEnabled=false

Mettre à jour le package

Chaque version de Babel fournit une nouvelle version du package accompagnée d’un nouveau fichier de licence. Pour mettre à jour :

Conservez Babel.Obfuscator et Babel.Obfuscator.Tool à la même version lorsque vous utilisez les deux.