DEV Community: Zero Heartbeat

Decompiling C# expression trees: the lambda that became a tree of factory calls

Zero Heartbeat — Thu, 22 Oct 2026 04:38:00 +0000

A lambda is one of the few constructs in C# whose compilation depends on something outside the lambda. Write x => x + 1 and assign it to a Func<int, int> and you get a hidden static method and a delegate; assign the identical text to an Expression<Func<int, int>> and you get something else entirely — a nested sequence of calls to the factory methods on System.Linq.Expressions.Expression that builds a runtime data structure describing the lambda, node by node. There is no expression-tree opcode and no dedicated metadata. The decompiled method is a page of Expression.Parameter, Expression.Constant, Expression.Add and Expression.Lambda calls, with every member the source named reached through ldtoken. Reading that lowering explains what a decompiler such as Glass.NET can fold back into the one-liner, why captured variables show up as a Constant of a closure object, and why the query provider on the other end of an IQueryable has to do real work to find your variable's value.

Same lambda, two compilations

Start with the fact that decides everything. The conversion of a lambda is chosen by its target type, not by its text:

Func<int, int>             f = x => x + 1;   // delegate: a method plus a delegate object
Expression<Func<int, int>> e = x => x + 1;   // expression tree: a data structure

The first line compiles the way lambdas and closures always do — the body becomes a method <M>b__0_0 on the compiler's <>c singleton class, and the assignment is an ldftn plus a newobj of Func<int, int>, cached in a static field. The body's IL is three instructions: ldarg.1, ldc.i4.1, add.

The second line produces no hidden method at all. The + is never emitted as an add instruction. Instead the compiler emits code that constructs a description of the addition:

ParameterExpression x = Expression.Parameter(typeof(int), "x");
Expression<Func<int, int>> e = Expression.Lambda<Func<int, int>>(
    Expression.Add(x, Expression.Constant(1, typeof(int))),
    new ParameterExpression[] { x });

That is the whole lowering, and it is already what a decompiler without expression-tree recognition will show you. Three things to notice: the parameter name "x" is kept as a string literal, the literal 1 is boxed into an object because Expression.Constant takes (object, Type), and the parameter node is created once, stored in a local, and used twice — once in the body and once in the parameter array. In IL it is a chain of call instructions against the static factory methods, with typeof(int) spelled as ldtoken plus Type.GetTypeFromHandle:

ldtoken    System.Int32
call       Type Type::GetTypeFromHandle(RuntimeTypeHandle)
ldstr      "x"
call       ParameterExpression Expression::Parameter(Type, string)
stloc.0
ldloc.0                                   // left operand: the parameter node
ldc.i4.1
box        System.Int32                   // Constant takes object
ldtoken    System.Int32
call       Type Type::GetTypeFromHandle(RuntimeTypeHandle)
call       ConstantExpression Expression::Constant(object, Type)
call       BinaryExpression Expression::Add(Expression, Expression)
ldc.i4.1
newarr     ParameterExpression
dup
ldc.i4.0
ldloc.0
stelem.ref
call       Expression`1<!!0> Expression::Lambda<Func`2<int32,int32>>(Expression, ParameterExpression[])

(The assembly qualifiers are elided here for readability; the real IL spells out [System.Linq.Expressions]System.Linq.Expressions.Expression every time, which is a large part of why the raw view of an expression-tree method is so long.)

Every expression tree you will ever decompile has this skeleton: a Parameter call per lambda parameter stored in a local, a body built bottom-up from factory calls that consume the stack, and a closing Lambda<TDelegate> that takes the body and an explicit ParameterExpression[]. The generic type argument of that final call is the delegate type — it is the one place the original Expression<Func<int, int>> signature is visible in the body.

Members are reached by token, not by name

As soon as the lambda touches a property, field or method, the lowering has to say which member, and it does so the only way the runtime can guarantee is exact: a metadata token. Take a filter over a type with a property:

Expression<Func<Customer, bool>> adults = c => c.Age >= 18;

The property access becomes Expression.Property, and the PropertyInfo it needs is obtained from the getter's method token:

ParameterExpression c = Expression.Parameter(typeof(Customer), "c");
Expression<Func<Customer, bool>> adults = Expression.Lambda<Func<Customer, bool>>(
    Expression.GreaterThanOrEqual(
        Expression.Property(c, (MethodInfo)MethodBase.GetMethodFromHandle(/* ldtoken Customer::get_Age */)),
        Expression.Constant(18, typeof(int))),
    new ParameterExpression[] { c });

In IL the member reference is ldtoken method instance int32 Customer::get_Age() followed by call MethodBase::GetMethodFromHandle(RuntimeMethodHandle) and a castclass MethodInfo. Fields go through ldtoken field plus FieldInfo.GetFieldFromHandle and Expression.Field. Methods go through the same token-plus-handle pair into Expression.Call. When the member lives on a generic type, the compiler uses the two-argument GetMethodFromHandle(RuntimeMethodHandle, RuntimeTypeHandle) overload and also passes the declaring type's token, because a method handle alone does not identify which instantiation it belongs to.

This is the detail that makes expression trees robust and decompilation easy at the same time. The tree does not contain the string "Age"; it contains a token that resolves to exactly the get_Age the source bound to, overload and all. A decompiler reads the token straight back out of the ldtoken operand and prints c.Age. The same tokens are what a renaming obfuscator rewrites consistently, which is why expression trees survive renaming while reflection-by-string does not.

Operators that C# defines on a type rather than on a primitive carry their operator method along. A string comparison is the common case:

Expression<Func<Customer, bool>> named = c => c.Name == "Ada";

does not lower to the two-argument Expression.Equal. It lowers to the four-argument overload with the user-defined operator attached:

Expression.Equal(
    Expression.Property(c, /* get_Name */),
    Expression.Constant("Ada", typeof(string)),
    false,                                                   // liftToNull
    (MethodInfo)MethodBase.GetMethodFromHandle(/* ldtoken string::op_Equality */))

The MethodInfo is String.op_Equality(string, string) — the compiler recorded which == it resolved, so a query provider can tell string equality from reference equality. && and || become AndAlso and OrElse; the non-short-circuit & and | become And and Or; ?: becomes Expression.Condition and ?? becomes Expression.Coalesce. Each maps back to exactly one piece of C# syntax, and a decompiler that knows the table rebuilds the body one node at a time.

Captured variables: a Constant that is not constant

The lowering gets genuinely interesting when the lambda uses a variable from the enclosing method:

static Expression<Func<Customer, bool>> OlderThan(int min) => c => c.Age > min;

For a delegate, min would be hoisted into a display class and the lambda body would read it as a field — the familiar closure pattern. An expression tree needs the same thing, but it has to express "read field min from this particular closure object" as a tree node. The compiler does it with a Constant whose value is the closure instance, and a Field access on top of it:

<>c__DisplayClass0_0 closure = new <>c__DisplayClass0_0();
closure.min = min;
ParameterExpression c = Expression.Parameter(typeof(Customer), "c");
return Expression.Lambda<Func<Customer, bool>>(
    Expression.GreaterThan(
        Expression.Property(c, /* get_Age */),
        Expression.Field(
            Expression.Constant(closure, typeof(<>c__DisplayClass0_0)),
            FieldInfo.GetFieldFromHandle(/* ldtoken <>c__DisplayClass0_0::min */))),
    new ParameterExpression[] { c });

Two consequences follow from this shape, and both are visible only in the lowered form. First, the tree does not contain the value of min; it contains a reference to the closure object and a field to read from it. The value is fetched when the tree is compiled or walked, so a tree built from a mutable local sees later mutations exactly as a delegate would. Second, this is precisely why every LINQ query provider has a step that evaluates Field-on-Constant subtrees before translating a query: from the provider's point of view, min is not a literal in the tree, it is a member access on an opaque object, and the provider has to execute that sub-expression to discover 18 and turn it into a query parameter. If you have ever wondered why a captured variable becomes @p0 in generated SQL while an inline literal becomes a literal, this is the shape behind it.

For a decompiler the pattern is a fingerprint. Expression.Field(Expression.Constant(x, typeof(T)), f) where T is a compiler-generated display class and x is a local of that type collapses to the captured variable's name — the display-class field keeps the original name min, so the recovered lambda reads c => c.Age > min even without a PDB. The surrounding new <>c__DisplayClass0_0() and closure.min = min are the same closure setup a delegate would need, and are folded away with it.

Conversions, checked arithmetic and boxing

C# inserts implicit conversions silently; expression trees cannot, because every node has an exact type and the factory methods validate it. So a lambda that mixes types grows Convert nodes the source never spelled out:

Expression<Func<int, double>> half = x => x / 2.0;

becomes

Expression.Divide(
    Expression.Convert(x, typeof(double)),      // the implicit int -> double promotion, made explicit
    Expression.Constant(2.0, typeof(double)))

The same happens for boxing — Expression<Func<int, object>> box = x => x; has a body of Expression.Convert(x, typeof(object)) — and for nullable lifting, where an int? compared to a literal gets its literal wrapped in Expression.Convert(Expression.Constant(3, typeof(int)), typeof(int?)) so both operands of the comparison have the same nullable type. A checked context changes the factory method rather than adding a node: checked(x + 1) lowers to Expression.AddChecked, and checked((byte)x) to Expression.ConvertChecked, so the overflow behaviour you asked for travels inside the tree as the choice of node type.

This is the first place a decompiler has to make a judgement call. An Expression.Convert(x, typeof(double)) could be a cast the author wrote, (double)x, or the promotion the compiler added. Both readings recompile to the same tree, so a decompiler can either print the cast — faithful but noisier — or drop conversions that C# would reinsert anyway and print x / 2.0. Glass.NET prefers the shorter form where it is provably equivalent and keeps the explicit Convert where it changes meaning, such as a narrowing cast or an object box that an overload resolution depends on.

Nested lambdas and Expression.Quote

Real expression trees are usually query fragments, and query fragments call methods that themselves take lambdas. What the inner lambda lowers to depends, again, on its target type. Consider a filter written over IQueryable:

Expression<Func<IQueryable<Customer>, IQueryable<Customer>>> active =
    q => q.Where(c => c.Active);

Queryable.Where takes an Expression<Func<Customer, bool>>, so the inner lambda must itself become a tree — and the outer tree needs to carry that inner tree as a value. The compiler lowers the inner lambda to its own Expression.Lambda and wraps it in Expression.Quote:

ParameterExpression q = Expression.Parameter(typeof(IQueryable<Customer>), "q");
ParameterExpression c = Expression.Parameter(typeof(Customer), "c");
Expression.Lambda<Func<IQueryable<Customer>, IQueryable<Customer>>>(
    Expression.Call(
        null,                                                             // static method
        (MethodInfo)MethodBase.GetMethodFromHandle(/* ldtoken Queryable::Where<Customer>(IQueryable<Customer>, Expression<Func<Customer,bool>>) */),
        new Expression[]
        {
            q,
            Expression.Quote(
                Expression.Lambda<Func<Customer, bool>>(
                    Expression.Property(c, /* get_Active */),
                    new ParameterExpression[] { c }))
        }),
    new ParameterExpression[] { q });

Notice the ldtoken for Where names the constructed generic method Where<Customer>, so the type argument the compiler inferred is recorded in the tree and the decompiler can leave it inferred in the output. Notice also that the static call passes null for the instance argument — Roslyn consistently uses the Call(Expression, MethodInfo, Expression[]) overload for both instance and static calls, which is a small but reliable fingerprint of compiler-generated trees versus hand-built ones.

Now change the source so the sequence is a List<Customer> instead. The call binds to Enumerable.Where, whose parameter is a plain Func<Customer, bool>, and the Quote disappears: the inner Expression.Lambda<Func<Customer, bool>>(...) node is passed directly as the argument. A LambdaExpression node is of delegate type, so no wrapping is needed. The presence or absence of Quote therefore tells you, without looking at the method signature, whether the callee receives the inner lambda as data to translate or as code to run — and a decompiler folds both forms to the same c => c.Active, because that is what the source said in both cases.

Object creation, initializers and anonymous types

Projections lower to a small family of node factories that a decompiler has to recognise as a group. A new with an object initializer becomes MemberInit over New, with one Bind per assigned member, each referencing the property's setter token:

Expression<Func<Customer, Dto>> toDto = c => new Dto { Name = c.Name, Age = c.Age };

Expression.MemberInit(
    Expression.New((ConstructorInfo)MethodBase.GetMethodFromHandle(/* ldtoken Dto::.ctor() */)),
    new MemberBinding[]
    {
        Expression.Bind((MethodInfo)MethodBase.GetMethodFromHandle(/* set_Name */), Expression.Property(c, /* get_Name */)),
        Expression.Bind((MethodInfo)MethodBase.GetMethodFromHandle(/* set_Age  */), Expression.Property(c, /* get_Age  */))
    })

Anonymous types take a different route, because they have no settable properties. c => new { c.Name, c.Age } lowers to the Expression.New overload that takes the constructor, the argument expressions and an array of the property getters as members. That member list is how a query provider pairs each constructor argument with the property it initialises, and it is also how a decompiler recovers the new { Name = ..., Age = ... } syntax — the generated anonymous-type class itself is just the usual <>f__AnonymousType0 with its read-only properties.

What the tree cannot tell you

Constant folding runs before expression-tree lowering, so arithmetic on literals is gone by the time the tree is built. x => x * (60 * 60) lowers to Expression.Multiply(x, Expression.Constant(3600, typeof(int))); no decompiler can recover 60 * 60, because the compiled assembly never contained it. The same applies to const fields referenced from the lambda — they are inlined as Constant nodes with the value, and the name of the constant is lost.

The second limit is one the language imposes rather than the compiler. An expression-tree lambda can only have an expression body: no statements, no assignment, no ?., no pattern matching, no dynamic, no async, no tuples, no local functions, and the compiler refuses the conversion (CS0834 and friends) rather than lowering them. The practical consequence for decompilation is that a compiler-generated tree is always a pure nest of factory calls with no control flow between them — so if you see branches, loops or a Block node being built, you are looking at a hand-constructed tree, not a lowered lambda, and a decompiler correctly leaves it as the factory calls.

What a decompiler folds, and what it shows

Everything above reduces to a small set of rules. The outer Expression.Lambda<TDelegate>(body, new ParameterExpression[] { ... }) with parameters created by Expression.Parameter(typeof(T), "name") gives the lambda header, including the original parameter names, which are literal strings in the IL. The body folds bottom-up: each binary and unary factory maps to one operator, Property/Field/Call print the member their ldtoken resolves to, Constant prints a literal, Field on a Constant of a display class prints the captured variable, Quote is transparent, MemberInit/Bind and the three-argument New rebuild initializers and anonymous types, and Convert is dropped where C# would reinsert it. What remains ambiguous — a Convert that might be an explicit cast, a Constant that might have been an arithmetic expression, a four-argument Equal whose operator method is just == in source — is rendered the shortest way that recompiles to the same tree.

