[PrathmeshPawar2110]

Context

This is not a serializer regression. @luisangelrod's investigation on this issue found that BlobResourceContents.Blob, ImageContentBlock.Data, and AudioContentBlock.Data are documented to hold the base64 text representation of the data, as UTF-8 bytes — not raw, unencoded binary. The correct construction path for raw bytes is the FromBytes factory on each type (BlobResourceContents.FromBytes(...), ImageContentBlock.FromBytes(...), AudioContentBlock.FromBytes(...)), which base64-encodes correctly. Serializing an instance built via FromBytes, or with the property set to real base64 UTF-8 bytes, already round-trips correctly through McpJsonUtilities.DefaultOptions.

The real problem: assigning raw bytes directly to Blob/Data (the mistake in the issue's repro) is silent and easy. Nothing fails at the point of assignment. The polymorphic JSON writer serializes those bytes as if they already were base64 text (Utf8JsonWriter.WriteString(name, ReadOnlySpan<byte>)), and since most raw binary isn't valid UTF-8, it gets mangled (escaped control characters, replacement characters) rather than rejected outright. The corruption then only surfaces later, confusingly, as a FormatException on the deserializing end.

Fix

Add EncodingUtilities.ValidateBase64Utf8 and call it from the Blob/Data setters on all three types, so assigning non-base64 bytes now throws an ArgumentException immediately, naming the FromBytes factory to use instead:

new ImageContentBlock { Data = someRawBytes, MimeType = "image/png" };
// ArgumentException: The value must be the base64 text representation of the binary data, as
// UTF-8 bytes, not the raw, unencoded bytes. Use ImageContentBlock.FromBytes(...) to construct
// an instance from raw binary data instead. (Parameter 'Data')

To avoid penalizing the common (correct) case, the JSON converters' existing fast path — reusing an unescaped wire value's UTF-8 bytes directly, which are already known-valid base64 text as read from the document — now goes through a new internal FromTrustedBase64Utf8 factory on each type that bypasses this validation, so normal deserialization pays no extra cost.

A few existing tests used a non-base64 placeholder string ("base64data", or a raw byte[] { 1, 2, 3 } literal) as filler Data/Blob content; those are updated to use real base64 text, since base64 fidelity was never what those tests were checking.

Fixes #1835

Testing

dotnet build
# Build succeeded, 0 Warning(s), 0 Error(s)

dotnet test tests/ModelContextProtocol.Tests/ --filter "FullyQualifiedName~ContentBlockTests|FullyQualifiedName~ResourceContentsTests|FullyQualifiedName~ReadResourceResultTests|FullyQualifiedName~PromptMessageTests"
# net8.0, net9.0, net10.0, net472: 193/193 passed on each

New tests cover: raw-bytes rejection on all three setters (including a 900,000-byte payload matching the issue's repro size), rejection of well-formed-alphabet-but-wrong-length input, and that the existing FromBytes/valid-base64-setter/JSON-round-trip paths are unaffected.

I also ran the full suite (dotnet test tests/ModelContextProtocol.Tests/, net10.0): 3313 passed. The non-zero failure count there reproduces in this environment on unrelated branches too — this sandbox's checkout path contains a space (C:\Open Source\csharp-sdk), which breaks StdioClientTransportTests.EscapesCliArgumentsCorrectly's cmd.exe argument parsing regardless of what's being tested, plus some test-host launch flakiness unrelated to this change.

Co-Authored-By: Claude Sonnet 5 [email protected]