Eine benutzerdefinierte MSBuild-Task obfuskieren, ohne sie zu zerstören
Eine benutzerdefinierte MSBuild-Task ist das Spiegelbild eines Quellcode-Generators. Der Compiler findet einen Generator über ein Attribut, sodass du die gesamte Klasse frei umbenennen kannst; MSBuild findet eine Task über die literale Typnamen-Zeichenfolge, die in ein UsingTask-Element geschrieben wurde, und liest ihre Parameter aus den öffentlichen Eigenschaftsnamen — beides ist also ein harter externer Vertrag, den die Umbenennung nicht antasten darf. Dieser Beitrag untersucht, worüber die MSBuild-Engine tatsächlich reflektiert, wenn sie deine Task ausführt, zieht die genaue Linie zwischen der kleinen festgenagelten Oberfläche und der wertvollen Logik, die sich problemlos umbenennen lässt, und zeigt die Nebula-Konfiguration sowie den Verifizierungs-Build, der den einzigen Fehlermodus abfängt, der lautlos ist.
Wenn du jemals einen Roslyn-Quellcode-Generator obfuskiert hast, kennst du das glückliche Ende: Der Compiler findet Generatoren über das Attribut [Generator], niemals über den Namen, sodass du die Klasse, ihren Namespace und jede Hilfsmethode umbenennen kannst, ohne etwas Besonderes konfigurieren zu müssen. Eine benutzerdefinierte MSBuild-Task ist genau das Spiegelbild davon, und es lohnt sich zu verstehen, warum, bevor du einen Obfuskator darauf richtest — denn der Fehler, den sie erzeugt, ist lautlos.
MSBuild findet deine Task nicht über ein Attribut. Es findet sie über eine Zeichenfolge mit dem Typnamen, die jemand in ein UsingTask-Element geschrieben hat, und es setzt die Eingaben der Task, indem es über die öffentlichen Eigenschaftsnamen reflektiert, die zu Attributen in der Build-Datei passen. Beides ist Text in einer .targets-Datei — deiner eigenen oder der des Projekts deines Konsumenten — und Text in einer Build-Datei wird nicht umgeschrieben, wenn dein Umbenenner a für die Klasse und b für die Eigenschaft wählt. Benenne sie um, und der Build findet deine Task nicht, oder er findet sie und verwirft lautlos jede Eingabe. Die gute Nachricht ist, genau wie bei einem Generator, dass die festgenagelte Oberfläche klein und spezifisch ist und der Code, den du wirklich verbergen möchtest, nicht dazugehört.
Worüber die Engine beim Ausführen deiner Task reflektiert
Hier ist eine minimale, echte Task — die Form, die du in einem NuGet-Tooling-Paket auslieferst:
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace Acme.Build;
public sealed class ValidateManifest : Task // Task : ITask
{
[Required]
public string ManifestPath { get; set; } = "";
public int MaxEntries { get; set; } = 1000;
[Output]
public string Fingerprint { get; set; } = "";
public override bool Execute()
{
var report = ManifestInspector.Analyze(ManifestPath, MaxEntries); // the valuable part
Fingerprint = report.Fingerprint;
if (report.HasErrors)
Log.LogError("ACMEB001: manifest failed validation: {0}", report.Summary);
return !Log.HasLoggedErrors;
}
}
Und so ruft ein Konsument sie auf — entweder über deine gepackte build/Acme.Build.targets oder von Hand in seinem eigenen Projekt geschrieben:
<UsingTask TaskName="Acme.Build.ValidateManifest"
AssemblyFile="$(MSBuildThisFileDirectory)..\tasks\Acme.Build.dll" />
<Target Name="CheckManifest" BeforeTargets="Build">
<ValidateManifest ManifestPath="$(ManifestFile)" MaxEntries="500">
<Output TaskParameter="Fingerprint" PropertyName="ManifestHash" />
</ValidateManifest>
</Target>
Wenn MSBuild dieses Target erreicht, tut es etwas sehr Spezifisches. Es lädt Acme.Build.dll, ruft assembly.GetType("Acme.Build.ValidateManifest") mit der exakten Zeichenfolge aus TaskName auf, instanziiert sie mit Activator.CreateInstance und sucht dann — für jedes XML-Attribut am Element <ValidateManifest> — eine öffentliche setzbare Eigenschaft desselben Namens und weist ihr den (typkonvertierten) Wert zu. Es führt Execute() aus. Danach liest es für jedes <Output> eine öffentliche lesbare Eigenschaft anhand des Namens in TaskParameter. Drei verschiedene Stellen dieser Sequenz verbrauchen Namen als Daten: den Typnamen, die Namen der Eingabe-Eigenschaften und die Namen der Ausgabe-Eigenschaften. Keine davon überlebt einen Umbenenner, der nicht weiß, dass sie tragend sind.
Was festgenagelt ist und warum
Der Typname der Task ist eine Zeichenfolge in UsingTask
TaskName="Acme.Build.ValidateManifest" ist ein Zeichenfolgenliteral, und MSBuild löst es mit GetType auf. Wenn Nebula die Klasse in Acme.Build.a umbenennt, gibt der GetType-Aufruf null zurück und der Build schlägt fehl mit “The ‘ValidateManifest’ task was not found.” Hier gibt es eine verlockende, aber falsche Lösung: Da du die .targets-Datei zusammen mit der DLL in deinem eigenen Paket auslieferst, könntest du beide im Gleichschritt umbenennen und konsistent halten. Widersteh dem. Konsumenten schreiben <UsingTask> auch von Hand, Blogbeiträge zitieren den Namen deiner Task und deine eigene Dokumentation schreibt ihn fest. Der öffentliche Typname der Task ist API. Nagle ihn fest — und nagle den Namespace gleich mit.
Die öffentlichen Eigenschaftsnamen sind der Parametervertrag
ManifestPath, MaxEntries und Fingerprint sind keine gewöhnlichen Eigenschaften — sie sind die Parameter der Task, und MSBuild bindet sie über den Namen an XML-Attribute, die in Konsumenten-Projektdateien geschrieben wurden, die du nie zu Gesicht bekommst. Das ist dieselbe Situation wie bei System.Text.Json, das über Eigenschaftsnamen bindet, oder bei Dapper, das Spalten zuordnet: Die öffentlichen Eigenschaftsnamen sind ein Wire-Vertrag, kein Implementierungsdetail. Benenne ManifestPath um, und das Attribut ManifestPath="..." im Build bindet lautlos an nichts; deine [Required]-Prüfung wirft ein verwirrendes “required parameter not set”, obwohl der Autor ihn eindeutig gesetzt hat. Behalte jede öffentliche setz-/lesbare Eigenschaft, die als Task-Parameter auftaucht. Beachte die Asymmetrie zum Klassenkörper: Die Namen sind festgenagelt, aber die Methodenkörper und jeder private Member nicht.
Die ITask-Oberfläche
Execute ist die Implementierung der Schnittstelle ITask.Execute (du bekommst sie über die Basisklasse Task), daher bewahrt die Umbenennung ihren v-Table-Slot automatisch — MSBuild ruft sie über die Schnittstelle auf, nicht per Zeichenfolge. Die Eigenschaften BuildEngine und HostObject sind Schnittstellen-Member, die die Engine setzt; sie werden aus demselben Grund bewahrt. Die einzigen Regeln sind die gewohnten: Entferne nicht die Schnittstellenimplementierung, ändere nicht die Signatur und halte den öffentlichen parameterlosen Konstruktor öffentlich (die Engine ruft Activator.CreateInstance auf).
Ein leicht zu übersehender Punkt: Der Diagnosecode "ACMEB001" ist ein öffentlicher Vertrag. Teams suchen ihn mit grep, unterdrücken ihn in der CI und leiten ihn in Log-Parsern weiter. Die Verschlüsselung von Zeichenfolgen ist in Ordnung — der Wert wird rekonstruiert, bevor LogError ihn ausgibt — aber der Wert der Zeichenfolge darf nicht verändert werden.
Was sich problemlos umbenennen lässt
Alles, was zählt. ManifestInspector.Analyze, die Modelltypen, die es zurückgibt, jede private Hilfsmethode, das Parsen, das Fingerprinting, die Regel-Engine — nichts davon wird in irgendeiner Build-Datei benannt, also wird alles umbenannt, und genau das ist die Logik, die es wert ist, geschützt zu werden. Eine Task ist meist eine dünne, reflexionsfreundliche Hülle um einen echten Arbeitskörper; die Hülle ist festgenagelt und die Arbeit ist frei. Wie bei einem Generator obfuskiert sich die überwältigende Mehrheit des Assemblys wie jede andere Bibliothek. Du nagelst eine Tür fest, nicht ein Haus.
Die Feinheit: dir gehören die .targets, den Konsumenten gehören die Attribute
Es hilft, die beiden Textquellen zu trennen. Die UsingTask-Typnamen-Zeichenfolge lebt in der Regel in deinen gepackten build/*.targets, steht also im Prinzip unter deiner Kontrolle. Die Attribute mit Eigenschaftsnamen (ManifestPath="...") leben im Projekt des Konsumenten und in deiner öffentlichen Dokumentation — völlig außerhalb deiner Kontrolle. Das bedeutet: Selbst wenn du bereit wärst, die eine Zeichenfolge, die dir gehört, im Gleichschritt umzubenennen, könntest du die Eigenschaftsnamen trotzdem nicht antasten, und die machen ohnehin den Großteil der festgenagelten Oberfläche aus. Das ehrliche Modell lautet: Behandle die gesamte extern benannte Task-Oberfläche als öffentliche API, nagle sie in der Konfiguration fest und überlass den Körper dem Umbenenner.
Die Nebula-Konfiguration
In Nebula-Begriffen ist das ein Bibliotheksprofil, das die extern benannte Oberfläche der Task festnagelt und alles andere ziehen lässt:
{
"rename": {
"enabled": true,
"autoDetect": true,
"keep": [
{
"type": "Acme.Build.ValidateManifest",
"members": "public",
"reason": "MSBuild GetType()s this exact name from UsingTask and binds task parameters to its public property names"
}
]
},
"strings": { "encrypt": true },
"preserve": [
{ "interfaceImpl": "Microsoft.Build.Framework.ITask" }
],
"controlFlow": { "enabled": true, "exclude": [ "*ValidateManifest.Execute*" ] }
}
Die gesamte öffentliche Oberfläche des Task-Typs zu behalten — statt jede Eigenschaft einzeln aufzuzählen — ist bewusst gewählt: Es ist robust dagegen, dass jemand später einen Parameter hinzufügt und vergisst, die keep-Liste zu aktualisieren, was die klassische Ursache für einen Parameter ist, der nach einem Refactoring lautlos aufhört zu binden. autoDetect schützt bereits die ITask-Implementierung; der explizite preserve-Eintrag ist Hosenträger und Gürtel. Execute vom Control-Flow-Flattening auszuschließen, ist eine kleine Performance-Entscheidung (die Task kann bei jedem inkrementellen Build laufen) und kostet keinen Schutz, denn Execute ist ein dünner Dispatcher — die eigentliche Arbeit steckt in ManifestInspector, das vollständig transformiert bleibt.
Führe es als Teil deiner Pack-Pipeline aus:
nebula protect --config nebula.json --in bin/Release/Acme.Build.dll --out dist/Acme.Build.dll
Verifiziere mit einem echten Build, nicht mit einem Laden
Der Fehlermodus ist hier lautlos, also beweist eine Verifizierung durch das Laden der DLL nichts. Du musst MSBuild gegen das obfuskierte Assembly ausführen und das Verhalten per Assertion prüfen:
# point a throwaway project's UsingTask at dist/Acme.Build.dll
dotnet build tests/TaskHarness/TaskHarness.csproj -t:CheckManifest -v:normal
Drei Dinge müssen gelten: Die Task wird aufgelöst (kein “task was not found”), die Eingaben binden (ein absichtlich fehlerhaftes Manifest erzeugt ACMEB001 und beweist, dass ManifestPath und MaxEntries angekommen sind) und das [Output] fließt zurück ($(ManifestHash) ist nachgelagert nicht leer). Wenn ein Parameter ungebunden blieb, siehst du einen Lauf mit Standardwerten statt eines Absturzes — genau deshalb prüft das Harness die erzeugten Werte per Assertion und nicht nur den Exit-Code.
Das Fazit
Eine benutzerdefinierte MSBuild-Task ist das Spiegelbild des Generators: Der Compiler findet einen Generator über ein Attribut und lässt dich alles umbenennen, während MSBuild eine Task über eine literale Typnamen-Zeichenfolge findet und ihre Parameter über öffentliche Eigenschaftsnamen bindet, was beides zu einem harten externen Vertrag macht. Nagle die öffentliche Oberfläche des Task-Typs fest — den Typnamen und jede Eigenschaft, die als Task-Parameter auftaucht — behalte den ITask/Execute-Slot und den öffentlichen Konstruktor und lass die Werte der Diagnosecode-Zeichenfolgen unangetastet. Lass dann Nebula den gesamten Körper umbenennen und transformieren, denn dort lebt deine eigentliche Tooling-Logik. Verifiziere, indem du ein echtes Target gegen die obfuskierte DLL ausführst und die gebundenen Ein- und Ausgaben per Assertion prüfst, denn die einzige Art, wie das kaputtgeht, ist lautlos.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.