That is exactly what Glass.NET does when it meets a method that builds a tree: it shows the lambda when the shape is a compiler lowering, and the factory calls when it is not. Both views are worth having. The folded lambda tells you what the author wrote; the lowered view tells you what the query provider on the other end actually receives — the closure Constant it must evaluate, the Convert nodes it must translate, the op_Equality it must map to a string comparison, and the Quote that marks a sub-query it has to translate rather than run. Open an assembly that builds queries, pick a method that returns an Expression<...>, and switch between the C# and IL views to watch a one-line lambda unfold into the tree the runtime really gets. For the full workflow, see how to decompile a .NET DLL to C#.

Obfuscating a type you serialize with Newtonsoft.Json: [JsonProperty] is the contract, and TypeNameHandling''s $type is a landmine

Zero Heartbeat — Wed, 21 Oct 2026 23:44:27 +0000

Here is a type that works perfectly until the day you obfuscate it:

public sealed class Order
{
    public string Customer { get; set; } = "";
    public decimal Total { get; set; }
    public DateTime PlacedOn { get; set; }
}

Serialize it with JsonConvert.SerializeObject(order) and you get {"Customer":"…","Total":…,"PlacedOn":"…"}. Run the assembly through a renamer and serialize again, and you get {"a":"…","b":…,"c":"…"}. Nothing threw. The build was green. Every consumer of that JSON — a frontend, a sister service, a document you stored last week and read back today — is now broken, and it broke at runtime, in a place no compiler and no build step could ever see.

This is the single most common way obfuscation "breaks serialization," and with Newtonsoft.Json it bites harder than with System.Text.Json, for one structural reason: Json.NET has no compile-time source generator. System.Text.Json lets you escape the reflection walk entirely with a [JsonSerializable] context that freezes the names into generated code before the obfuscator runs. Json.NET has no first-party equivalent — serialization always goes through a contract resolver that reflects over your live type at runtime. There is no escape hatch. So pinning the wire names with attributes is not an optimization you can skip for a hot path; it is the entire contract.

Why the rename reaches the wire

Internal calls survive renaming because they are linked by metadata token: the compiler emits call against a token, and a renamer that rewrites the callee rewrites every token that points at it, so the graph stays connected. Json.NET's DefaultContractResolver does not use a token. At serialize time it walks your type with reflection, reads each member's actual CLR Name, applies the resolver's naming strategy, and writes that string as the JSON key:

// Inside the contract resolver, conceptually:
//   property.PropertyName = namingStrategy.GetPropertyName(member.Name, hasSpecifiedName: false);
//   member.Name == "Customer"  ->  "Customer"   (default strategy: verbatim)
//                               ->  "customer"   (CamelCaseNamingStrategy)
var settings = new JsonSerializerSettings
{
    ContractResolver = new DefaultContractResolver { NamingStrategy = new CamelCaseNamingStrategy() }
};

The JSON key "Customer" exists only because the property is named Customer. There is no token joining the string in the file to the member in the assembly — the join is the name. Deserialization runs the same machinery in reverse: it reads the incoming key and matches it, by string, to a member. So when the renamer turns Customer into a, the resolver does exactly what it is told — it reads the member now called a and writes "a" — and the round-trip to anyone expecting "Customer" is dead. A naming strategy changes the casing of that string; it does nothing to save you, because it is still deriving the key from a name the obfuscator just moved.

The fix is [JsonProperty], not a keep rule

The instinct is to exclude the DTO from renaming. Don't — that surrenders exactly the type an attacker most wants to read, and it is unnecessary. The wire name should be a constant, not a side effect of the member name, and [JsonProperty] makes it one:

public sealed class Order
{
    [JsonProperty("customer")] public string Customer { get; set; } = "";
    [JsonProperty("total")]    public decimal Total { get; set; }
    [JsonProperty("placedOn")] public DateTime PlacedOn { get; set; }
}

Now the resolver reads the attribute's string literal — "customer" — not the member name. That literal lives in the custom-attribute blob in metadata, which renaming never touches; the renamer is free to turn Customer into b, and the JSON key is still "customer". This is the key distinction: the member does get renamed (which is the point of obfuscating), and only the string Json.NET reads is pinned. A keep rule would preserve the member name on disk — the opposite of what you want.

The rule, then, is simple and total: every serialized member gets an explicit [JsonProperty] name. A single un-attributed property falls back to its CLR name and becomes the one field that breaks. If you serialize fields or opt a type into MemberSerialization.Fields with [JsonObject], the same applies to every field. This is easy to enforce in review and easy to see in a diff — and unlike a naming strategy, it does not quietly depend on the member name surviving.

The constructor is a second name binding

Immutable DTOs hide a second trap. When a type has no default constructor, Json.NET deserializes it by matching each JSON value to a constructor parameter — by parameter name, case-insensitively:

public sealed class Order
{
    [JsonConstructor]
    public Order(string customer, decimal total, DateTime placedOn)  // param names matter
    {
        Customer = customer; Total = total; PlacedOn = placedOn;
    }

    [JsonProperty("customer")] public string Customer { get; }
    [JsonProperty("total")]    public decimal Total { get; }
    [JsonProperty("placedOn")] public DateTime PlacedOn { get; }
}

Json.NET pairs the "customer" value with the constructor parameter named customer. That pairing lives in parameter-name metadata — and if your obfuscator rewrites parameter names to p0, p1, p2, the match fails and each property is silently left at its default. Two things keep this safe. Mark the chosen constructor with [JsonConstructor] so Json.NET is unambiguous about which one to use, and ensure parameter-name renaming is off for it. Most obfuscators, Nebula included, leave parameter names alone by default — they are not a meaningful attack surface — but when a DTO deserializes through a constructor, that default is load-bearing, so confirm it rather than assume it.

Enums serialize by their member name too

By default Json.NET writes enums as their numeric value, which renaming never touches. But the moment you add a StringEnumConverter — common, because a string is more readable and more stable on the wire — the enum is written by its member name, and that is a renameable identifier again:

[JsonConverter(typeof(StringEnumConverter))]
public enum Priority
{
    [EnumMember(Value = "low")]  Low,
    [EnumMember(Value = "high")] High,
}

Json.NET honours [EnumMember(Value = …)] on enum members, so pin each one. Now Priority.High serializes as "high" whether or not the field High has been renamed, because the converter reads the attribute's literal rather than the member name.

The bigger trap: TypeNameHandling writes your type's name into the document

Everything above is a property or a value. TypeNameHandling is different: it writes your type's identity into the document. When you enable it to round-trip polymorphic graphs — a base Payment with CreditCardPayment and BankTransferPayment subclasses, an object-typed field, a List<IMessage> — Json.NET embeds a $type discriminator so it can reconstruct the exact runtime type on the way back:

var settings = new JsonSerializerSettings { TypeNameHandling = TypeNameHandling.Auto };
string json = JsonConvert.SerializeObject(payment, settings);
// {
//   "$type": "MyApp.Payments.CreditCardPayment, MyApp",
//   "last4": "4242", "amount": 42.50
// }

Look at the value of $type: it is the type's assembly-qualified name — namespace, type name, assembly — assembled from the exact identifiers an obfuscator renames. Rename CreditCardPayment to a and flatten the namespace, and the same object now serializes as "$type": "a, MyApp". Your [JsonProperty] attributes do nothing here, because $type is not a property of your type; it is the type's name, and no property attribute pins a type name.

That makes $type far more dangerous than a property key, because it breaks across builds and across versions, not just within one. A document written by an un-obfuscated build, or by last month's release, carries "…CreditCardPayment, MyApp". Feed it to your obfuscated build — whose type is now called a — and Json.NET cannot resolve the name and throws on deserialize. Anything that persists polymorphic JSON (a stored document, a queued message, a cached payload, a saved project file) is exposed the instant the type names on the two sides disagree.

The fix is neither an attribute nor a keep rule. It is a custom ISerializationBinder that maps a stable logical name you choose to the Type, so the wire carries a constant you own while the type underneath renames freely:

public sealed class StableTypeBinder : ISerializationBinder
{
    // The wire names are string literals; the Type values rename consistently with your code.
    private static readonly Dictionary<string, Type> ByName = new()
    {
        ["creditCardPayment"] = typeof(CreditCardPayment),
        ["bankTransferPayment"] = typeof(BankTransferPayment),
    };
    private static readonly Dictionary<Type, string> ByType =
        ByName.ToDictionary(kv => kv.Value, kv => kv.Key);

    public void BindToName(Type serializedType, out string? assemblyName, out string? typeName)
    {
        assemblyName = null;                 // keep the assembly out of the wire entirely
        typeName = ByType[serializedType];   // -> "creditCardPayment", a constant
    }

    public Type BindToType(string? assemblyName, string typeName) => ByName[typeName];
}

var settings = new JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.Auto,
    SerializationBinder = new StableTypeBinder(),
};
// {"$type":"creditCardPayment","last4":"4242","amount":42.50}

The dictionary keys — "creditCardPayment" — are string literals the obfuscator cannot touch. The dictionary values are typeof(CreditCardPayment), which Json.NET and the renamer both resolve through the metadata token, so they rename consistently with the rest of your code. The result is a discriminator that is stable across every build and every version, no matter how aggressively the types are renamed, and as a bonus it keeps your namespace layout out of the document. (It is also the recommended posture for TypeNameHandling on security grounds: a binder that only resolves a fixed allow-list of types refuses to instantiate anything else, which is the mitigation for the deserialization-gadget risk TypeNameHandling otherwise carries.)

Prove it with a round-trip on the protected build

Whichever path you pick, the test that matters runs against the obfuscated output, not the debug build — the whole failure mode is that the names only move after Nebula runs. A round-trip against the protected assembly is the one assertion that catches it:

[Fact]
public void Protected_build_round_trips_the_wire_contract()
{
    var settings = new JsonSerializerSettings
    {
        TypeNameHandling = TypeNameHandling.Auto,
        SerializationBinder = new StableTypeBinder(),
    };

    Payment payment = new CreditCardPayment { Last4 = "4242", Amount = 42.50m };
    string json = JsonConvert.SerializeObject(payment, settings);

    // The contract, asserted literally — these are what consumers and stored docs depend on.
    Assert.Contains("\"$type\":\"creditCardPayment\"", json);
    Assert.Contains("\"last4\":\"4242\"", json);
    Assert.DoesNotContain("\"a\"", json);                 // no leaked renamed member or type

    var back = (CreditCardPayment)JsonConvert.DeserializeObject<Payment>(json, settings)!;
    Assert.Equal("4242", back.Last4);                     // constructor/members matched by pinned names
    Assert.Equal(42.50m, back.Amount);
}

Wire this against the post-obfuscation artifact in CI and the "serialization broke" incident becomes a failed test instead of a customer email. The principle underneath it is the one worth carrying to every reflection-driven framework you obfuscate: a name a framework reads at runtime is a contract, and a contract belongs in a string literal the obfuscator cannot move — not in a member name, a type name, or a namespace it is paid to.

Nebula.NET renames aggressively by design; [JsonProperty], [EnumMember], and a stable ISerializationBinder are how you keep the handful of names that have to stay while losing the ones that should go. For the System.Text.Json side of the same story, see obfuscating a type you serialize with System.Text.Json; for the broader pattern, what obfuscation breaks.

Decompiling C# string interpolation and interpolated string handlers

Zero Heartbeat — Wed, 21 Oct 2026 13:09:20 +0000

An interpolated string is one of the most innocent-looking pieces of C# you can write — $"Hello {name}, you have {count} messages" — and one of the least predictable once it reaches IL. There is no interpolation instruction. The compiler rewrites every $"..." into ordinary method calls, and it has three completely different ways of doing so: a string.Concat, a string.Format with a positional template, or — on modern targets — a construct-and-append sequence against DefaultInterpolatedStringHandler. Which one it picks depends on your target framework, the types in the holes, and whether the receiving method opted into a handler of its own. Walking each lowering explains what a decompiler such as Glass.NET can fold back into $"...", and where it can only show you the machinery the compiler actually emitted.

Three lowerings, one syntax

The single most useful fact about $"..." is that the syntax tells you almost nothing about the IL. The compiler looks at where the string is going and what is in the holes and chooses:

The rest of this post is those four boxes, in order, with the IL each one produces and the fingerprint a decompiler uses to recognize it.

The concat shortcut

If every hole in the string is already a string, and no hole has an alignment or format specifier, the compiler does the cheapest possible thing: it calls String.Concat. Given

string Greet(string first, string last) => $"{first} {last}";

the body is simply a three-argument concat — the literal space is just another operand:

ldarg.1              // first
ldstr      " "
ldarg.2              // last
call       string System.String::Concat(string, string, string)
ret

This is byte-for-byte identical to what first + " " + last compiles to, and identical to a hand-written string.Concat(first, " ", last). There is no marker that says "this was interpolation." A decompiler is free to render it as $"{first} {last}", as first + " " + last, or as the explicit concat — all three are faithful readings of the same IL. The interpolation, as a distinct idea, did not survive compilation.

The format template

The moment a hole is not a string — a number, a DateTime, anything that needs formatting — the classic lowering is String.Format with a positional template. This is what you get on netstandard2.0, on .NET Framework, and on any target that predates the handler type. For

string Status(int count, double rate) => $"{count} items at {rate:P1}";

the compiler builds the template string, boxes the value-type arguments into an object[], and calls Format:

ldstr      "{0} items at {1:P1}"
ldc.i4.2
newarr     [System.Runtime]System.Object
dup
ldc.i4.0
ldarg.1              // count
box        [System.Runtime]System.Int32      // int -> object
stelem.ref
dup
ldc.i4.1
ldarg.2              // rate
box        [System.Runtime]System.Double     // double -> object
stelem.ref
call       string System.String::Format(string, object[])
ret

Two things are worth noticing here, because they are exactly what you see in the decompiled output. First, your format specifier :P1 is preserved verbatim inside the template as {1:P1} — the decompiler can read it straight out of the ldstr. Second, the value types are boxed; the object[] is the allocation cost this lowering carries, and it is the reason the newer handler form exists.

Because this is a literal String.Format call, it is indistinguishable from one you wrote by hand. A decompiler will show one of the two. Many print the string.Format("{0} items at {1:P1}", count, rate) call as-is, because it is the lower-level, more portable reading; a C#-aware decompiler may re-sugar it to $"{count} items at {rate:P1}" by parsing the template and mapping {0},{1} back onto the argument order. Both are correct.

