Class MessageContextPropagationExtensions
Carries named values beyond the process boundary, alongside a message.
public static class MessageContextPropagationExtensions
- Inheritance
-
MessageContextPropagationExtensions
- Inherited Members
Remarks
Items is request-local: nothing in this framework serializes it, persists it, transmits it or emits it to a telemetry backend. Use these methods for the values that must travel.
The split is the one Activity already makes, for the same reason: Tags stay in the process and Baggage is propagated, and they are two collections rather than one collection with a naming convention. A single bag whose entries sometimes cross a trust boundary cannot be read safely, because whether a given write leaves the process depends on a key spelling rather than on the call.
Propagation is explicit and per-value. There is no option that propagates
Items wholesale, and that absence is deliberate: a switch would make the
meaning of a write to Items depend on deployment configuration, so a consumer reading their own
handler could not tell what the line does.
Methods
GetPropagatedItem(IMessageContext, string)
Gets a value marked to travel with the message.
public static string? GetPropagatedItem(this IMessageContext context, string key)
Parameters
contextIMessageContextThe message context.
keystringThe name the value travels under.
Returns
Exceptions
- ArgumentNullException
contextorkeyis null.
GetPropagatedItems(IMessageContext)
Gets the values marked to travel with the message.
public static IReadOnlyDictionary<string, string> GetPropagatedItems(this IMessageContext context)
Parameters
contextIMessageContextThe message context.
Returns
- IReadOnlyDictionary<string, string>
The propagated entries, or an empty dictionary when none were marked. Never null.
Remarks
The returned dictionary is a live, read-only view of the context's own collection rather than a copy, so a later SetPropagatedItem(IMessageContext, string, string) is visible through it and a sink on a per-message path allocates nothing to read it. It is read-only to its caller, not merely in its declared type: mutating it through any cast throws. A sink that must hold the set across an await should copy it.
Exceptions
- ArgumentNullException
contextis null.
RemovePropagatedItem(IMessageContext, string)
Removes one value marked to travel with the message.
public static bool RemovePropagatedItem(this IMessageContext context, string key)
Parameters
contextIMessageContextThe message context.
keystringThe exact, case-sensitive propagated key.
Returns
- bool
Whether a marked value was removed.
Remarks
Only explicitly propagated values are affected. Request-local items remain unchanged. Removing an absent key does not allocate a propagation collection. This method does not authorize the removal or validate the meaning of the value.
Exceptions
- ArgumentNullException
contextis null.- ArgumentException
keyis null, empty, or whitespace.
SetPropagatedItem(IMessageContext, string, string)
Marks a value to travel with the message beyond this process.
public static void SetPropagatedItem(this IMessageContext context, string key, string value)
Parameters
contextIMessageContextThe message context.
keystringThe name the value travels under. Rendered per binding by each transport.
valuestringThe value. Already its own wire form.
Remarks
A later call with the same key replaces the earlier value.
Bounded, and the bound REFUSES rather than truncates: a key of at most 256 UTF-8 bytes, a value of at most 1024 UTF-8 bytes, and at most 100 propagated items on one message. Overwriting a key you already set is always allowed, since it does not change the count. The sizes are measured in UTF-8 bytes and not in characters, because that is the unit every transport limit is expressed in — a value of 600 multi-byte characters can exceed the byte limit.
Why it refuses instead of shortening, which is the decisive part rather than a stylistic one: a value this framework truncated would be read downstream as though it were whole, and nothing there could tell. An exception is loud and recoverable at the line that caused it; a quietly shortened value is neither.
Why the bound lives here and not at the transport. A marked value is set once and may be forwarded to any transport, and to several, so the only sound bound is the intersection of what every transport accepts — applied where your own code is on the stack and the offending value is attributable. The numbers above are the strictest limits across the supported transports, and that transport documents them as fixed constraints which cannot be raised by configuration. Enforcing them at the sink instead would mean the same code works against one broker and fails against another, discovered in production: brokers reject the whole message rather than the offending header, so an oversized value becomes an undeliverable staged row that retries indefinitely, which is a stall you cannot see.
This is a deliberate deviation from AddBaggage(string, string), which applies no bound. The shape is the same and the destination is not: baggage stays within a trace, while a marked value is published as a broker attribute under a hard, non-negotiable limit. Matching the surface is right; inheriting the unboundedness would move the failure to a place the caller cannot see.
Still validate a value that came from your caller before marking it. These bounds stop an oversized value, not an untrusted one, and this method's intended use means the value is frequently theirs rather than yours.
Exceptions
- ArgumentNullException
context,keyorvalueis null.- ArgumentException
keyis empty or whitespace; or names a header an outbox store supplies as its own envelope framing; orkeyexceeds 256 UTF-8 bytes; orvalueexceeds 1024 UTF-8 bytes; or this context already carries 100 propagated items andkeyis not one of them.