Configurazione del pacchetto

Ospitare il pacchetto

I pacchetti NuGet di Babel non sono pubblicati su nuget.org. Ogni build che referenzia Babel.Obfuscator deve poterlo ripristinare da un feed che controlli tu:

• Un feed privato come Azure Artifacts, GitHub Packages, GitLab, MyGet o un server NuGet ospitato in proprio. È la scelta giusta per i server di build e per i team. L’esempio GitHub Actions mostra come caricare il pacchetto su GitHub Packages e come autenticare il passo di ripristino con un token.
• Una cartella locale registrata come origine pacchetti, sufficiente per il computer di un singolo sviluppatore.

Entrambe le opzioni sono descritte passo per passo in Installazione. Qualunque tu scelga, conserva la configurazione del feed in un file NuGet.config accanto alla soluzione, così dotnet restore trova il pacchetto su ogni computer, agenti CI compresi:

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

Aggiungere il riferimento al pacchetto

Da Visual Studio

Fai clic con il pulsante destro sul progetto in Solution Explorer, scegli Manage NuGet Packages…, seleziona l’origine pacchetti che ospita i pacchetti Babel e installa Babel.Obfuscator. Visual Studio aggiunge al file di progetto un PackageReference con i metadati corretti.

Dalla CLI dotnet

dotnet add package Babel.Obfuscator

Modificando il file di progetto

Aggiungi il seguente elemento al file .csproj o .vbproj:

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

I due elementi di metadati sono importanti:

• PrivateAssets impostato su all contrassegna il pacchetto come dipendenza di sviluppo, così non viene propagato ai progetti o ai pacchetti che referenziano il tuo.
• IncludeAssets include gli asset build, dove si trovano i file .props e .targets del pacchetto. Senza build nell’elenco il task Babel non viene mai collegato al progetto e non viene offuscato nulla.

Più progetti in una soluzione

Per offuscare più progetti senza ripetere il riferimento, inseriscilo in un file Directory.Build.props nella radice del repository. Una condizione esclude i progetti di test e gli altri progetti che non vengono distribuiti:

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

Se usi la gestione centrale dei pacchetti , dichiara la versione una sola volta con un elemento PackageVersion in Directory.Packages.props e togli l’attributo Version dal PackageReference.

Attivare la licenza

Il task Babel ha bisogno di una licenza valida a ogni esecuzione. Il pacchetto la cerca in quest’ordine:

1. La proprietà BabelLicense, se impostata nel progetto.
2. Un file babel.licenses nella cartella del progetto o in una qualsiasi cartella superiore. Basta quindi copiare il file di licenza accanto al file della soluzione perché valga per ogni progetto della soluzione.

BabelLicense accetta gli stessi valori dell’opzione --license della riga di comando: il percorso di un file di licenza, una chiave di licenza o la chiave utente di una licenza 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>

Sui server di build tieni la chiave fuori dal repository: salvala come segreto, esponila al passo di build come variabile d’ambiente e fai riferimento a quella variabile da BabelLicense, come fa l’esempio GitHub Actions. Le licenze flottanti sono descritte in Attivazione del prodotto.

Modalità demo

Quando non viene trovata alcuna licenza, Babel funziona in modalità demo: viene applicata solo la ridenominazione dei simboli e l’assembly offuscato smette di funzionare dopo un breve periodo, come segnala l’avviso W00000 nel log di build. Per fare in modo che un assembly di questo tipo non esca mai dal server di build, trasforma quell’avviso in un errore:

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

Compilare e verificare

Compila il progetto come al solito, da Visual Studio, con dotnet build o con msbuild. Il log di Babel viene scritto nell’output della build con il livello di dettaglio impostato da VerboseLevel (1 per impostazione predefinita).

dotnet build -c Release

Per vedere esattamente come il pacchetto richiama Babel, imposta BabelProvideCommandLineArgs su true: la riga di comando completa viene scritta nel log e memorizzata nell’elemento @(BabelCommandLineArgs), utile per riprodurre un problema di build con lo strumento da riga di comando. GenerateLogFile scrive il log di offuscamento completo in un file accanto all’assembly target, oppure nel percorso impostato da BabelLogFile.

Verifica che l’output sia offuscato aprendo l’assembly compilato con un decompilatore, oppure leggendo le statistiche stampate alla fine del log di Babel. Babel elabora l’assembly che il compilatore scrive nella cartella intermedia obj, quindi le copie in bin e nella cartella di pubblicazione sono tutte offuscate. Vedi Pipeline di build.

Disabilitare l’offuscamento per una configurazione

Nelle build Debug l’offuscamento serve di rado. Imposta BabelEnabled su false nella configurazione Debug e il pacchetto salta ogni passo di Babel, compresi gli adattamenti della pubblicazione:

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

La stessa proprietà può essere cambiata dalla riga di comando per una singola build non offuscata:

dotnet build -c Release -p:BabelEnabled=false

Aggiornare il pacchetto

Ogni rilascio di Babel include una nuova versione del pacchetto insieme a un nuovo file di licenza. Per aggiornare:

Mantieni Babel.Obfuscator e Babel.Obfuscator.Tool alla stessa versione quando li usi entrambi.