The handler dance

On .NET 6 and later, a plain assignment of an interpolated string to a string no longer goes through String.Format. The compiler lowers it against DefaultInterpolatedStringHandler, a ref struct in System.Runtime.CompilerServices that accumulates the result into an internal buffer — no template parsing, no object[], no boxing of the arguments into the array. The same Status method on a modern target decompiles to this shape:

string Status(int count, double rate)
{
    DefaultInterpolatedStringHandler handler =
        new DefaultInterpolatedStringHandler(9, 2); // literalLength=9, formattedCount=2
    handler.AppendFormatted(count);
    handler.AppendLiteral(" items at ");
    handler.AppendFormatted(rate, "P1");
    return handler.ToStringAndClear();
}

Read the constructor arguments, because they are the first half of the fingerprint. The handler is created with (int literalLength, int formattedCount) — the total number of literal characters (" items at " is nine, plus any other literal runs) and the number of holes. The handler uses those to size its buffer up front. Then the body is a strict interleaving: one AppendLiteral per run of literal text, one AppendFormatted per hole, in source order, finished by exactly one ToStringAndClear() that produces the string and returns the buffer. In IL it is a sequence of call/callvirt against a local of the handler type:

ldloca.s   handler
ldc.i4.s   9
ldc.i4.2
call       instance void DefaultInterpolatedStringHandler::.ctor(int32, int32)
ldloca.s   handler
ldarg.1
call       instance void DefaultInterpolatedStringHandler::AppendFormatted<int32>(!!0)
ldloca.s   handler
ldstr      " items at "
call       instance void DefaultInterpolatedStringHandler::AppendLiteral(string)
...
ldloca.s   handler
call       instance string DefaultInterpolatedStringHandler::ToStringAndClear()
ret

That literal-length-and-count constructor, the alternating AppendLiteral/AppendFormatted<T> calls on a single handler local, and the terminating ToStringAndClear are a shape nothing else produces. A modern decompiler recognizes it and folds the whole block back to $"{count} items at {rate:P1}". A decompiler that does not — or that is reading output where the optimizer hoisted or reordered some of the appends — shows the handler calls literally. That is not a failure: it is the honest reading, and it is often more informative than the sugar, because it shows you exactly where the buffer allocation and each AppendFormatted<T> generic instantiation happen.

Alignment, format, and the culture trap

The AppendFormatted family has several overloads, and which one the compiler selects tells you what was in the braces. A bare hole {x} becomes AppendFormatted<T>(T value). A format specifier {x:N2} becomes AppendFormatted<T>(T value, string? format) with the format as a literal string argument. An alignment {x,10} becomes AppendFormatted<T>(T value, int alignment), and both together {x,10:N2} becomes AppendFormatted<T>(T value, int alignment, string? format). So you can reconstruct the exact brace contents from the overload and its constant arguments — the format text is right there in the call.

There is one behavioral subtlety that the decompiled view makes visible and that bites people who refactor between the forms. DefaultInterpolatedStringHandler formats using the current culture by default, exactly like string.Format. If you need invariant or a specific culture, the interpolated string must be passed to an API that threads an IFormatProvider into the handler's constructor — the compiler then emits a constructor overload taking the provider. If you see a DefaultInterpolatedStringHandler constructed without a provider argument, the result is culture-sensitive; that is a real semantic detail hiding in the lowered IL, not noise.

Custom handlers: when the string is never built

The handler pattern is not limited to building a string. Any method can accept an interpolated string directly by taking a parameter whose type is marked [InterpolatedStringHandler]. The compiler then constructs that handler and appends into it, so the interpolated string is formatted straight into the destination with no intermediate string at all. The clearest example is StringBuilder.Append:

sb.Append($"id={id} name={name}");

does not build a string and append it. It lowers to the construction of a StringBuilder.AppendInterpolatedStringHandler that writes directly into sb:

var handler = new StringBuilder.AppendInterpolatedStringHandler(8, 2, sb); // note: sb passed in
handler.AppendLiteral("id=");
handler.AppendFormatted(id);
handler.AppendLiteral(" name=");
handler.AppendFormatted(name);
sb.Append(ref handler);

The giveaway in the decompiled code is that the handler's constructor takes a third argument — the StringBuilder itself — and the final call is Append(ref handler) rather than Append(string). That extra constructor argument comes from an [InterpolatedStringHandlerArgument("sb")] attribute on the parameter, which tells the compiler to forward the receiver into the handler.

The most striking case is a handler that can decide not to build the string at all. Debug.Assert(condition, $"expensive {Describe()} message") must not pay for the message when the assertion passes. Its handler constructor has a trailing out bool parameter:

var handler = new AssertInterpolatedStringHandler(17, 1, condition, out bool shouldAppend);
if (shouldAppend)
{
    handler.AppendLiteral("expensive ");
    handler.AppendFormatted(Describe());
    handler.AppendLiteral(" message");
}
Debug.Assert(condition, ref handler);

When condition is true the constructor sets shouldAppend = false, the whole if block is skipped, and Describe() is never called. This is the conditional-evaluation behavior people rely on without realizing it, and it is only visible in the lowered form — there is no way to express "skip the interpolation" in the $"..." syntax itself. A decompiler that folds this back to Debug.Assert(condition, $"...") is correct about the result but is hiding the shouldAppend guard; switching to the IL or lowered-C# view in Glass.NET is how you confirm the message really is skipped on the hot path.

Constant interpolation disappears entirely

The last case is the one with nothing to recover. If every part of an interpolated string is a compile-time constant, the whole thing is folded at compile time:

const string Version = "2";
const string Banner = $"Acme v{Version}";   // becomes the constant "Acme v2"

Banner is emitted as the literal string "Acme v2". There is no handler, no Format, no Concat — the metadata holds a constant, and any reference to Banner is just ldstr "Acme v2". A decompiler shows a plain string constant, because that is all that exists. The same is true of a no-hole interpolated string like $"ready", which is just the literal "ready". Interpolation that the compiler could resolve statically leaves no trace of having been interpolation.

What to take from the decompiled view

String interpolation is the cleanest illustration of a theme that runs through this whole series: the surface syntax is a request, and the compiler answers it differently depending on context. The same $"..." can be a String.Concat, a String.Format with a boxed object[], a DefaultInterpolatedStringHandler sequence, a direct append into a StringBuilder, or — when the inputs are constant — nothing but a baked-in literal. Only some of those carry a fingerprint strong enough to rebuild the $"...": the handler dance and the custom-handler forms are recognizable; the concat and format forms are indistinguishable from hand-written calls; the constant form is already gone. A good decompiler folds back what it can prove and shows the lowered calls where it cannot — and the lowered calls are often the point, because that is where you see the boxing, the buffer allocation, the culture dependence, and the shouldAppend guard that the sugar quietly hides. Open the assembly in Glass.NET, switch a method to IL, and watch a one-line $"..." unfold into the calls the runtime actually makes. For the full workflow, see how to decompile a .NET DLL to C#.

Obfuscating code that uses dynamic: the runtime binder looks members up by name, so a renamed property is a RuntimeBinderException

Zero Heartbeat — Fri, 16 Oct 2026 20:11:12 +0000

Here is a method that works on every build except the one you ship:

public sealed class Settings
{
    public int    Timeout  { get; set; } = 30;
    public string Endpoint { get; set; } = "https://api.example";
}

static void Configure(dynamic settings)
{
    int timeout = settings.Timeout;          // compiles; passes tests; dies when obfuscated
    settings.Endpoint = "https://api.example/v2";
}

On the debug build, Configure(new Settings()) does what it says. On the obfuscated build it throws:

Microsoft.CSharp.RuntimeBinder.RuntimeBinderException:
  'a' does not contain a definition for 'Timeout'

Nothing is wrong with the obfuscator. The type was renamed to a, its property was renamed, and the dynamic site — which never knew about either — kept asking for Timeout by name. To see why that is unavoidable, and what to do about it, read the IL the compiler emitted for that one line.

Where the name lives

A normal property read, int timeout = settings.Timeout; with settings typed as Settings, compiles to a callvirt against a metadata token:

callvirt instance int32 Acme.Settings::get_Timeout()

The token points at a row in the method table. When Nebula renames get_Timeout to a, it rewrites the row and every token that references it — the call site and the member move together, and the string Timeout ceases to exist anywhere in the assembly. That is why renaming is invisible to ordinary code.

The dynamic version compiles to something else entirely. The compiler generates a hidden nested class to hold a cached call site, and the site is initialised with a binder that is handed the member name as a string:

// hidden container the compiler generates for Configure
.class nested private '<>o__0'
{
  .field public static class [System.Runtime]System.Runtime.CompilerServices.CallSite`1<
      class [System.Runtime]System.Func`3<CallSite, object, object>> '<>p__0'
}

