Warum protobuf-net das Umbenennen überlebt
protobuf-net serialisiert anhand der numerischen Tags in [ProtoMember(N)], nicht anhand der Mitgliedsnamen — das Umbenennen eines protobuf-net-DTO ist daher auf der Leitung ungefährlich, anders als bei System.Text.Json oder DataContract, wo die Namen DER Vertrag sind. Hier erfahren Sie, warum das Umbenennen von Eigenschaften bei protobuf-net praktisch kostenlos ist, und welche vier Fälle dennoch brechen: implizite Feldnummerierung, Typnamen in ProtoInclude/AsReference, per Reflexion über Mitgliedsnamen aufgebaute Modelle und ProtoEnum-Namen.
Die meisten Ratschläge zum Obfuskieren serialisierter Typen sind eine Warnung: Benennen Sie Ihre DTOs nicht um, die Namen sind der Vertrag. Das stimmt für System.Text.Json, Newtonsoft.Json und DataContract/WCF — der Mitgliedsname (oder ein Attribut, das ihn wiederholt) ist buchstäblich der Schlüssel, der auf die Leitung geschrieben wird, sodass das Umbenennen von OrderId in a ändert, was die Gegenseite liest. protobuf-net ist die erfreuliche Ausnahme, und der Grund lohnt sich zu verstehen, weil er den üblichen Rat umkehrt: Bei protobuf-net-DTOs ist das Umbenennen von Eigenschaften und Feldern praktisch kostenlos, und Sie müssen nur über eine kurze Liste von Ausnahmen nachdenken.
Die Leitung transportiert Zahlen, keine Namen
protobuf-net implementiert das Leitungsformat von Googles Protocol Buffers. Jedes Feld auf der Leitung ist ein Schlüssel/Wert-Paar, und der Schlüssel ist ein Varint, der aus einer Feldnummer und einem Leitungstyp aufgebaut ist — keine Zeichenkette. Die Feldnummer stammt aus dem N, das Sie in [ProtoMember(N)] geschrieben haben:
[ProtoContract]
public sealed class OrderLine
{
[ProtoMember(1)] public int OrderId { get; set; }
[ProtoMember(2)] public string Sku { get; set; } = "";
[ProtoMember(3)] public decimal UnitPrice { get; set; }
}
Bei der Serialisierung sagen die Bytes „Feld 1, Varint”, dann „Feld 2, längenbegrenzt” und so weiter. Die Zeichenkette "OrderId" taucht nirgendwo in der Ausgabe auf. Das ist der ganze Trick: Der Name ist ein Label zur Kompilierzeit, und die Tag-Nummer ist der Vertrag zur Laufzeit.
Warum das das Umbenennen sicher macht
Da der Name die Leitung nie erreicht, darf ein Obfuskator ihn frei umschreiben. Nachdem Nebula den Typ umbenannt hat, sieht ein Dekompiler etwa Folgendes:
[ProtoContract]
public sealed class b
{
[ProtoMember(1)] public int a { get; set; }
[ProtoMember(2)] public string c { get; set; } = "";
[ProtoMember(3)] public decimal d { get; set; }
}
Die [ProtoMember(N)]-Nummern bleiben unangetastet — sie sind Daten im Attribut-Blob, keine Bezeichner —, sodass die serialisierten Bytes Byte für Byte identisch mit denen des nicht obfuskierten Builds sind. Ein alter Client, der noch das ursprüngliche OrderLine besitzt, liest die Ausgabe des umbenannten Servers einwandfrei und umgekehrt, weil sich beide Seiten einig sind, dass Feld 3 der Stückpreis ist. Der lesbare Name existierte nur für Ihren Quellbaum, und die Obfuskation ist genau die Transformation, die diesen Quellbaum verwirft.
Das ist ein echter Vorteil gegenüber den namensbasierten Serialisierern. Mit System.Text.Json ändert das Umbenennen von UnitPrice in d entweder den JSON-Schlüssel in "d" (und bricht alle Konsumenten) oder zwingt Sie, jede Eigenschaft mit [JsonPropertyName("UnitPrice")] festzunageln — womit Sie genau die Zeichenkette wieder eingeführt haben, die Sie verbergen wollten. protobuf-net braucht nichts davon. Verwenden Sie explizite Nummerierung mit [ProtoMember(N)], und das Umbenennen ist kostenlos.
Die vier Dinge, die dennoch brechen
Die obige Freiheit gilt gerade deshalb, weil das Tag explizit ist und der Name fehlt. Jede folgende Ausnahme ist ein Fall, in dem das nicht mehr zutrifft — entweder hängt das Tag vom Namen ab, oder der Name schleicht sich auf die Leitung oder in eine Reflexions-Suche ein.
1. Implizite Feldnummerierung
protobuf-net kann die Tags für Sie vergeben:
[ProtoContract(ImplicitFields = ImplicitFields.AllPublic)]
public sealed class Customer // GEFAHR beim Umbenennen
{
public int Id { get; set; } // implizit Tag 1
public string Name { get; set; } // implizit Tag 2
public string Region { get; set; } // implizit Tag 3
}
Mit ImplicitFields.AllPublic (oder AllFields) gibt es keine expliziten Nummern. protobuf-net leitet die Tags ab, indem es die Mitglieder aufzählt, sie alphabetisch nach Namen sortiert und dann ab 1 nummeriert. Benennen Sie Name in a und Region in b um, so ändert sich die alphabetische Reihenfolge, sodass die Tags, die einmal Id=1, Name=2, Region=3 waren, stillschweigend zu etwas anderem werden — jedes Feld verschiebt sich, und das Leitungsformat bricht gegenüber allen zuvor serialisierten Daten. Das händische Umsortieren der Mitglieder bewirkt dasselbe.
Die Abhilfe besteht darin, sich für nichts, was Sie obfuskieren, auf die implizite Nummerierung zu verlassen. Wandeln Sie den Typ entweder in explizites [ProtoMember(N)] um (die empfohlene Vorgehensweise — sie ist sowohl umbenennungs- als auch versionssicher) oder setzen Sie den Typ auf die Keep-List, damit seine Mitglieder ihre Namen behalten.
2. ProtoInclude, AsReference und dynamische Typbehandlung
Vererbung und Referenzverfolgung können einen Typnamen ins Spiel bringen:
[ProtoContract]
[ProtoInclude(10, typeof(ExpressShipment))]
public abstract class Shipment { [ProtoMember(1)] public string Tracking { get; set; } = ""; }
Die Form [ProtoInclude(10, typeof(ExpressShipment))] ist tag-basiert (Feld 10) und daher umbenennungssicher — der Subtyp wird über die Nummer 10 identifiziert, nicht über "ExpressShipment". Doch zwei verwandte Funktionen sind standardmäßig nicht sicher: die Graphen-Serialisierung mit AsReference und DynamicType können den assembly-qualifizierten CLR-Typnamen einbetten, damit der Leser den exakten Typ wiederherstellen kann. Wenn Sie den Typ umbenennen, passt diese eingebettete Zeichenkette nicht mehr. Bevorzugen Sie das tag-basierte [ProtoInclude(N, typeof(T))] gegenüber DynamicType, und falls Sie AsReference über Prozessgrenzen hinweg serialisieren müssen, setzen Sie die betroffenen Typen auf die Keep-List.
3. Ein zur Laufzeit per Mitgliedsname aufgebautes Modell
Wenn Sie protobuf-net imperativ statt mit Attributen konfigurieren, benennen Sie Mitglieder möglicherweise als Zeichenketten:
RuntimeTypeModel.Default
.Add(typeof(Customer), applyDefaultBehaviour: false)
.Add(1, "Id")
.Add(2, "Name") // Suche per Zeichenkette — bricht nach Umbenennen
.Add(3, "Region");
.Add(2, "Name") löst "Name" beim Start per Reflexion auf. Nachdem Nebula die Eigenschaft in a umbenannt hat, passt die Zeichenkette "Name" zu keinem Mitglied mehr, und das Modell wird nicht aufgebaut (oder überspringt das Feld stillschweigend). Dies ist der einzige Fall, der wirklich mit dem Umbenennen unverträglich ist, daher gehören diese Typen auf die Keep-List — oder, besser, migrieren Sie die Registrierung zur stark typisierten Überladung .Add(2, nameof(Customer.Name)) und setzen Sie sie dann auf die Keep-List, da nameof weiterhin eine zur Kompilierzeit erzeugte, ins IL eingebackene Zeichenkette ist.
4. ProtoEnum-Namen
Enum-Werte werden anhand ihres numerischen Werts serialisiert, sodass das Umbenennen von Enum-Mitgliedern normalerweise unbedenklich ist. Die Ausnahme ist ein expliziter Namens-Roundtrip:
[ProtoContract]
public enum Priority
{
[ProtoEnum(Name = "LOW")] Low = 0,
[ProtoEnum(Name = "HIGH")] High = 2,
}
[ProtoEnum(Name = "...")] ist ein Zeichenkettenliteral im Attribut, daher ist es vom Umbenennen des Enum-Mitglieds nicht betroffen — aber es bleibt eine lesbare Zeichenkette in Ihren Metadaten, und wenn irgendein Werkzeug auf diesen Namen abgleicht, sollten Sie ihn in Ruhe lassen. Einfache Enums ohne [ProtoEnum(Name=)] brauchen überhaupt keine Sonderbehandlung.
Die Keep-List: eng angelegt per Design
Setzen Sie alles auf das vollständige Umbenennen und nehmen Sie dann nur die konkreten Typen aus, die unter die obigen Fälle 1–3 fallen. Eine realistische nebula.config.json:
{
"input": "bin/Release/net8.0/Acme.Orders.dll",
"output": "dist/Acme.Orders.dll",
"rename": { "enabled": true, "scope": "all" },
"strings": { "encrypt": true },
"controlFlow": { "flatten": "sensitive" },
"keep": [
{
"type": "Acme.Orders.Dtos.Customer",
"members": "names",
"reason": "ImplicitFields.AllPublic — tags derive from member names/order"
},
{
"type": "Acme.Orders.Model.*",
"members": "names",
"reason": "RuntimeTypeModel built with .Add(n, \"MemberName\") by string"
}
]
}
"members": "names" bewahrt die Mitgliedsnamen für diese Typen, lässt Nebula aber weiterhin String-Verschlüsselung und Kontrollfluss-Transformationen auf ihre Methodenrümpfe anwenden — Sie schützen nur die Namen, die der Serialisierer benötigt, ohne den Typ als Ganzes auszunehmen. Schützen Sie anschließend die Assembly:
nebula protect --config nebula.config.json
Alles außerhalb der Keep-List — was bei einem gut nummerierten protobuf-net-Projekt im Wesentlichen die gesamte DTO-Schicht ist — wird ohne Risiko für das Leitungsformat frei umbenannt.
Die Faustregel
protobuf-net kehrt das übliche Spannungsverhältnis zwischen Serialisierung und Obfuskation um. Da der Vertrag das numerische Tag und nicht der Mitgliedsname ist, sind DTOs mit explizitem [ProtoMember(N)] per Konstruktion umbenennungssicher. Konzentrieren Sie Ihren Aufwand an einer einzigen Stelle: Finden Sie die Typen, die den Namen wieder in den Vertrag zurücksickern lassen — implizite Nummerierung, AsReference/DynamicType und Laufzeitmodelle mit Namen als Zeichenkette —, wandeln Sie um, was Sie können, in explizite Tags, setzen Sie den Rest auf die Keep-List und lassen Sie Nebula die gesamte DTO-Schicht ohne zweiten Gedanken umbenennen.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.