Eine lokalisierte .NET-Anwendung obfuskieren, ohne die Ressourcen zu zerstören
Eine lokalisierte Anwendung löst ihre Übersetzungen zur Laufzeit per Name auf, und genau diese Art der Suche kann die Obfuskation stillschweigend zerstören. Die Überraschung: Die beiden gängigen Lokalisierungsstile verhalten sich beim Umbenennen gegensätzlich. Ein klassischer, vom Designer erzeugter .resx-Accessor ist sicher, weil der Basisname seines ResourceManager ein bereits eingebettetes String-Literal ist, während IStringLocalizer<T> fragil ist, weil die Factory den Basisname aus dem vollständigen Namen des Markertyps ableitet: Benennt man diesen Typ um, schlägt die Suche fehl, das Satellitenassembly wird nie konsultiert, und der Localizer gibt stillschweigend den Ressourcenschlüssel statt der Übersetzung zurück. Dieser Artikel liest, was jeder Stil ausgibt, zeigt, warum der eine überlebt und der andere nicht, und gibt die präzisen Nebula.NET-Beibehaltungsregeln, damit Ihre Übersetzungen in jeder Kultur weiter geladen werden.
Lokalisierung ist ein namensbasiertes Subsystem, und „per Name” ist genau der Ausdruck, der jeden dazu bringen sollte, einen Obfuskator mit Vorsicht anzufassen. Jede übersetzte Zeichenfolge, die Ihre Anwendung anzeigt, wurde zur Laufzeit aufgelöst, indem ein Schlüssel mit einem Ressourcensatz abgeglichen wurde, und Ressourcensätze werden per Name gefunden: ein Basisname, den die Laufzeit in einen eingebetteten .resources-Stream verwandelt und, für nicht standardmäßige Kulturen, in ein Satellitenassembly, das sie auf der Festplatte sondiert. Obfuskation benennt Dinge um. Die Frage ist, ob einer der umbenannten Namen einer ist, den die Lokalisierungspipeline nachschlägt.
Die Antwort ist tatsächlich geteilt. Der alte, langweilige .resx-Accessor des Designers ist aus einem Grund sicher, den es sich zu verstehen lohnt. Das moderne IStringLocalizer<T> ist aus einem Grund fragil, den es sich noch besser zu verstehen lohnt, denn es scheitert stillschweigend: keine Ausnahme, kein Log, nur Ihre englischen Schlüssel, die in einem französischen Build durchscheinen. Hier ist, was jeder ausgibt, warum sie auseinanderlaufen, und die genauen Beibehaltungsregeln, die beide mit Nebula.NET sicher machen.
Woher der Ressourcenname wirklich kommt
Beginnen Sie mit dem klassischen Pfad – eine Strings.resx mit ihrer erzeugten Strings.Designer.cs. Entscheidend ist, wie der Accessor seinen ResourceManager aufbaut:
internal static global::System.Resources.ResourceManager ResourceManager {
get {
if (object.ReferenceEquals(resourceMan, null)) {
var temp = new global::System.Resources.ResourceManager(
"MyApp.Resources.Strings", // base name — a string literal
typeof(Strings).Assembly); // assembly — a token reference
resourceMan = temp;
}
return resourceMan;
}
}
Der Basisname ist ein Literal. Der Designer bettet "MyApp.Resources.Strings" als ldstr in den IL-Code ein, und an dieses Literal hängt ResourceManager die Kultur an: MyApp.Resources.Strings.fr.resources für Französisch, zu finden im eingebetteten Manifest für die neutrale Kultur und in fr/MyApp.resources.dll für den Satelliten. Benennen Sie den Typ Strings in a um, und das Literal bewegt sich nicht; es sagt weiterhin "MyApp.Resources.Strings". Das typeof(Strings) wird wie jede Typreferenz per Token umgeschrieben, zeigt also weiterhin auf den umbenannten Typ und liefert weiterhin das richtige Assembly. Beide Hälften überleben. Selbst die String-Verschlüsselung lässt dies funktionieren, denn das Literal wird vor dem Erreichen des Konstruktors entschlüsselt – ResourceManager erhält den Basisnamen im Klartext genau so, wie er geschrieben wurde.
Nun der moderne Pfad. IStringLocalizer<HomeController> wird über ResourceManagerStringLocalizerFactory aufgelöst, und die Factory erhält kein Literal. Sie berechnet den Basisnamen aus dem Markertyp:
// Program.cs
builder.Services.AddLocalization(o => o.ResourcesPath = "Resources");
// HomeController.cs
public HomeController(IStringLocalizer<HomeController> loc) => _loc = loc;
// ...
ViewData["Title"] = _loc["PageTitle"];
Dahinter liest die Factory typeof(HomeController).FullName, entfernt den Stammnamespace des Assemblys und fügt ResourcesPath ein, um einen Basisnamen wie MyApp.Resources.Controllers.HomeController zu erzeugen. Dieser Basisname ist der Suchschlüssel – das, wonach ein .resources-Stream benannt sein muss. Er wird zur Laufzeit aus dem Typbezeichner abgeleitet, also genau aus dem Bezeichner, den die Obfuskation umschreibt.
Der Fehler ist still, und das ist die eigentliche Gefahr
Würde IStringLocalizer eine Ausnahme werfen, wenn es keinen Ressourcensatz findet, wäre dies ein lauter Fehler, den Sie im ersten Rauchtest beheben würden. Er wirft keine Ausnahme. Der Vertrag von IStringLocalizer besagt, dass eine fehlende Ressource ein behebbarer Zustand ist: Er gibt ein LocalizedString zurück, dessen ResourceNotFound-Flag true ist und dessen Value der von Ihnen übergebene Schlüssel ist:
var s = _loc["PageTitle"];
// After a renamed marker type:
// s.ResourceNotFound == true
// s.Value == "PageTitle" // the key, shown verbatim in the UI
So sieht ein französischer Nutzer PageTitle, wo der Titel stehen sollte, jeder von Ihnen ausgelieferte Satellit liegt weiterhin auf der Festplatte und ist völlig gültig, und nichts in den Logs weist darauf hin. Der Build in neutraler Kultur sieht oft ebenfalls in Ordnung aus, weil viele Teams den englischen Text in den Schlüssel oder in einen neutralen Fallback legen – die Regression zeigt sich also nur in genau den Kulturen, auf die ein Prüfer am wenigsten wahrscheinlich klickt. Das ist das stärkste Argument dafür, Lokalisierung als eigenständiges Schutzziel mit eigenen Beibehaltungsregeln zu behandeln, statt zu hoffen, dass die automatische Erkennung sie abdeckt.
Die Beibehaltungsregeln
Nebula erkennt die gängige Nutzung von ResourceManager automatisch, sodass der klassische .resx-Accessor in der Regel für Sie abgedeckt ist – und selbst ein umbenannter Accessor-Typ ist in Ordnung, weil sein Basisname, wie oben gezeigt, ein Literal ist. Der Pfad, der eine ausdrückliche Entscheidung erfordert, ist IStringLocalizer<T>: Die Markertypen müssen ihre vollständigen Namen behalten, weil die Factory FullName in den Suchschlüssel verwandelt.
Fixieren Sie genau diese Markertypen und nichts weiter. Platzieren Sie in nebula.config.json die engen keep-Regeln über dem breiten rename-Auffangmuster – die erste Übereinstimmung gewinnt:
{
"schemaVersion": 1,
"inputs": [ "bin/Release/net8.0/MyApp.dll" ],
"outputDirectory": "protected",
"preservePublicApi": true,
"encryptStrings": true,
"controlFlowObfuscation": true,
"renaming": {
"rules": [
{ "pattern": "MyApp.Controllers.*", "action": "keep" },
{ "pattern": "MyApp.Resources.*", "action": "keep" },
{ "pattern": "MyApp.*", "action": "rename" }
]
}
}
Zwei Dinge sind zu beachten. Erstens fixiert keep den Namen, nicht den Rumpf: Ein beibehaltener Controller hat weiterhin umbenannte private Felder, durch Kontrollfluss abgeflachte Methodenrümpfe und verschlüsselte Zeichenfolgen – Sie haben auf das Umbenennen eines Typbezeichners verzichtet, nicht auf den Schutz seines Codes. Zweitens: Behalten Sie das Blatt, nicht den Ast. Werden nur eine Handvoll Typen als IStringLocalizer<T>-Marker verwendet, fixieren Sie diese Typen statt eines ganzen Namespace. Für eine chirurgische, codenahe Alternative markieren Sie den genauen Markertyp mit einem Attribut, das direkt daneben lebt:
[Obfuscation(Feature = "renaming", Exclude = true)] // used as IStringLocalizer<T> marker
public class HomeController : Controller { /* ... */ }
Eine subtilere Beibehaltung gilt, wenn Sie Datenannotationen über Ressourcentypen lokalisieren: [Display(Name = "Field_Email", ResourceType = typeof(Strings))]. Das typeof(Strings) ist eine sichere Token-Referenz, aber Name = "Field_Email" wird aufgelöst, indem per Reflexion nach einer statischen Eigenschaft dieses Namens auf dem Ressourcentyp gesucht wird. Das macht die Member des erzeugten Accessors tragend: Behalten Sie die öffentlichen Member jedes Ressourcen-Accessor-Typs, den Sie aus einem ResourceType referenzieren, nicht nur den Typnamen. IViewLocalizer braucht nichts: Es leitet seinen Basisnamen aus dem View-Pfad ab, den kein Umbenennen berührt.
Satellitenassemblys erfordern keinerlei Arbeit. Ein Satellit ist ein reines Ressourcenassembly – .resources-Ströme pro Kultur und kein IL-Code von Ihnen –, also gibt es darin nichts umzubenennen oder abzuflachen. Lassen Sie fr/MyApp.resources.dll und Konsorten aus Ihren Nebula-Eingaben heraus und liefern Sie sie so aus, wie sie kompiliert wurden. Sie werden weiterhin aufgelöst, weil Nebula den Namen des Hauptassemblys beibehält (sodass die Laufzeit den richtigen Kultur-Unterordner sondiert) und weil auf dem klassischen Pfad der vom Hauptassembly angeforderte Basisname sich nicht ändert.
Prüfen Sie in der Kultur, nicht nur auf Englisch
Lokalisierungsbrüche verbergen sich vor einem Lauf in der Standardkultur, also muss der Abnahmetest die Kultur wechseln und auf einen übersetzten Wert prüfen, nicht nur darauf, dass eine Zeichenfolge zurückkam:
[Theory]
[InlineData("fr")]
[InlineData("de")]
public void Localizer_returns_translation_not_key(string culture)
{
CultureInfo.CurrentUICulture = new CultureInfo(culture);
var s = _loc["PageTitle"];
Assert.False(s.ResourceNotFound); // the real assertion
Assert.NotEqual("PageTitle", s.Value); // guards against the silent key fallback
}
Führen Sie diese Suite gegen den geschützten Build aus, nicht gegen den Debug-Build – der ganze Sinn besteht darin, das umbenannte Assembly auszuüben. Ergänzen Sie sie durch eine statische Prüfung in Glass.NET, dem kostenlosen, rein statischen Begleiter: Öffnen Sie die geschützte MyApp.dll, bestätigen Sie, dass sich Ihr interner Motor als a, b, c liest, und bestätigen Sie, dass Ihre IStringLocalizer<T>-Markertypen ihre vollständigen Namen und Namespaces behalten haben, damit die Factory den Basisnamen ableitet, gegen den die Satelliten gebaut wurden. Für die allgemeine Disziplin hinter minimalen Beibehaltungslisten siehe Beibehaltungslisten und Umbenennungsausschlüsse; für den breiteren Katalog namensbasierter Brüche was Obfuskation zerstört.
Fazit
Lokalisierung wird per Name aufgelöst, also ist die einzige Frage, die die Obfuskation aufwirft, welche der Namen die Suchschlüssel sind. Auf dem klassischen .resx-Pfad sind es überhaupt keine Bezeichner – der Basisname ist ein eingebettetes Literal –, sodass der Accessor-Typ frei umbenannt wird und selbst die String-Verschlüsselung ihn funktionsfähig lässt. Auf dem IStringLocalizer<T>-Pfad wird der Basisname zur Laufzeit aus dem vollständigen Namen des Markertyps abgeleitet, sodass das Umbenennen dieses Typs die Suche von jedem ausgelieferten .resources-Stream wegschiebt und der Localizer still den Schlüssel liefert. Behalten Sie die Handvoll Markertypen bei (und die öffentlichen Member jedes Ressourcentyps, den Sie über einen ResourceType einer Datenannotation erreichen), lassen Sie Satellitenassemblys aus den Eingaben und unberührt, schützen Sie alles andere vollständig, und beweisen Sie es mit einem Test, der die Kultur wechselt und auf die Übersetzung prüft – nicht darauf, ob eine Zeichenfolge zurückkam.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.