// first use of the site: build the binder, with the member NAME as data
IL_0007: ldc.i4.0                                       // CSharpBinderFlags.None
IL_0008: ldstr      "Timeout"                           // <-- the binding, as a string
IL_000d: ldtoken    Acme.Program                        // calling context
IL_0012: call       class Type Type::GetTypeFromHandle(RuntimeTypeHandle)
IL_0017: ldc.i4.1
IL_0018: newarr     CSharpArgumentInfo
...
IL_002a: call       CallSiteBinder Binder::GetMember(CSharpBinderFlags, string, Type, IEnumerable`1<CSharpArgumentInfo>)
IL_002f: call       CallSite`1<...> CallSite`1<...>::Create(CallSiteBinder)
IL_0034: stsfld     ... '<>o__0'::'<>p__0'

// every use: invoke the site's delegate with the receiver
IL_0039: ldsfld     '<>o__0'::'<>p__0'
IL_003e: ldfld      !0 CallSite`1<...>::Target
IL_0043: ldsfld     '<>o__0'::'<>p__0'
IL_0048: ldarg.0                                        // settings (object)
IL_0049: callvirt   instance !2 Func`3<CallSite, object, object>::Invoke(!0, !1)

There is no token for Timeout anywhere in that sequence. The only mention of the member is ldstr "Timeout", a string literal passed to Binder.GetMember. At runtime, the C# runtime binder takes the actual type of the object that arrives in settings, searches it for a member called Timeout — the same search reflection does — builds a rule for that type, caches it in the site, and executes it. The assignment compiles the same way through Binder.SetMember(..., "Endpoint", ...); a method call through Binder.InvokeMember(..., "Save", ...).

After renaming, the type has a member a and the site still says "Timeout". The binder searches, finds nothing, and throws. The link was a name, and the renamer, which only moves tokens, had no reason to know.

Why string encryption is beside the point

The reflex, on seeing ldstr "Timeout", is to think Nebula's string encryption will take care of it. It will encrypt it — and the decrypted value handed to Binder.GetMember at runtime is the same "Timeout", which still does not exist on the renamed type. Encryption changes nothing about the binding.

What it changes is the leak. In an unencrypted build, every dynamic site is a plain-text signpost in the user-string heap: a reader opening the assembly sees "Timeout" passed to a binder right beside a type whose members are now a, b, c, and has recovered one original name for free. This is the quieter cost of dynamic in a protected assembly — where it does not break, it still narrates. With encryptStrings on, the signpost is gone from the static view; the lookup is exactly as broken as before.

Which operations bind by name

Not every dynamic operation is a name lookup, and knowing which are tells you where to look:

Member access, assignment, invocation — s.Timeout, s.Endpoint = …, s.Save() — go through GetMember, SetMember, InvokeMember with the member name as a string. These break when the member is renamed.
Indexing — s[0] — goes through GetIndex/SetIndex, which resolves the type's default member ([DefaultMember("Item")], the indexer's Item property). Rename the indexer and the dynamic index breaks the same way.
Operators and conversions — a + b, (int)d — go through BinaryOperation/Convert, which resolve user-defined operators by their special names, op_Addition, op_Implicit. Those are specialname members the runtime itself relies on, and Nebula does not rename them, so dynamic arithmetic over your types keeps working.
Invocation of a delegate value — d(x) where d holds a delegate — goes through Invoke, no name, no problem.
ExpandoObject and any IDynamicMetaObjectProvider — the "members" are dictionary keys supplied at runtime, not CLR members. Renaming never touches data, so expando.Timeout keeps working regardless. The same is true of a dynamic over a COM IDispatch proxy: the names are resolved by the COM server, not by your metadata.

The dangerous case is the first bullet applied to types you own, and there is one pattern that hides it particularly well.

The pattern that breaks a whole visitor at once

Double dispatch by dynamic is a popular shortcut for a visitor without the Accept boilerplate:

public abstract class Shape { }
public sealed class Circle : Shape { public double R { get; init; } }
public sealed class Rect   : Shape { public double W { get; init; } public double H { get; init; } }

public static class Area
{
    public static double Of(Shape s) => Compute((dynamic)s);    // picks the overload at runtime

    private static double Compute(Circle c) => Math.PI * c.R * c.R;
    private static double Compute(Rect r)   => r.W * r.H;
}

This compiles to Binder.InvokeMember(..., "Compute", typeof(Area), ...) with the runtime binder selecting the overload by the argument's actual type. Rename Compute to b and every shape fails on the first call — not one property, the entire dispatch — with 'Area' does not contain a definition for 'Compute'. Because the overloads are private, nothing else in the assembly references them by anything but this one string, so there is no compile-time trace that they are reached at all. The unprotected test suite is green; the protected build cannot compute a single area.

Fixes, in order of preference

1. Replace dynamic with an interface or a virtual. This is the right answer far more often than it feels. Duck typing between types you own is what interfaces are for, and the interface call is a token-bound callvirt that survives renaming, runs without a binder, and is checked by the compiler:

public interface IHasArea { double Area(); }
public sealed class Circle : Shape, IHasArea { … public double Area() => Math.PI * R * R; }

public static double Of(Shape s) => s is IHasArea a ? a.Area() : 0;   // no binder, no name

The visitor becomes an ordinary virtual Accept or an IHasArea; the settings reader takes Settings or an ISettings. If the dynamic existed only to avoid writing a type, writing the type is the fix.

2. Pin only the members a site reaches. Where dynamic is genuinely required — a scripting host that calls into your objects, a dynamic-language runtime, a plugin boundary you do not control — the set of members it touches is small and known. Mark exactly those with the standard [Obfuscation] attribute, which Nebula honours through autoDetect:

public sealed class Settings
{
    [Obfuscation(Exclude = true)] public int    Timeout  { get; set; } = 30;
    [Obfuscation(Exclude = true)] public string Endpoint { get; set; } = "";
    public  string InternalCacheKey { get; set; } = "";      // still renames
    private int    _retries;                                  // still renames
}

Exclude = true on a member keeps that member's name and nothing else; the type still renames, the other members still rename. Or keep it out of the source entirely with the exclude list in nebula.config.json, which takes Namespace.Type.Member for a single member:

{
  "inputs": ["bin/Release/net8.0/Acme.Studio.dll"],
  "encryptStrings": true,
  "controlFlowObfuscation": true,
  "exclude": [
    "Acme.Settings.Timeout",
    "Acme.Settings.Endpoint",
    "Acme.Area.Compute"
  ]
}

What you should not do is exclude Acme.Settings wholesale. That preserves every member — the ones the binder reaches and the dozen it never will — to protect two properties, and it is the type an attacker most wants to read.

3. Find every site before you ship. Dynamic sites announce themselves in the IL: a reference to Microsoft.CSharp.RuntimeBinder.Binder, hidden <>o__ containers, and ldstr literals feeding them. nebula inspect --strings lists every literal in the assembly, and the ones that are also member names on your types are the ones to look at — Timeout, Endpoint, Compute stand out immediately beside genuine user-facing strings. Cross-check against a search for dynamic in the source and you have the complete list of members to pin.

The test that catches it

Whatever you choose, assert it on the protected build, because the failure only exists there. A dynamic site throws at the first use, so a test that exercises each site is a test that fails loudly when a pin is missing:

[Fact]
public void Dynamic_sites_still_bind_on_the_protected_build()
{
    var s = new Settings();
    Configure(s);                                           // GetMember "Timeout", SetMember "Endpoint"
    Assert.Equal("https://api.example/v2", s.Endpoint);

    Assert.Equal(Math.PI, Area.Of(new Circle { R = 1 }), precision: 10);   // InvokeMember "Compute"
    Assert.Equal(6.0,     Area.Of(new Rect { W = 2, H = 3 }));
}

Run that against the output of the obfuscation step in CI — the same place a round-trip serialization test belongs — and a RuntimeBinderException becomes a red build instead of a customer's crash report.

The principle is the same one that governs reflection and serialization: a name that is resolved at runtime is a contract, and a renamer cannot see a contract that is written as a string. dynamic is the C# feature that turns an ordinary member access into exactly that kind of string. Nebula.NET will rename everything you let it; your job is to make sure the one name a binder will ask for by text is either no longer asked for, or deliberately kept. For the wider map of what runtime name lookups break, see what obfuscation breaks.

Site licenses: binding one Keyright key to the customer''s domain instead of a machine, and what that binding can and cannot prove

Zero Heartbeat — Fri, 16 Oct 2026 20:10:06 +0000

A customer with four hundred desktops does not want to activate four hundred machines, and their IT team will tell you so before the purchase order is signed. The answer every vendor arrives at is a site license: one key for the whole organisation, no per-machine ceremony. The question that rarely gets written down is what such a key is bound to. A node-locked key is bound to a machine fingerprint. A floating key is bound to a seat count on a server. A site key with no binding at all is a file that unlocks your product for anyone who has it — and files travel.

This post builds a site license on Keyright that is bound to something the whole organisation shares and a stranger does not: the directory domain. It is a signed entitlement, not a new license type; the gate is twenty lines; and the threat model is stated honestly, because a domain name is a fence, not a lock.

What the key says

A node-locked Keyright license carries a machineId and the validator refuses to run on any machine whose fingerprint does not match. A site license sets machineId to nothing and instead names the site in the signed entitlement set:

{
  "product":  "acme-studio",
  "licensee": "Contoso Ltd",
  "expiryUtc": "2027-10-17T00:00:00Z",
  "tier":     "pro",
  "entitlements": {
    "site:domain":     "corp.contoso.example",
    "site:domain-sid": "S-1-5-21-3623811015-3361044348-30300820",
    "export":          "true",
    "max-projects":    "unlimited"
  },
  "signature": "…"
}

Two things matter here. The site: entries are ordinary entitlements — string values inside the canonical payload that the signature covers — so a customer can no more change corp.contoso.example to home.example than they can push the expiry out a year: one changed byte and LicenseStatus.SignatureInvalid is what the app sees. And the prefix is a convention, not a Keyright feature: it keeps where this key may run visibly separate from what this key unlocks, so nobody later gates a feature on a site claim or vice versa.

site:domain-sid is optional. The DNS domain is the portable, cross-platform binding; the SID is the Windows-only hardening you add when the customer or the contract value justifies it. We will come back to what each one actually proves.

Where the machine's identity comes from

The app has to answer "what domain am I on?" from the machine itself, offline, at startup. There are two tempting APIs and one of them is wrong.

Environment.UserDomainName returns the NetBIOS domain of the user running the process — CONTOSO — and on a machine that is not joined to any domain it returns the machine name instead. That makes it useless for a fail-closed check (you cannot tell "not joined" from "joined to a domain that happens to share the machine's name") and it is flat, so it cannot express that emea.corp.contoso.example is part of corp.contoso.example.

IPGlobalProperties.GetIPGlobalProperties().DomainName returns the host's primary DNS suffix, which domain membership sets: emea.corp.contoso.example on a joined workstation, an empty string on a laptop that was never joined. It is hierarchical, it is cross-platform (on Linux it reads the host's configured domain name), and the empty-string case is exactly the signal you want.

For the SID, WindowsIdentity.GetCurrent().User.AccountDomainSid returns the SID of the domain the current account belongs to — S-1-5-21-… with the final relative identifier stripped. For a domain user on a joined machine that is the forest's domain SID. For a local account it is the local machine's SID, which will not match and should not.

using System.Net.NetworkInformation;
using System.Security.Principal;

public interface ISiteIdentity
{
    string? DnsDomain { get; }   // "emea.corp.contoso.example"; null when not joined
    string? DomainSid { get; }   // "S-1-5-21-…"; null off Windows or for a local account
}

public sealed class RealSiteIdentity : ISiteIdentity
{
    public string? DnsDomain
    {
        get
        {
            try
            {
                var d = IPGlobalProperties.GetIPGlobalProperties().DomainName;
                return string.IsNullOrWhiteSpace(d) ? null : d.TrimEnd('.').ToLowerInvariant();
            }
            catch { return null; }                       // no network stack info → treat as unjoined
        }
    }

    public string? DomainSid
    {
        get
        {
            if (!OperatingSystem.IsWindows()) return null;
            try
            {
                using var id = WindowsIdentity.GetCurrent();
                return id.User?.AccountDomainSid?.Value;  // null for well-known/non-domain SIDs
            }
            catch { return null; }
        }
    }
}

Every failure path returns null, and null means "not joined". That is deliberate: the gate below treats an unknown identity on a site-licensed key as a refusal, not a pass.

The gate

The gate runs after Validate() and only does anything when the key carries a site claim. Matching the DNS domain is a suffix match on label boundaries: a key issued for corp.contoso.example must accept a workstation in the child domain emea.corp.contoso.example, but must not accept notcorp.contoso.example — hence the leading dot in the comparison.

public enum SiteStatus { Ok, NotSiteLicensed, NotJoined, WrongDomain, WrongDomainSid }

public static class SiteGate
{
    public static SiteStatus Check(LicenseInfo info, ISiteIdentity site)
    {
        var claim = info.Entitlements.GetRaw("site:domain");
        if (string.IsNullOrWhiteSpace(claim))
            return SiteStatus.NotSiteLicensed;            // ordinary key: nothing to check here

        var here = site.DnsDomain;
        if (here is null)
            return SiteStatus.NotJoined;                  // fail closed: unknown ≠ allowed

        claim = claim.Trim().TrimEnd('.').ToLowerInvariant();
        bool inDomain = here == claim
                     || here.EndsWith("." + claim, StringComparison.Ordinal);
        if (!inDomain)
            return SiteStatus.WrongDomain;

        var sidClaim = info.Entitlements.GetRaw("site:domain-sid");
        if (!string.IsNullOrWhiteSpace(sidClaim)
            && !string.Equals(site.DomainSid, sidClaim.Trim(), StringComparison.OrdinalIgnoreCase))
            return SiteStatus.WrongDomainSid;

        return SiteStatus.Ok;
    }
}

Wire it at startup, after the signature and expiry checks the SDK already performs:

static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-studio",
    PublicKeyBase64 = AcmeKeys.LicensePublicKey,        // public key only; safe to ship
});

LicenseInfo info = License.Validate();                  // signature, product, expiry, (no) node-lock
if (!info.IsValid) { RunEvaluation(info); return; }

var site = SiteGate.Check(info, new RealSiteIdentity());
if (site is not (SiteStatus.Ok or SiteStatus.NotSiteLicensed))
{
    RunEvaluation(info, reason: site);                  // "this key is for corp.contoso.example"
    return;
}

RunLicensed(info);

Note what the SDK did not do: with machineId absent, Validate() never computed a machine fingerprint, so there is no per-machine state, nothing to "activate", and nothing that drifts when IT re-images a desktop. Four hundred machines, one file, one check.

One deliberate ordering: the site check runs after IsValid. A key with a bad signature never reaches the gate, so the entitlements it carries — including a site:domain an attacker could have typed in — are never read. Entitlements are only trustworthy once the signature over them has verified, and Keyright enforces that by returning an empty entitlement set for anything that did not validate.

Getting the values from the customer

The weak point of any identity-bound license is the hand-off: the customer has to tell you what their domain is, and if they tell you something subtly different from what the machine reports (contoso.example versus corp.contoso.example, a NetBIOS name instead of a DNS one), the first launch after purchase fails with "wrong domain" while everyone involved insists they are on the right domain.

Close that gap by making the product report its own answer, from exactly the code path the gate uses:

// yourapp --site-info
var id = new RealSiteIdentity();
Console.WriteLine($"DNS domain : {id.DnsDomain ?? "(not domain-joined)"}");
Console.WriteLine($"Domain SID : {id.DomainSid ?? "(n/a)"}");

Ask for that output on the order form. Neither value is confidential — the DNS suffix is in every email the company sends, and the domain SID is readable by any authenticated user in the domain — so this is no more sensitive than asking for a company name. The issuing side writes the two strings into the entitlements and signs; what the customer pasted is, by construction, what the check will see. (Issue for the parent domain the customer names, not the child the diagnostic happened to run in: a key for corp.contoso.example covers EMEA and APAC; a key for emea.corp.contoso.example does not.)

What the binding proves — honestly

Here is the part that belongs in your own threat model, not just the marketing page.

A DNS domain name is a policy fence. It is not a secret and it is not a cryptographic identity. Anyone holding a leaked site key can stand up a throwaway forest named corp.contoso.example, join a VM to it, and the name check passes. What the name does stop is the overwhelmingly common failure: the employee who copies license.json to a home PC, the contractor who keeps it after the engagement, the file that ends up in a shared drive. Those machines are not joined to the customer's domain, the gate fails closed, and the product tells them precisely why. For most site licenses — where the customer is a known organisation with a contract — that is the entire job.

A domain SID raises the bar considerably. The SID of a forest is generated at random when the forest is created; there is no supported tooling to choose it, so reproducing S-1-5-21-3623811015-3361044348-30300820 means cloning the customer's actual domain controller, not typing a name into a wizard. An attacker outside the organisation cannot do that; an insider with domain admin rights could, but an insider with domain admin rights is also the person the customer's contract already covers. Pin the SID when the deal is large enough that a renamed forest is a realistic attack, and accept that it is Windows-only — on a Linux workstation DomainSid is null, and the gate above skips the SID comparison only when the key does not carry one, so issue Linux-only sites without it.

Neither is a seat count. A site key says nothing about how many machines run it, because it was designed not to. If a contract needs a hard ceiling — "up to 400 concurrent installs" — the instrument is online activation with per-machine seats and a server that counts them, which is a different Keyright feature with a different operational cost (node-locking and seat management covers it). Trying to get a ceiling out of a domain claim is how vendors end up with a site license that is neither convenient nor enforced.

Tests: a fake site, three machines

The gate is pure given an ISiteIdentity, so the three machines in the figure are three tests:

sealed record FakeSite(string? DnsDomain, string? DomainSid) : ISiteIdentity;

static LicenseInfo SiteKey(string domain, string? sid = null) =>
    TestLicenses.Valid(entitlements: new()
    {
        ["site:domain"] = domain,
        ["site:domain-sid"] = sid!,          // null entry is dropped by the test helper
    });

[Fact]
public void Child_domain_workstation_passes_by_suffix()
    => Assert.Equal(SiteStatus.Ok, SiteGate.Check(
        SiteKey("corp.contoso.example", "S-1-5-21-1-2-3"),
        new FakeSite("emea.corp.contoso.example", "S-1-5-21-1-2-3")));

[Fact]
public void Unjoined_laptop_fails_closed()
    => Assert.Equal(SiteStatus.NotJoined, SiteGate.Check(
        SiteKey("corp.contoso.example"),
        new FakeSite(DnsDomain: null, DomainSid: null)));

[Fact]
public void Lookalike_domain_does_not_suffix_match()
    => Assert.Equal(SiteStatus.WrongDomain, SiteGate.Check(
        SiteKey("corp.contoso.example"),
        new FakeSite("notcorp.contoso.example", null)));

[Fact]
public void Renamed_forest_fails_the_sid_check()
    => Assert.Equal(SiteStatus.WrongDomainSid, SiteGate.Check(
        SiteKey("corp.contoso.example", "S-1-5-21-1-2-3"),
        new FakeSite("corp.contoso.example", "S-1-5-21-9-9-9")));

The third test is the one people forget. Without the leading dot in the suffix comparison, notcorp.contoso.example ends with corp.contoso.example and the gate opens for a domain the customer never owned.

Rolling it out

Treat the site claim like any new enforcement: issue the first site keys with the claim present but the gate in audit mode — log SiteStatus without acting on it — for a release, read the logs, then flip to enforcing. The audit-mode rollout pattern applies unchanged, and the thing it will catch is the one this post cannot predict for you: the customer whose "one domain" turns out to be three forests from two acquisitions.

A site license is a promise about where software may run, made to an organisation rather than a machine. Keyright lets you sign that promise into the key; the domain gives the app something real to check it against; and the SID, when you need it, makes the check expensive to lie to. What it does not do is count — and knowing that is what keeps the convenience from quietly becoming a leak.

Decompiling nullable value types: int? is a struct, a lifted operator is a HasValue check, and the box that erases Nullable

Zero Heartbeat — Fri, 16 Oct 2026 20:08:05 +0000

Everything the C# language lets you do with int? is a lie the compiler tells on behalf of a struct. There is no null in an int?. There is no special "nullable integer" type the CLR knows how to add. There is System.Nullable<int> — two fields, sixteen bytes, a value type like any other — and a compiler that rewrites a + b, a == null, a ?? 5 and (object)a into calls on that struct so thoroughly that the operators you typed never reach the IL. Reading an obfuscated or symbol-less assembly that uses nullable arithmetic means reading those rewrites, and a decompiler that renders them literally produces code that is correct, compilable, and unreadable.

This post follows each lowering through the IL and back out, and shows what Glass.NET has to recognise to give you the line you wrote.

`int?` is in the signature blob, not in an attribute

First the easy part, because it is the opposite of a trap readers of nullable reference types have learned to expect. string? leaves the type alone and records nullability in [Nullable] attributes — compile-time annotations the runtime ignores. int? is a different type: the generic struct Nullable<T> instantiated over int, and it appears as such in every signature:

.method public hidebysig static valuetype [System.Runtime]System.Nullable`1<int32>
        Add(valuetype [System.Runtime]System.Nullable`1<int32> a,
            valuetype [System.Runtime]System.Nullable`1<int32> b) cil managed

A decompiler prints int? for valuetype System.Nullable`1<int32> by the same rule it prints int for System.Int32 — the language's shorthand for a known type. No attribute is consulted; nothing can be stripped that would lose it. Metadata hardening that removes [Nullable] annotations leaves int? completely intact, because the information was never an annotation.

The struct itself is two fields and a handful of members, and those members are the entire vocabulary of every lowering that follows:

public struct Nullable<T> where T : struct
{
    private readonly bool hasValue;
    internal T value;
    public Nullable(T value);              // the "has a value" constructor
    public bool HasValue { get; }
    public T Value { get; }                // throws InvalidOperationException when !hasValue
    public T GetValueOrDefault();          // returns value unconditionally — no check, no throw
}

default(Nullable<T>) — both fields zero — is what the language calls null.

Lifted arithmetic: a conjunction, two `GetValueOrDefault`s, and a `newobj`

Take the method whose signature appears above:

static int? Add(int? a, int? b) => a + b;

The + on two int? values is a lifted operator: the result is null if either operand is null, otherwise the sum. The compiler emits that rule directly:

  .locals init (valuetype Nullable`1<int32> V_0,
                valuetype Nullable`1<int32> V_1,
                valuetype Nullable`1<int32> V_2)
  IL_0000: ldarg.0
  IL_0001: stloc.0                                   // copy a to a temp (operands evaluated once)
  IL_0002: ldarg.1
  IL_0003: stloc.1                                   // copy b
  IL_0004: ldloca.s   V_0
  IL_0006: call       instance bool Nullable`1<int32>::get_HasValue()
  IL_000b: ldloca.s   V_1
  IL_000d: call       instance bool Nullable`1<int32>::get_HasValue()
  IL_0012: and                                       // both have a value?
  IL_0013: brtrue.s   IL_0020
  IL_0015: ldloca.s   V_2
  IL_0017: initobj    Nullable`1<int32>              // the null result: default(Nullable<int>)
  IL_001d: ldloc.2
  IL_001e: ret
  IL_0020: ldloca.s   V_0
  IL_0022: call       instance !0 Nullable`1<int32>::GetValueOrDefault()
  IL_0027: ldloca.s   V_1
  IL_0029: call       instance !0 Nullable`1<int32>::GetValueOrDefault()
  IL_002e: add
  IL_002f: newobj     instance void Nullable`1<int32>::.ctor(!0)
  IL_0034: ret

Three details are worth noticing, because they are what a decompiler keys on:

The operands are copied to temporaries first, so each is evaluated exactly once even though it is read twice (once for HasValue, once for the value). A hand-written version would usually not bother.
The value is read with GetValueOrDefault, not Value. HasValue was just checked, so the re-check inside Value would be redundant and its throw path unreachable; GetValueOrDefault is a plain field read. Seeing GetValueOrDefault immediately after a HasValue guard is the single strongest signal that you are looking at compiler output rather than source.
The null result is initobj, not a call — there is no "null constructor"; the null state is the struct zeroed.

Render that literally and you get:

// faithful to the IL, and not what anyone wrote:
int? num = a, num2 = b;
return (num.HasValue & num2.HasValue)
    ? new int?(num.GetValueOrDefault() + num2.GetValueOrDefault())
    : null;

That compiles and is semantically exact. It is also three lines, two temporaries and four calls for a single +. Glass recognises the whole shape — temporaries, conjunction of HasValue, a pair of GetValueOrDefault feeding one binary operator, newobj on the true arm and initobj on the false — and emits a + b. The same template covers every lifted arithmetic, bitwise and shift operator; only the instruction between the two GetValueOrDefault calls changes.

Lifted equality is a different shape

Comparison is not lowered the same way, because the rule is different: two nulls are equal, and a null is unequal to any value. The compiler produces a branch-free expression for it:

static bool Same(int? a, int? b) => a == b;

  IL_0004: ldloca.s   V_0
  IL_0006: call       instance !0 Nullable`1<int32>::GetValueOrDefault()
  IL_000b: ldloca.s   V_1
  IL_000d: call       instance !0 Nullable`1<int32>::GetValueOrDefault()
  IL_0012: ceq                                       // values equal (both 0 when both null)
  IL_0014: ldloca.s   V_0
  IL_0016: call       instance bool Nullable`1<int32>::get_HasValue()
  IL_001b: ldloca.s   V_1
  IL_001d: call       instance bool Nullable`1<int32>::get_HasValue()
  IL_0022: ceq                                       // same has-value state
  IL_0024: and
  IL_0025: ret

That is (a.GetValueOrDefault() == b.GetValueOrDefault()) & (a.HasValue == b.HasValue). Walk the cases: both null → 0 == 0 and false == false → true. One null, one 5 → 0 == 5 is false → false. Both 5 → true. Note that GetValueOrDefault is called here without a prior HasValue guard — it is being used precisely because it is safe on a null — so the "GetValueOrDefault after guard" signal from the arithmetic case does not apply, and the decompiler needs a second template for this shape. <, >, <=, >= lower to the value comparison ANDed with a.HasValue & b.HasValue (two nulls are not less-than each other), which is a third variant of the same idea.

`== null`, `??`, and the pattern `is int v`

The simpler forms have simpler lowerings, each of which is a single-template match:

bool IsNull(int? a) => a == null;        // ldarga a; call get_HasValue; ldc.i4.0; ceq
int  OrFive(int? a) => a ?? 5;           // a.HasValue ? a.GetValueOrDefault() : 5
int  Force (int? a) => (int)a;           // ldarga a; call get_Value   — the only place Value appears
bool Test  (int? a) => a is int v && v > 0;   // a.HasValue && a.GetValueOrDefault() > 0

== null never compares a reference: there is no reference. It is !a.HasValue, and != null is a.HasValue. ?? becomes a conditional on HasValue with GetValueOrDefault on the value arm — again not Value, because the guard already ran. The explicit cast (int)a is the only lowering that calls get_Value, because it is the only one whose contract is to throw when there is nothing there; a decompiler can use that as a tell. And the type pattern a is int v over a nullable is lowered to HasValue plus GetValueOrDefault into v, with no isinst anywhere — the runtime type test the pattern looks like never happens, because the compiler already knows what the struct contains.

The box that erases `Nullable<T>`

Everything so far is the compiler rewriting language into calls. Boxing is different: here the runtime does something special, and the IL says less than it seems to.

object Box(int? a)   => a;              // box valuetype Nullable`1<int32>
int?   Unbox(object o) => (int?)o;      // unbox.any valuetype Nullable`1<int32>

Boxing an ordinary struct copies it to the heap behind an object header. The box instruction applied to Nullable<T> does not do that. The runtime checks hasValue: if it is false, the result is a null reference; if it is true, the result is a boxed T — a heap object of type System.Int32, byte-for-byte identical to boxing a plain int. Nullable<int> itself never reaches the heap. The consequences are visible from C#:

object o = (int?)5;
o.GetType()            // typeof(int) — not Nullable<int>
o is int               // true
o is int?              // true — same object satisfies both
object n = (int?)null; // n == null; there is no "boxed empty nullable"

unbox.any Nullable<int32> is the mirror image: given a boxed int it constructs a Nullable<int> with a value; given a null reference it produces an empty Nullable<int> instead of throwing the NullReferenceException that unbox.any on any other value type would throw. So (int?)o is the one cast in C# that quietly turns null into a value-type default.

For a decompiler this is a case of not inventing code. The box and unbox.any instructions name Nullable<int32> in their type operand, and the temptation is to render them as a conversion call or a new int?(…). The author wrote a plain implicit conversion and a plain cast; the special behaviour lives inside the runtime's implementation of two ordinary instructions, and the right output is object o = a; and (int?)o, nothing more.

What a decompiler gets wrong, and why it matters

Three failure modes show up in practice, and they are all versions of rendering the lowering instead of the language:

The HasValue/GetValueOrDefault dance printed in full — correct, verbose, and a reliable sign the tool has no lifted-operator templates. A method with six nullable additions becomes forty lines of temporaries.
new int?(x) where the source had x — the implicit conversion from int to int? is a newobj in the IL, and printing the constructor call is faithful but noisy. Glass emits the conversion implicitly wherever the target type makes it unambiguous.
A conversion call around box/unbox.any — inventing a method that is not in the IL to explain behaviour that is in the runtime.

The reason these matter beyond aesthetics is that nullable arithmetic clusters in exactly the code a reader is usually trying to understand — optional configuration, financial calculations with "not set" states, pattern-heavy domain logic — and the lowering multiplies its length by three or four. A decompiler that folds the templates back gives you the author's five lines; one that does not gives you a page of struct calls that all look the same.

The underlying lesson is the same one that governs ?. and ?? and foreach: the C# compiler lowers language features into ordinary IL over ordinary types, and the decompiler's job is to know every one of those shapes well enough to run them backwards. Nullable<T> is unusual only in how completely it disappears — into a struct on the way in, and into a plain boxed int or a null on the way out.

Obfuscating a type you serialize with System.Text.Json: [JsonPropertyName] is the contract, the renamed property is not

Zero Heartbeat — Fri, 16 Oct 2026 13:57:40 +0000

Here is a type that works perfectly until the day you obfuscate it:

public sealed class Order
{
    public string Customer { get; set; } = "";
    public decimal Total { get; set; }
    public DateTime PlacedOn { get; set; }
}

Serialize it with the default reflection-based System.Text.Json and you get {"customer":"…","total":…,"placedOn":"…"}. Run the assembly through a renamer and serialize again, and you get {"a":"…","b":…,"c":"…"}. Nothing threw. The build was green. Every consumer of that JSON — a frontend, a sister service, a stored document you read back next week — is now broken, and it broke at runtime, in a place no compiler and no validateOnBuild could ever see.

This is the single most common way obfuscation "breaks serialization", and it is worth understanding precisely, because the fix is not a blunt keep rule — it is one attribute, and it lets the property keep renaming.

Why the rename reaches the wire

Internal calls survive renaming because they are linked by metadata token: the compiler emits call against a token, and a renamer that rewrites the callee rewrites every token that points at it, so the graph stays connected. Reflection-based System.Text.Json does not use a token. At serialize time it walks your type with reflection, reads each property's actual CLR Name, applies the configured naming policy, and writes that string as the JSON key:

var opts = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
// For each property p:  key = opts.PropertyNamingPolicy.ConvertName(p.Name);
//   p.Name == "Customer"  ->  "customer"

The JSON key "customer" exists only because the property is named Customer. There is no token joining the string in the file to the member in the assembly — the join is the name. Deserialization runs the same machinery in reverse: it reads the incoming key and matches it, by string, to a property. So when the renamer turns Customer into a, the serializer does exactly what it is told — it reads the property now called a and writes "a" — and the round-trip to anyone expecting "customer" is dead.

The fix is an attribute, not a keep rule

public sealed class Order
{
    [JsonPropertyName("customer")] public string Customer { get; set; } = "";
    [JsonPropertyName("total")]    public decimal Total { get; set; }
    [JsonPropertyName("placedOn")] public DateTime PlacedOn { get; set; }
}

Now the serializer reads the attribute's string literal — "customer" — not the property name. The renamer is free to turn Customer into b; the attribute still says "customer", the JSON key is still "customer", and the contract holds. This is the key distinction: the member does get renamed (which is the point of obfuscating), and only the string the serializer reads is pinned. A keep rule would preserve the member name on disk — the opposite of what you want. The attribute preserves the behaviour while the name disappears.

The rule, then, is simple and total: every serialized member gets an explicit name. A single un-attributed property falls back to its CLR name and becomes the one field that breaks. That is easy to enforce in review, and easy to see in a diff.

The constructor is a second name binding

Immutable DTOs hide a second trap. When a type has no parameterless constructor, System.Text.Json deserializes it by matching each JSON property to a constructor parameter — by parameter name, case-insensitively:

public sealed class Order
{
    public Order(string customer, decimal total, DateTime placedOn)  // param names matter
    {
        Customer = customer; Total = total; PlacedOn = placedOn;
    }

    [JsonPropertyName("customer")] public string Customer { get; }
    [JsonPropertyName("total")]    public decimal Total { get; }
    [JsonPropertyName("placedOn")] public DateTime PlacedOn { get; }
}

The serializer pairs the "customer" JSON value with the constructor parameter named customer. That pairing lives in parameter-name metadata — and if your obfuscator rewrites parameter names to p0, p1, p2, the match fails and each property is silently left at its default. Two things keep this safe. Mark the chosen constructor with [JsonConstructor] so the serializer is unambiguous about which one to use, and ensure parameter-name renaming is off for it. Most obfuscators, Nebula included, leave parameter names alone by default — they are not a meaningful attack surface — but when a DTO deserializes through a constructor, that default is load-bearing, so confirm it rather than assume it.

Enums, extension data, and the members that don't bind by name

A few more members have their own rules. String-serialized enums are written by their member name unless you override it — the same reflection-reads-the-name problem — so pin them explicitly ([.NET 9] gives you [JsonStringEnumMemberName] for exactly this):

[JsonConverter(typeof(JsonStringEnumConverter<Priority>))]
public enum Priority
{
    [JsonStringEnumMemberName("low")]  Low,
    [JsonStringEnumMemberName("high")] High,
}

[JsonExtensionData] on a Dictionary<string, object> is the one member whose property name never reaches the wire — its contents are spliced into the parent object — so it needs no [JsonPropertyName]; the dictionary keys are runtime data, not member names, and renaming never touches them. And [JsonIgnore] members, by definition, are not serialized and carry no contract.

The real escape from reflection: the source generator

Everything above is about the reflection serializer reading a live property name. The source generator sidesteps the walk entirely. A [JsonSerializable] context generates serialization code at compile time, baking each JSON name into the generated metadata as a string constant and reading the property directly:

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(Order))]
internal partial class OrderJsonContext : JsonSerializerContext { }

var json = JsonSerializer.Serialize(order, OrderJsonContext.Default.Order);

The names are resolved before Nebula runs and frozen into the generated context as literals, so renaming the DTO afterwards cannot change what the generated code emits — it already knows which property "customer" means. (The generated OrderJsonContext type and its Default.Order entry point are referenced by your call sites and rename consistently with them, like any other internal link; only a reflective use of the context by name would be a separate dependency.) For a hot DTO you are obfuscating, the source generator is both the faster path and the one with the fewest name hazards — but you still attribute the names you care about, because the generator reads [JsonPropertyName] the same way reflection does.

Prove it with a round-trip on the protected build

[Fact]
public void Protected_build_round_trips_the_wire_contract()
{
    var order = new Order("Acme", 42.50m, new DateTime(2026, 10, 16));

    var json = JsonSerializer.Serialize(order);
    // The contract, asserted literally — these keys are what consumers depend on.
    Assert.Contains("\"customer\":\"Acme\"", json);
    Assert.Contains("\"total\":42.50", json);
    Assert.DoesNotContain("\"a\":", json);          // no leaked renamed member

    var back = JsonSerializer.Deserialize<Order>(json)!;
    Assert.Equal("Acme", back.Customer);            // constructor matched by name
    Assert.Equal(42.50m, back.Total);
}

Nebula.NET renames aggressively by design; the attributes above are how you keep the one name that has to stay while losing the ones that should go. For the broader pattern across reflection and serialization, see what obfuscation breaks.

What HTTP status does a failed license check deserve? 402, 403, Problem Details, and a header the client can read

Zero Heartbeat — Fri, 16 Oct 2026 13:55:38 +0000

A licensed service makes one decision on the way in — is this caller allowed to run right now? — and the HTTP response it sends when the answer is no is almost always an afterthought. The two common failures are a bare 500 with a stack trace (which tells the caller nothing and leaks your internals) and a 200 OK carrying { "ok": false } in the body (which no HTTP client, proxy or retry policy will ever notice, because as far as the stack is concerned the request succeeded). Between them sits a contract the gate actually owes its callers: the right status code, a machine-readable reason, and a header a client can branch on — without ever echoing the license key back.

This post builds that contract around a Keyright licence. The verification itself — checking the signature, the expiry, the machine binding — is covered elsewhere; here the licence has already been verified and reduced to a LicenseStatus, and the only question is how to turn that status into an HTTP response a CLI, a browser and a sister service can all handle correctly.

A license failure is not an authentication failure

The reflex is to reach for 401 Unauthorized, because the request was "rejected". That is the wrong axis. 401 means I do not know who you are; it is an authentication signal, and the spec requires it to carry a WWW-Authenticate header telling the client how to present credentials. A client that gets a 401 will re-authenticate — and if its credentials are valid, it will succeed, retry, and hit exactly the same wall. You have built a loop.

A licence failure is orthogonal to identity. The caller can be perfectly authenticated — a valid token, a known API key — and the thing that lapsed is the licence. The status code has to say "I know exactly who you are, and this is still not allowed," which is 403 Forbidden. That covers a revoked key, a machine mismatch, or a request for a feature the licence does not include.

There is one case where 403 undersells the situation. When the licence has simply expired — the subscription ran out — the remedy is not "ask an administrator for permission", it is "renew". For that, 402 Payment Required says more. It was marked reserved in the original HTTP spec, but it is passed through cleanly by every proxy and is widely used by subscription APIs today; the only rule is not to expect a browser to do anything magical with it. Emitting 402 lets a client distinguish a commercial wall from a permissions wall, which is precisely the distinction a licence gate exists to make.

The reason belongs in a problem+json body

A status code is a single number; a client that wants to show a useful message or branch on the specific reason needs structured detail. The standard shape for that is RFC 9457 — Problem Details for HTTP APIs, the successor to RFC 7807 — served as application/problem+json:

{
  "type": "https://delta1labs.com/problems/license-expired",
  "title": "License expired",
  "status": 402,
  "detail": "This license expired on 2026-09-30. Renew to continue.",
  "licenseStatus": "Expired",
  "expiresOn": "2026-09-30T00:00:00Z",
  "renewUrl": "https://delta1labs.com/account/renew",
  "traceId": "00-3f1a…-01"
}

The type URI is the contract. A client branches on it — a stable string you promise not to change — not on the human title, which you are free to reword or localise. The members below detail are extension members: RFC 9457 lets you add any JSON you like, and this is where the licence-specific facts go. licenseStatus mirrors Keyright's enum, expiresOn gives a CLI something to print, renewUrl gives a UI a button. What is not there is the key, the signature, or the licensee's email — the error body is the single most-copied artifact in a support flow, pasted into tickets and screenshots, so it is held to the same rule as a log line.

ASP.NET Core has first-class support for this. Register the services once:

builder.Services.AddProblemDetails();

AddProblemDetails() registers an IProblemDetailsService and wires the framework to emit application/problem+json for error responses automatically, including content negotiation.

The gate: an endpoint filter that maps status to response

The cleanest place to enforce the licence on a minimal API is an IEndpointFilter: it runs after model binding and authentication but before the handler, it has the HttpContext, and it can short-circuit by returning an IResult instead of calling next.

public sealed class LicenseGateFilter(ILicenseState license) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var status = license.Current;   // already-verified snapshot, not a fresh crypto check

        // Happy paths run the handler.
        if (status is LicenseStatus.Valid or LicenseStatus.ExpiringSoon)
        {
            if (status is LicenseStatus.ExpiringSoon)
                ctx.HttpContext.Response.Headers["Keyright-License"] = "warning; reason=expiring-soon";
            return await next(ctx);
        }

        // Everything else short-circuits with a problem+json response.
        var (code, type, title, detail) = Map(status, license);
        if (status is LicenseStatus.ServerUnavailable)
            ctx.HttpContext.Response.Headers.RetryAfter = "30";

        ctx.HttpContext.Response.Headers["Keyright-License"] = $"blocked; status={status}";

        return Results.Problem(
            statusCode: code,
            type: type,
            title: title,
            detail: detail,
            extensions: new Dictionary<string, object?>
            {
                ["licenseStatus"] = status.ToString(),
                ["expiresOn"]     = license.ExpiresOn,     // null for non-expiry failures
                ["renewUrl"]      = code == 402 ? "https://delta1labs.com/account/renew" : null,
            });
    }

    private static (int, string, string, string) Map(LicenseStatus s, ILicenseState l) => s switch
    {
        LicenseStatus.Expired           => (402, "https://delta1labs.com/problems/license-expired",
                                            "License expired", $"This license expired on {l.ExpiresOn:yyyy-MM-dd}. Renew to continue."),
        LicenseStatus.Revoked           => (403, "https://delta1labs.com/problems/license-revoked",
                                            "License revoked", "This license has been revoked. Contact your administrator."),
        LicenseStatus.MachineMismatch   => (403, "https://delta1labs.com/problems/machine-mismatch",
                                            "License not valid on this machine", "This license is bound to a different machine."),
        LicenseStatus.EntitlementMissing=> (403, "https://delta1labs.com/problems/entitlement-missing",
                                            "Feature not licensed", "Your license does not include this feature."),
        LicenseStatus.SignatureInvalid  => (403, "https://delta1labs.com/problems/license-invalid",
                                            "License invalid", "The license could not be verified."),
        LicenseStatus.ServerUnavailable => (503, "https://delta1labs.com/problems/license-unavailable",
                                            "License service unavailable", "Could not reach the license service. Please retry shortly."),
        _                               => (403, "https://delta1labs.com/problems/license-invalid",
                                            "License invalid", "The license could not be verified."),
    };
}

Attach it to the endpoints — or a whole group — that the licence protects:

var pro = app.MapGroup("/api/pro").AddEndpointFilter<LicenseGateFilter>();
pro.MapPost("/export", (ExportRequest r) => Export(r));

Two deliberate choices. First, license.Current reads an already-verified snapshot — the filter never re-runs a signature check per request, so the gate adds a dictionary lookup, not cryptography, to the hot path. Second, the Keyright-License response header carries the machine-readable state even on the happy path (as a warning for an expiring licence), so a sister service or a CLI can react — renew, warn, back off — by reading one header instead of parsing the body. It carries the status, never the key.

4xx is you, 5xx is us

The split between ServerUnavailable → 503 + Retry-After and the 4xx family is what makes a generic HTTP client behave. A 402 or 403 is a definite, client-caused answer: it will not change on retry, there is no Retry-After, and a well-behaved client surfaces it to a human. A 503 with Retry-After: 30 is the opposite — not now, ask again — and a standard retry policy (Polly, HttpClient resilience) will back off and retry it automatically while leaving the 4xx alone. The grace logic that decides how long the app keeps serving while the licence service is unreachable lives behind the gate; the gate only reports the state it is handed.

The test: assert the status, the type, and the absent key

A gate like this earns a WebApplicationFactory test that pins all three parts of the contract — the status code, the problem type, and the one thing that must never be in the body.

[Fact]
public async Task Expired_license_returns_402_problem_and_never_the_key()
{
    await using var app = new LicensedAppFactory(LicenseStatus.Expired, key: "KR-SECRET-KEY-DO-NOT-LEAK");
    var client = app.CreateClient();

    var res = await client.PostAsJsonAsync("/api/pro/export", new { format = "csv" });

    Assert.Equal(HttpStatusCode.PaymentRequired, res.StatusCode);          // 402
    Assert.Equal("application/problem+json", res.Content.Headers.ContentType!.MediaType);

    var body = await res.Content.ReadAsStringAsync();
    using var doc = JsonDocument.Parse(body);
    Assert.Equal("https://delta1labs.com/problems/license-expired",
        doc.RootElement.GetProperty("type").GetString());
    Assert.Equal("Expired", doc.RootElement.GetProperty("licenseStatus").GetString());

    // The bearer credential must never appear in an error the client can copy.
    Assert.DoesNotContain("KR-SECRET-KEY-DO-NOT-LEAK", body);
    Assert.Equal("blocked; status=Expired", res.Headers.GetValues("Keyright-License").Single());
}

That last assertion is the one worth keeping forever. Status codes and problem types are a contract you can evolve; a leaked key in an error body is a credential disclosure that will sit in a support ticket for years. A licence gate's job is to say no clearly — to the HTTP stack, to the client's retry policy, and to the human reading the message — while giving away nothing a reader did not already have.

If you are wiring licence verification into a .NET service, Keyright hands you the verified LicenseStatus; the HTTP contract above is how you make it legible to everything downstream.

Decompiling a decimal constant: why 3.14m is not an IL constant, and the [DecimalConstant] attribute that rebuilds it

Zero Heartbeat — Fri, 16 Oct 2026 13:53:24 +0000

Take the most ordinary line of C# imaginable:

public const decimal TaxRate = 0.075m;

Compile it, open the assembly, and look for where 0.075 is stored. It is not in the IL — there is no ldc instruction for it. It is not in the metadata Constant table, where const int and default parameter values live. The number has, apparently, vanished. It hasn't: it has been dismantled into five integers and tucked into an attribute, and a decompiler that doesn't know to look there will render your tax rate as a pile of constructor arguments. This is the one numeric literal in C# that a decompiler has to reconstruct rather than read, and the mechanism is worth seeing in full.

Why `decimal` has nowhere to live

Every other numeric literal has a native home. A const int or a default int parameter is written into the Constant metadata table, whose blob format defines an encoding for each primitive element type — ELEMENT_TYPE_I4, ELEMENT_TYPE_R8, ELEMENT_TYPE_STRING, and so on. A literal in a method body becomes an instruction: ldc.i4 42, ldc.r8 3.14. Both channels share one assumption — that the value is a type the CLR represents natively.

decimal is not. System.Decimal is a 128-bit struct defined in the class library, built from a 96-bit integer plus a scale and a sign. The CLR has no load opcode for it and the Constant blob format has no element type for it. So when the language says "this decimal is a constant", there is no metadata slot that can hold the answer. The compiler has to encode the value some other way — and the way it chose is System.Runtime.CompilerServices.DecimalConstantAttribute.

The attribute is the number

Here is the field above as the compiler emits it, in IL:

.field public static initonly valuetype [System.Runtime]System.Decimal TaxRate
  .custom instance void [System.Runtime]System.Runtime.CompilerServices.DecimalConstantAttribute::.ctor(
      uint8, uint8, uint32, uint32, uint32) = ( 01 00 03 00 00 00 00 00 00 00 00 00 4B 00 00 00 00 00 )

Those five constructor arguments are not metadata about the number — they are the number, in exactly the pieces System.Decimal is assembled from. The constructor signature is (byte scale, byte sign, uint hi, uint mid, uint low):

scale = 3 — the number of digits after the decimal point (divide the integer by 10³).
sign = 0 — positive (1 would mean negative).
hi / mid / low = 0 / 0 / 75 — the three 32-bit words of the 96-bit unscaled integer; here just 75 in the low word.

Put together: the unscaled integer 75, scaled by 10⁻³, positive → 0.075. The decompiler runs the same arithmetic the runtime's decimal(int lo, int mid, int hi, bool isNegative, byte scale) constructor would, and recovers the literal 0.075m. Nothing is rounded and nothing is lost — the attribute is a complete, exact description of the value.

A `const decimal` has no initializer — on purpose

There is a second surprise waiting for a decompiler that only reads method bodies. You might expect const decimal TaxRate = 0.075m to compile to a store in the static constructor — .cctor assigns the field — but it does not. const in C# means compile-time constant: the value has to be usable in other constant contexts, so the compiler cannot implement it by running code at type-init time (that would make it readonly, not const). Instead:

the field is emitted as a static initonly field carrying the [DecimalConstant] attribute, and
every use of TaxRate in source is replaced, at compile time, by the reconstructed value inlined at the call site.

So the .cctor is empty of any store to TaxRate, and there is no instance initializer. A decompiler that walks constructors looking for the field's value finds nothing and would wrongly report the field as uninitialized. The value is in the attribute, and recovering the original declaration means reading it from there — then presenting the field as const, not static readonly, because the initonly flag plus the [DecimalConstant] attribute together are the signature of a const decimal.

A default `decimal` parameter takes a different road than a default `int`

The same gap reshapes optional parameters. Compare:

void A(int    rate = 5)      { }
void B(decimal rate = 0.075m) { }

For A, the default 5 goes into the Constant table and the parameter gets the HasDefault flag; a decompiler reads the Constant blob and writes = 5. For B, the Constant table can't hold a decimal, so the compiler marks the parameter [opt] (the Optional flag) without a HasDefault entry, and attaches [DecimalConstant(3, 0, 0, 0, 75)] to the parameter:

.method ... void B(valuetype System.Decimal rate)
{
  .param [1]
    .custom instance void ...DecimalConstantAttribute::.ctor(uint8,uint8,uint32,uint32,uint32)
      = ( 01 00 03 00 00 00 00 00 00 00 00 00 4B 00 00 00 00 00 )
}

A decompiler recovering default values therefore needs two code paths: read the Constant table for the primitives, and check for [DecimalConstant] on the parameter for decimal. Honour only the Constant table and the decimal default disappears — the parameter renders as having none. Worse, a decompiler that treats [DecimalConstant] as an ordinary custom attribute will print it literally into the source:

// WRONG — the attribute is an encoding, not something the author wrote:
void B([DecimalConstant(3, 0, 0, 0, 75)] decimal rate) { }

That line never existed in the original code. The attribute is the compiler's private encoding of = 0.075m, and a faithful decompiler consumes it and renders the thing the programmer actually typed.

Why Glass treats it as a value, not an annotation

The rule a decompiler has to encode is: [DecimalConstant] is never shown — it is always consumed. Wherever it appears — on a const field, a static readonly field initialised from a constant, or an optional parameter — Glass.NET reads the five arguments, reassembles the System.Decimal, and emits the literal the author wrote: const decimal TaxRate = 0.075m;, decimal rate = 0.075m. The attribute itself is suppressed, exactly as the [Extension] attribute on an extension method or the [IsReadOnly] modreq on a readonly struct is suppressed — these are the compiler's bookkeeping, not the source.

It is a small feature with an outsized failure mode. Get it wrong and every monetary constant, tax rate and threshold in a decompiled financial app comes back as new decimal(75, 0, 0, false, 3) or, worse, as an attribute the programmer never wrote — technically correct, humanly unreadable. Get it right and 0.075m reads back as 0.075m, which, for the one numeric type that has no native home in the metadata, is the whole job.

See how Glass handles the other values the compiler hides in metadata rather than IL in decompiling optional and named arguments and decompiling an array initializer.

Obfuscating a COM-visible .NET assembly: the GUID is the contract, the DispId is the contract, and the class name is the ProgID unless you pin it

Zero Heartbeat — Fri, 16 Oct 2026 07:59:57 +0000

A COM-visible .NET assembly is a strange thing to obfuscate because its most important consumer does not know it is .NET. A VBA macro, a VBScript in a scheduled task, a twenty-year-old C++ host — they reach your assembly through COM, and the contract they bind to is not the public C# API a developer would protect. It is three pieces of metadata living in three different places: a GUID on the class and the interface, a DispId on each member, and a ProgID that, unless you say otherwise, is just your type's namespace-qualified name. Obfuscate it like an ordinary library and the GUIDs come through untouched — but the ProgID moves the instant you rename the class, and a late-bound client breaks on both the moved ProgID and the renamed member names.

This post reads what a COM client resolves at each hop, draws the line for Nebula, and shows the layout that keeps the pinned surface tiny.

The assembly as COM sees it

Here is the shape most COM-visible components ship — an explicit IDispatch interface and a coclass that implements it:

using System.Runtime.InteropServices;
using Acme.Automation.Engine;   // the real logic — renames wholesale

namespace Acme.Automation;

[ComVisible(true)]
[Guid("8d9b3a2e-6c41-4f7a-9b21-2f0c7e5a1d44")]                 // IID — pinned, survives anyway
[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface IWidget
{
    [DispId(1)] string Caption { get; set; }                  // member name + DispId = contract
    [DispId(2)] int    Resize(int width, int height);
}

[ComVisible(true)]
[Guid("1f6e0c74-3a8b-4d2e-8c15-9a7b4e3f0c21")]                 // CLSID — pinned, survives anyway
[ClassInterface(ClassInterfaceType.None)]                     // no autogenerated interface
[ProgId("Acme.Automation.Widget")]                            // pin the ProgID — see below
public sealed class Widget : IWidget
{
    private readonly WidgetEngine _engine = WidgetEngine.Open();   // private: renames freely

    public string Caption { get => _engine.Caption; set => _engine.Caption = value; }
    public int Resize(int width, int height) => _engine.Resize(width, height);
}

Registration turns that into registry entries with regasm:

regasm Acme.Automation.dll /tlb:Acme.Automation.tlb /codebase

regasm writes three things that matter: a ProgID → CLSID mapping, a CLSID → assembly mapping, and (with /tlb) a type library describing the interface. Every one of those is keyed by the GUIDs, which is why they survive renaming — an attribute GUID is a string constant, and renaming never touches a constant. The parts that are not keyed by GUID are the ProgID and the member names, and those are the whole job.

How a late-bound client binds — and where it breaks

Walk a script through the hops. CreateObject("Acme.Automation.Widget") does this:

Look up the ProgID Acme.Automation.Widget in the registry → get a CLSID (the coclass GUID).
Instantiate the CLSID → get an IDispatch pointer.
For each call, GetIDsOfNames("Resize") → a DispId; then Invoke(dispId, args).

Three name-based lookups, and obfuscation can poison two of them. The ProgID in step 1 defaults to the type's namespace-qualified name — Acme.Automation.Widget. Rename the class to a and the namespace to b, and regasm would now register b.a; the script still asks for Acme.Automation.Widget, finds nothing, and dies with ActiveX component can't create object. The member name in step 3 is your CLR method name; rename Resize to a and GetIDsOfNames("Resize") returns DISP_E_UNKNOWNNAME — a run-time failure with no build error, exactly like a renamed PowerShell parameter.

The layout that shrinks the pinned surface

Two moves make most of the assembly rename freely.

Pin the ProgID with [ProgId]. The default ProgID is the type's namespace-qualified name, which chains the client's CreateObject string to a name you want to obfuscate. Put [ProgId("Acme.Automation.Widget")] on the coclass — as in the sample above — and the ProgID becomes a pinned attribute constant that no longer depends on the class name. Now Nebula can rename Widget to anything and the namespace with it; regasm reads the ProgID off the attribute, and the script's CreateObject still resolves.

Put the contract on an explicit interface, the logic in an engine. With [ClassInterface(ClassInterfaceType.None)], COM sees only the members of IWidget — so the only member names that are contract are the interface's. The coclass can hold private fields and helpers that rename freely, and the real work lives in a separate Acme.Automation.Engine namespace with no COM attributes at all, which renames, string-encrypts and control-flow-flattens like any other library:

// Acme.Automation.Engine — no COM, no public contract, renames wholesale.
namespace Acme.Automation.Engine;

internal sealed class WidgetEngine
{
    internal static WidgetEngine Open() { /* licensing gate, state load */ }
    internal string Caption { get; set; } = "";
    internal int Resize(int width, int height) { /* the real algorithm */ }
}

The kept surface is now exactly: the interface member names, their DispIds, the two GUIDs, and the ProgID string. Everything worth protecting is on the other side of the interface.

The config

Keep the interface by name (so its member names survive), keep the coclass type if you rely on the default ProgID — but with [ProgId] pinned you can rename it — preserve the interop attributes, and rename everything else:

{
  "inputs": [ "bin/Release/net48/Acme.Automation.dll" ],
  "outputDirectory": "protected",

  "preservePublicApi": false,
  "encryptStrings": true,
  "controlFlowObfuscation": true,

  "renaming": {
    "rules": [
      { "pattern": "Acme.Automation.IWidget", "action": "keep"   },
      { "pattern": "Acme.Automation.Widget",  "action": "rename" },
      { "pattern": "Acme.Automation.Engine.*", "action": "rename" }
    ],
    "preserveAttributes": [ "System.Runtime.InteropServices.*" ]
  },

  "controlFlow": { "exclude": [ "Acme.Automation.IWidget" ] }
}

Three notes. The keep rule is on the interface, not the coclass — the interface member names are what late binding resolves, and keeping the interface keeps Caption and Resize. The coclass is set to rename deliberately, which is only safe because [ProgId] is pinned; drop that attribute and you must change this rule to keep or CreateObject breaks. preserveAttributes guards [Guid], [DispId], [ComVisible], [InterfaceType], [ClassInterface] and [ProgId] against any attribute-stripping pass — losing [ComVisible] makes the type invisible to regasm with no error, and losing [DispId] makes the members renumber, which silently reorders an early-bound client's vtable. String encryption is safe throughout: the ProgID and GUID are attribute arguments and are not touched, and GetIDsOfNames reflects on the real member names in metadata, not on any string literal.

Verify by registering and calling — in both binding styles

Every failure here is a run-time bind miss, so register the protected assembly and exercise it both ways. Late-bound, through the ProgID and IDispatch names:

' late-bound.vbs — exercises the ProgID (step 1) and member names (step 3)
Set w = CreateObject("Acme.Automation.Widget")   ' ProgID must still resolve
w.Caption = "Report"                             ' GetIDsOfNames("Caption")
WScript.Echo w.Resize(800, 600)                  ' GetIDsOfNames("Resize")

Early-bound, through the type library — this exercises the GUIDs and the DispIds, binding by vtable with no names at run time:

// Reference the generated interop (tlbimp / COM reference), then:
var w = new Acme.Automation.Widget();            // CLSID GUID
w.Caption = "Report";                            // DispId 1 via vtable
int h = w.Resize(800, 600);                      // DispId 2 via vtable

Register the protected DLL with regasm protected\Acme.Automation.dll /tlb /codebase, run both clients in the bitness you ship (a 32-bit host needs the 32-bit regasm and the 32-bit registry view), and unregister with regasm /u afterwards so you are never testing against stale entries. If the assembly is strong-named, re-sign after obfuscation. An assembly that merely registers is not proven; one that CreateObjects and dispatches in both styles is.

The takeaway

A COM-visible assembly's contract is not its C# surface. The GUIDs on the class and interface survive obfuscation because they are attribute constants, and the registry is keyed by them — that much is free. What is not free is the ProgID, which defaults to the namespace-qualified class name and therefore moves the moment you rename the class, and the member names a late-bound IDispatch client passes to GetIDsOfNames, which are your CLR method and property names. Pin the ProgID with [ProgId] so the class can rename, keep the interface so its member names survive, pin the DispIds so early-bound vtables never renumber, preserve the InteropServices attributes, and push the real work into an engine namespace that renames wholesale. Then prove it by registering the protected assembly and calling it both late-bound through the ProgID and early-bound through the type library — because the build will not tell you which name you broke.

Obfuscating an app that registers itself by convention: assembly-scanning DI binds on type names, so renaming unregisters your services

Zero Heartbeat — Fri, 16 Oct 2026 07:59:49 +0000

A great many .NET applications never actually write down their service registrations. They scan. At startup an app sweeps an assembly, finds every type that looks like a service — by a naming convention, usually — and registers it. Scrutor made this a one-liner, and hand-rolled reflection loops did it long before that. It is tidy, it is convention-over-configuration, and it has a specific, quiet failure mode under obfuscation: the convention is almost always a string match against the type name, and renaming changes every name.

The result is the worst shape a bug can take. The build is green — the scan is valid code. The app starts — the scan runs without error. And then the first request asks the container for IOrderService, the container has never heard of it, and you get Unable to resolve service for type 'IOrderService' pointing at the controller, nowhere near the scan that silently registered nothing. This post is about why that happens for Nebula, and the one-line change that makes it stop.

The registration that breaks

Here is the shape that gets written most often — scan the assembly, take everything whose name ends in a convention word, register it against its interfaces:

builder.Services.Scan(scan => scan
    .FromAssemblyOf<OrderService>()
    .AddClasses(c => c.Where(t => t.Name.EndsWith("Service")))   // <-- string match on the name
        .AsImplementedInterfaces()
        .WithScopedLifetime());

Read what that predicate actually does: at startup it enumerates the assembly's types and keeps the ones whose Name ends in the seven characters S-e-r-v-i-c-e. Before obfuscation that is OrderService, PricingService, InventoryService. After Nebula renames them to a, b, c, the predicate asks each of them "does your name end in 'Service'?" and each answers no. The scan keeps zero types, AsImplementedInterfaces has nothing to bind, and IOrderService is never registered.

Nothing in that is a bug the compiler or the obfuscator could catch. The predicate is valid. The rename did exactly what it was told. The two facts are simply incompatible, and the incompatibility only becomes visible when something tries to resolve a service that the empty scan never added.

The distinction that matters: name vs shape

Not every scan breaks. The difference is whether the scan finds a type by its name or by its shape, and that line is the whole of it. A name is a string that renaming rewrites — and the string literal in your predicate does not get rewritten with it, so the comparison goes stale. A shape — implements this interface, carries this attribute, derives from this base — is a relationship in the metadata graph, and renaming is a consistent rewrite of that graph: it renames the interface and the implementing type together, so "implements" still holds.

// SURVIVES — matches on the implements-relationship, a metadata token identity
.AddClasses(c => c.AssignableTo<ICommandHandler>())

// SURVIVES — matches on an attribute type token; renaming keeps attribute and target in sync
.AddClasses(c => c.WithAttribute<ServiceAttribute>())

// BREAKS — matches on a frozen string the rename cannot reach
.AddClasses(c => c.Where(t => t.Name.EndsWith("Handler")))

// BREAKS WORSE — resolves a type from a name string that no longer names anything
.AddSingleton(Type.GetType("Acme.Orders.OrderService")!)

The fix is one line, and it buys back the names

Give the convention a marker and scan for that instead of for the spelling. A marker interface is the cleanest, because it costs nothing at run time and says exactly what the convention meant:

public interface IAppService { }                    // marker; renaming keeps it resolvable by token

public sealed class OrderService : IAppService, IOrderService { /* ... */ }

builder.Services.Scan(scan => scan
    .FromAssemblyOf<OrderService>()
    .AddClasses(c => c.AssignableTo<IAppService>())  // <-- shape, not name
        .AsImplementedInterfaces()
        .WithScopedLifetime());

Now the scan asks each type "do you implement IAppService?", which the metadata answers correctly before and after obfuscation. Nebula is free to rename OrderService, IOrderService and every other type in the layer, because the scan no longer reads a single name — the only thing it depends on is the implements relationship, and renaming preserves that by construction. You get the obfuscation you wanted and the convention registration you wanted, with no overlap between them.

An attribute works identically if you prefer not to add an interface to the type's hierarchy:

[Service(ServiceLifetime.Scoped)]
public sealed class PricingService : IPricingService { /* ... */ }

.AddClasses(c => c.WithAttribute<ServiceAttribute>())

The attribute is matched by its type token, which the rename keeps consistent on the attribute class and on every type decorated with it.

When you cannot change the scan

Sometimes the scan is in a library you do not own, and it filters on a name you cannot influence. The escape hatch is to keep the names the scan relies on — but keep them narrowly, and understand the cost. A Nebula config excludes just the convention-named types from renaming:

{
  "inputs": [ "bin/Release/net8.0/Acme.Orders.dll" ],
  "outputDirectory": "protected",

  "encryptStrings": true,
  "controlFlowObfuscation": true,

  "renaming": {
    "rules": [
      { "pattern": "*Service",    "action": "keep"   },
      { "pattern": "*Handler",    "action": "keep"   },
      { "pattern": "*Repository", "action": "keep"   },
      { "pattern": "Acme.Orders.*", "action": "rename" }
    ]
  }
}

Be clear-eyed about the trade: every keep rule here leaves a class name in the metadata, and the set of names you are exposing is precisely your service layer — the map of what the app does. The earlier the rule sits, the more it wins over the broad rename, so a *Service keep pins every service's name. That is why the refactor is the better answer whenever the scan is yours: switching one predicate from Name.EndsWith to AssignableTo turns the whole keep block back into rename and hands the names back to the obfuscator. Use the exclude only for the third-party scan you genuinely cannot reach.

Fail fast instead of at the first request

The reason this bug is expensive is distance — the empty scan and the failed resolution are far apart. Close the distance with a startup smoke test that asserts the services you expect are actually registered, and run it against the obfuscated build, because that is the only build where the scan can come up empty:

[Fact]
public void Expected_services_are_registered_after_scanning()
{
    using var provider = BuildProductionServiceProvider();   // same Scan(...) as the app

    // Resolve the way the app will — if the scan registered nothing, this throws here,
    // in a test, instead of on the first production request.
    Assert.NotNull(provider.GetService<IOrderService>());
    Assert.NotNull(provider.GetService<IPricingService>());

    // Or assert the count the convention should have produced:
    var handlers = provider.GetServices<ICommandHandler>().ToList();
    Assert.Equal(expected: 7, handlers.Count);
}

BuildServiceProvider(validateOnBuild: true) will not catch this on its own — it validates that the registrations present can be constructed, and a missing registration is simply absent, not invalid. You have to assert the presence of what the scan should have found. Run this test over the protected assembly in CI and a scan that renaming emptied turns red in the build, which is exactly where you want it, rather than in a production stack trace that blames the controller.

The takeaway

Convention-based DI registration is a string match against type names far more often than it looks, and renaming obfuscation changes every one of those names while leaving the string literal in your predicate frozen — so the scan quietly registers nothing and the app fails at the first resolution, a green build away from the cause. The fix is to make the scan match on shape rather than spelling: AssignableTo a marker interface or WithAttribute a marker attribute, both of which renaming rewrites consistently across the metadata graph, so the scan keeps finding your types no matter what they are called. That one change lets Nebula rename your entire service layer — the names you obfuscated to hide — while the registration keeps working. When the scan is not yours to change, pin just the convention-named types with narrow keep rules and accept that you are leaving those names visible. Either way, prove it with a startup test that resolves the expected services against the obfuscated build, so an emptied scan fails in CI and never in production.

Logging a license check: structured events an operator can read, and never the key itself

Zero Heartbeat — Fri, 16 Oct 2026 07:59:02 +0000

A license check is the single event that decides whether your software is allowed to run tonight, and it is almost always logged in one of two wrong ways. Either it is logged as nothing — the verification happens, succeeds or fails silently, and the first anyone hears of a lapsed key is a user complaint — or it is logged as a disaster: log.LogInformation("license: {@License}", info), which serialises the whole object and writes the signed key, the raw signature and the licensee's email into a file that will be shipped to an aggregator and pasted into a support ticket by lunchtime.

This post builds the version in between: one structured, queryable event per verification, emitted so that an operator can read it, alert on it, and correlate it — and so that the key itself never leaves the process. It is about logging a Keyright verification the way you would log an auth event, because that is what it is.

The thing you are verifying

Keyright's Validate() returns a LicenseInfo with a Status, a Licensee, an expiry and the derived DaysRemaining/IsExpiringSoon that the renewal and health-check work already lean on:

LicenseInfo info = client.Validate(licenseKey);
// info.Status        -> LicenseStatus (Valid, Expired, Revoked, SignatureInvalid, ...)
// info.Licensee      -> "Acme GmbH"
// info.ExpiryUtc     -> DateTime?
// info.DaysRemaining -> int
// info.IsExpiringSoon-> bool

The licenseKey in that call is the thing that must never reach the log. Everything else on info is fair to record; the key and the signature are not. So the first design decision is to compute a fingerprint of the key once, and pass that to the logger — never the key.

using System.Security.Cryptography;
using System.Text;

static string Fingerprint(string licenseKey)
{
    // A stable, non-reversible handle: first 8 hex of SHA-256 over the key.
    // Enough to say "same key as the one in the ticket?" — not enough to be the key.
    Span<byte> hash = stackalloc byte[32];
    SHA256.HashData(Encoding.UTF8.GetBytes(licenseKey), hash);
    return Convert.ToHexString(hash)[..8].ToLowerInvariant();   // e.g. "9f3a1c20"
}

If your payload carries a key-id claim, prefer that — it is already a non-secret handle. The fingerprint is the fallback for keys that do not.

One event, declared once

The redaction rule is only as good as the number of places it has to hold. Spread the logging across a dozen log.LogInformation("...") call sites and the one that passes licenseKey instead of fingerprint is the leak. So declare the event once, as a source-generated LoggerMessage, whose signature makes the raw key unpassable:

using Microsoft.Extensions.Logging;

public static partial class LicenseLog
{
    // Note the parameters: fingerprint, status, licensee, days — never the key.
    [LoggerMessage(
        EventId = 4000, Level = LogLevel.Information,
        Message = "License verified: {Status} for {Licensee} (key {Fingerprint}), {DaysRemaining} day(s) remaining")]
    public static partial void Verified(
        this ILogger logger,
        string status, string licensee, string fingerprint, int daysRemaining);

    [LoggerMessage(
        EventId = 4001, Level = LogLevel.Warning,
        Message = "License expiring: {Status} for {Licensee} (key {Fingerprint}) expires in {DaysRemaining} day(s)")]
    public static partial void Expiring(
        this ILogger logger,
        string status, string licensee, string fingerprint, int daysRemaining);

    [LoggerMessage(
        EventId = 4002, Level = LogLevel.Error,
        Message = "License invalid: {Status} for {Licensee} (key {Fingerprint})")]
    public static partial void Invalid(
        this ILogger logger,
        string status, string licensee, string fingerprint);
}

The source generator turns each of these into a zero-allocation method that checks the level, writes the named fields and formats the message only if a sink wants it. There is no licenseKey parameter on any of them, so a caller cannot log the key through this type even by accident — the compiler stops them. That is the whole reason to prefer the generator over a free-form template: the rule is now a method signature, not a code-review convention.

Mapping status to level

The dispatch from LicenseStatus to one of those three events is the translation table, and it lines up with how alerting already works — Information is quiet, Warning is noticed, Error is counted and paged:

public static void LogLicense(this ILogger logger, LicenseInfo info, string fingerprint)
{
    string status   = info.Status.ToString();
    string licensee  = info.Licensee ?? "(none)";

    switch (info.Status)
    {
        case LicenseStatus.Valid when info.IsExpiringSoon:
            logger.Expiring(status, licensee, fingerprint, info.DaysRemaining);
            break;
        case LicenseStatus.Valid:
            logger.Verified(status, licensee, fingerprint, info.DaysRemaining);
            break;
        default:   // Expired, Revoked, SignatureInvalid, MachineMismatch, ClockTampered, NoLicense
            logger.Invalid(status, licensee, fingerprint);
            break;
    }
}

A JSON console sink then renders the healthy case like this — note that the key is nowhere in it, only its fingerprint:

{
  "Timestamp": "2026-10-16T09:00:01.42Z",
  "LogLevel": "Information",
  "EventId": 4000,
  "Message": "License verified: Valid for Acme GmbH (key 9f3a1c20), 48 day(s) remaining",
  "State": { "Status": "Valid", "Licensee": "Acme GmbH", "Fingerprint": "9f3a1c20", "DaysRemaining": 48 }
}

Because Status, Fingerprint and DaysRemaining are named structured fields and not just text baked into the message, a log backend can graph "distinct fingerprints seen this week" or alert on "EventId 4002 count > 0" without parsing the message string. That is the dividend of the structured form: the event is queryable, not just readable.

A scope so the rest of the logs correlate

The verification is one line, but the work that follows it — a background lease renewal, an entitlement check, a feature gate — produces its own logs, and an incident reviewer wants to tie them to the license that was in force. Open a logging scope keyed by the fingerprint around that work, and every line inside it carries the field automatically:

using (logger.BeginScope(new Dictionary<string, object> { ["LicenseKey"] = fingerprint }))
{
    logger.LogLicense(info, fingerprint);
    // ... anything logged in here also carries LicenseKey=9f3a1c20 ...
}

Now a SignatureInvalid at 03:00 and a failed entitlement check at 03:01 share a LicenseKey field, and the reviewer can pull the whole story with one filter. The scope carries the fingerprint, never the key — the same rule, applied to the correlation handle.

Prove the key never escapes

The one assertion worth writing is the negative one: that the raw key does not appear in anything the logger emits. Microsoft.Extensions.Diagnostics.Testing ships a FakeLogger that captures records in memory, so the test is direct:

[Fact]
public void Verification_never_logs_the_raw_key()
{
    var fake = new FakeLogger<LicenseService>();
    const string key = "KR1-REALKEY-abcdef ...";          // the actual signed key
    var info = new LicenseInfo { Status = LicenseStatus.Valid, Licensee = "Acme", DaysRemaining = 48 };

    fake.LogLicense(info, Fingerprint(key));

    foreach (FakeLogRecord rec in fake.Collector.GetSnapshot())
    {
        Assert.DoesNotContain(key, rec.Message);
        foreach (var kv in rec.StructuredState ?? [])
            Assert.DoesNotContain(key, kv.Value ?? "");    // check the structured fields too
    }
}

Assert on both the rendered message and the structured state, because a leak can hide in either — a stray {Key} in a template shows up in the message, a BeginScope that captured the key shows up in the state. This test is the thing that keeps the rule true as the code grows: the day someone adds a fourth event that passes the key, it goes red.

The takeaway

A license check deserves to be logged like the auth event it is: one structured record, not silence and not a data dump. Declare the event once as a source-generated LoggerMessage whose parameters are a fingerprint and the non-secret fields, so the raw key is unpassable by construction. Map LicenseStatus onto levels that your existing alerting already understands — Information for valid, Warning for expiring, Error for invalid — and give each a stable EventId so a dashboard counts failures without string-matching. Emit it on verification and on transitions, not on every request. Wrap the work in a scope keyed by the fingerprint so the rest of the logs correlate. Then write the one test that proves the key never reaches the sink, and let it guard the rule forever. The result is a log an operator can read, a backend can query, and a support ticket can safely carry — because the one thing that must not travel never made it past the first line.

DEV Community: Zero Heartbeat

Decompiling C# expression trees: the lambda that became a tree of factory calls

Same lambda, two compilations

Members are reached by token, not by name

Captured variables: a Constant that is not constant

Conversions, checked arithmetic and boxing

Nested lambdas and Expression.Quote

Object creation, initializers and anonymous types

What the tree cannot tell you

What a decompiler folds, and what it shows

Obfuscating a type you serialize with Newtonsoft.Json: [JsonProperty] is the contract, and TypeNameHandling''s $type is a landmine

Why the rename reaches the wire

The fix is [JsonProperty], not a keep rule

The constructor is a second name binding

Enums serialize by their member name too

The bigger trap: TypeNameHandling writes your type's name into the document

Prove it with a round-trip on the protected build

Decompiling C# string interpolation and interpolated string handlers

Three lowerings, one syntax

The concat shortcut

The format template

The handler dance

Alignment, format, and the culture trap

Custom handlers: when the string is never built

Constant interpolation disappears entirely

What to take from the decompiled view

Obfuscating code that uses dynamic: the runtime binder looks members up by name, so a renamed property is a RuntimeBinderException

Where the name lives

Why string encryption is beside the point

Which operations bind by name

The pattern that breaks a whole visitor at once

Fixes, in order of preference

The test that catches it

Site licenses: binding one Keyright key to the customer''s domain instead of a machine, and what that binding can and cannot prove

What the key says

Where the machine's identity comes from

The gate

Getting the values from the customer

What the binding proves — honestly

Tests: a fake site, three machines

Rolling it out

Decompiling nullable value types: int? is a struct, a lifted operator is a HasValue check, and the box that erases Nullable

int? is in the signature blob, not in an attribute

Lifted arithmetic: a conjunction, two GetValueOrDefaults, and a newobj

Lifted equality is a different shape

== null, ??, and the pattern is int v

The box that erases Nullable<T>

What a decompiler gets wrong, and why it matters

Obfuscating a type you serialize with System.Text.Json: [JsonPropertyName] is the contract, the renamed property is not

Why the rename reaches the wire

The fix is an attribute, not a keep rule

The constructor is a second name binding

Enums, extension data, and the members that don't bind by name

The real escape from reflection: the source generator

Prove it with a round-trip on the protected build

What HTTP status does a failed license check deserve? 402, 403, Problem Details, and a header the client can read

A license failure is not an authentication failure

The reason belongs in a problem+json body

The gate: an endpoint filter that maps status to response

4xx is you, 5xx is us

The test: assert the status, the type, and the absent key

Decompiling a decimal constant: why 3.14m is not an IL constant, and the [DecimalConstant] attribute that rebuilds it

Why decimal has nowhere to live

The attribute is the number

A const decimal has no initializer — on purpose

A default decimal parameter takes a different road than a default int

Why Glass treats it as a value, not an annotation

Obfuscating a COM-visible .NET assembly: the GUID is the contract, the DispId is the contract, and the class name is the ProgID unless you pin it

The assembly as COM sees it

How a late-bound client binds — and where it breaks

The layout that shrinks the pinned surface

The config

Verify by registering and calling — in both binding styles

The takeaway

Obfuscating an app that registers itself by convention: assembly-scanning DI binds on type names, so renaming unregisters your services

The registration that breaks

The distinction that matters: name vs shape

The fix is one line, and it buys back the names

When you cannot change the scan

Fail fast instead of at the first request

`int?` is in the signature blob, not in an attribute

Lifted arithmetic: a conjunction, two `GetValueOrDefault`s, and a `newobj`

`== null`, `??`, and the pattern `is int v`

The box that erases `Nullable<T>`

Why `decimal` has nowhere to live

A `const decimal` has no initializer — on purpose

A default `decimal` parameter takes a different road than a default `int`