Add Base64 parity APIs with Base64Url

[Copilot]

• Add new Base64 APIs to existing files
  • Moved encoding APIs to Base64Encoder.cs
  • Moved decoding APIs to Base64Decoder.cs
• Invert GetEncodedLength/GetMaxEncodedToUtf8Length relationship
• Invert GetMaxDecodedLength/GetMaxDecodedFromUtf8Length relationship
• Add Debug.Assert statements for expected status values
• Fix Debug.Assert typo in EncodeToString
• Distribute tests to Base64EncoderUnitTests.cs and Base64DecoderUnitTests.cs
• Update Base64Fuzzer.cs to test all new APIs
• Simplify Convert.cs using new Base64 APIs
  • Encoding:
    • ToBase64String(byte[]) delegates directly to Base64.EncodeToString
    • ToBase64String(ReadOnlySpan<byte>, options) delegates early to Base64.EncodeToString when !insertLineBreaks
    • ToBase64CharArray and TryToBase64Chars use Base64.EncodeToChars when !insertLineBreaks
    • ConvertToBase64ArrayInsertLineBreaks now accepts spans instead of pointers for callers
    • Removed Base64VectorizationLengthThreshold and ToBase64CharsLargeNoLineBreaks
  • Decoding:
    • TryFromBase64Chars now delegates to Base64.DecodeFromChars (with OperationStatus return), sets bytesWritten=0 on failure to match previous behavior
    • FromBase64String now delegates to Base64.DecodeFromChars(s) directly
    • FromBase64CharArray now delegates to Base64.DecodeFromChars with span
    • Removed Convert.Base64.cs entirely
    • Removed unused helpers
• Build succeeds

Security Summary

No security vulnerabilities were detected.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[API Proposal]: Base64 parity with Base64Url</issue_title>
<issue_description>EDITED by @stephentoub on 1/12/2026:

Copying members from Base64Url:

namespace System.Buffers.Text;

public static partial class Base64
{
    +public static byte[] DecodeFromChars(System.ReadOnlySpan<char> source);
    +public static int DecodeFromChars(System.ReadOnlySpan<char> source, System.Span<byte> destination);
    +public static OperationStatus DecodeFromChars(System.ReadOnlySpan<char> source, System.Span<byte> destination, out int charsConsumed, out int bytesWritten, bool isFinalBlock = true);

    +public static byte[] DecodeFromUtf8(System.ReadOnlySpan<byte> source);
    +public static int DecodeFromUtf8(System.ReadOnlySpan<byte> source, System.Span<byte> destination);

    +public static char[] EncodeToChars(System.ReadOnlySpan<byte> source);
    +public static int EncodeToChars(System.ReadOnlySpan<byte> source, System.Span<char> destination);
    +public static OperationStatus EncodeToChars(System.ReadOnlySpan<byte> source, System.Span<char> destination, out int bytesConsumed, out int charsWritten, bool isFinalBlock = true);

    +public static string EncodeToString(System.ReadOnlySpan<byte> source);
    +public static byte[] EncodeToUtf8(System.ReadOnlySpan<byte> source);
    +public static int EncodeToUtf8(System.ReadOnlySpan<byte> source, System.Span<byte> destination);

    +public static bool TryDecodeFromChars(System.ReadOnlySpan<char> source, System.Span<byte> destination, out int bytesWritten);
    +public static bool TryDecodeFromUtf8(System.ReadOnlySpan<byte> source, System.Span<byte> destination, out int bytesWritten);
    +public static bool TryEncodeToChars(System.ReadOnlySpan<byte> source, System.Span<char> destination, out int charsWritten);
    +public static bool TryEncodeToUtf8(System.ReadOnlySpan<byte> source, System.Span<byte> destination, out int bytesWritten);
    +public static bool TryEncodeToUtf8InPlace(System.Span<byte> buffer, int dataLength, out int bytesWritten);

    +public static int GetEncodedLength(int bytesLength);
    +public static int GetMaxDecodedLength(int base64Length);
}

---

Background and motivation

The API on Base64Url is very nice. However, there are no equivalents for the things that deal with UTF-16 instead of UTF-8 on Base64 and the UTF-16 base64 functionality on Convert is not as nice.

Here's an example: using Convert, I can't tell if it has failed due to invalid input or destination-too-small. This is actually getting in my way right now in a use case where I want decode only some bytes from base64. I went to copy some code that used Base64Url and was surprised that just dropping the Url suffix didn't work.

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

byte[] bytes = new byte[100_000];
RandomNumberGenerator.Fill(bytes);

string base64UrlInput = Base64Url.EncodeToString(bytes);
string base64Input = Convert.ToBase64String(bytes);
string badInput = "@#$!!@#";
byte[] buffer = new byte[1_000];

// Output of TryFromBase64Chars does not distinguish between bad input and destination too small.
{
    Console.WriteLine();
    Console.WriteLine("Bad input vs Convert.TryFromBase64Chars.");
    bool success = Convert.TryFromBase64Chars(badInput, buffer, out int bytesWritten);
    Console.WriteLine("bytesWritten: " + bytesWritten);
    Console.WriteLine("     success: " + success);
}
{
    Console.WriteLine();
    Console.WriteLine("Too much input vs Convert.TryFromBase64Chars");
    bool success = Convert.TryFromBase64Chars(base64Input, buffer, out int bytesWritten);
    Console.WriteLine("bytesWritten: " + bytesWritten);
    Console.WriteLine("     success: " + success);
}

// Output of DecodeFromChars is perfect, but it's only available on Base64Url.
{
    Console.WriteLine();
    Console.WriteLine("Too much input vs Base64Url.DecodeFromChars");
    var status = Base64Url.DecodeFromChars(base64UrlInput, buffer, out int charsConsumed, out int bytesWritten);
    Console.WriteLine("charsConsumed: " + charsConsumed);
    Console.WriteLine(" bytesWritten: " + bytesWritten);
    Console.WriteLine("      status : " + status);
}
{
    Console.WriteLine();
    Console.WriteLine("Bad input vs Base64Url.DecodeFromChars");
    var status = Base64Url.DecodeFromChars(badInput, buffer, out int charsConsumed, out int bytesWritten);
    Console.WriteLine("charsConsumed: " + charsConsumed);
    Console.WriteLine(" bytesWritten: " + bytesWritten);
    Console.WriteLine("      status : " + status);
}

Output:

Bad input vs Convert.TryFromBase64Chars.
bytesWritten: 0
     success: False

Too much input vs Convert.TryFromBase64Chars
bytesWritten: 0
     success: False

Too much input vs Base64Url.DecodeFromChars
charsConsumed: 1332
 bytesWritten: 999
      status : DestinationTooSmall

Bad input vs Base64Url.DecodeFromChars
charsConsumed: 0
 bytesW...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes dotnet/runtime#121454

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

[Copilot]

Pull request overview

This pull request adds new APIs to System.Buffers.Text.Base64 to achieve parity with Base64Url, particularly enabling callers to distinguish between InvalidData and DestinationTooSmall when decoding—a capability not available in Convert.TryFromBase64Chars.

Changes:

• Adds 16 new public methods to the Base64 class including encoding/decoding for chars and UTF-8, both throwing and Try-variants
• Introduces helper methods GetEncodedLength and GetMaxDecodedLength as aliases matching Base64Url naming conventions
• Implements internal encoder/decoder structs (Base64EncoderChar, Base64DecoderChar) to support char-based operations

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
System.Runtime.cs	Adds public API surface declarations for all 16 new Base64 methods
Base64Extensions.cs	Implements the new APIs using encoder/decoder pattern from Base64Url
System.Private.CoreLib.Shared.projitems	Registers the new Base64Extensions.cs file in the build
System.Memory.Tests.csproj	Adds the new test file to the test project
Base64UnicodeAPIsUnitTests.cs	Provides 39 unit tests covering all new APIs with various scenarios
Base64TestHelper.cs	Adds InitializeDecodableChars helper method for test data generation

[MihaZupan]

@copilot please address the new comments

[MihaZupan]

@copilot Ensure that the new APIs are covered in
https://github.com/dotnet/runtime/blob/main/src/libraries/Fuzzing/DotnetFuzzing/Fuzzers/Base64Fuzzer.cs
and
https://github.com/dotnet/runtime/blob/main/src/libraries/Fuzzing/DotnetFuzzing/Fuzzers/Base64UrlFuzzer.cs
if they're similar enough, consider merging them into a single fuzzer that tests both variants

[Copilot]

@copilot Ensure that the new APIs are covered in
https://github.com/dotnet/runtime/blob/main/src/libraries/Fuzzing/DotnetFuzzing/Fuzzers/Base64Fuzzer.cs
and
...

Added comprehensive fuzz testing coverage for all new Base64 APIs in Base64Fuzzer.cs:

• New TestBase64Chars method for char-based APIs (EncodeToChars, DecodeFromChars, EncodeToString, TryEncodeToChars, TryDecodeFromChars)
• Tests for new simplified UTF-8 APIs (EncodeToUtf8 returning byte[], DecodeFromUtf8 returning byte[], TryEncodeToUtf8, TryDecodeFromUtf8, TryEncodeToUtf8InPlace)
• Tests for GetEncodedLength/GetMaxDecodedLength consistency with existing methods

The fuzzers remain separate since Base64 and Base64Url use different encoding schemes ('+/' vs '-_' and padding behavior), so the encoded outputs differ. However, both now have parallel structure for their char-based APIs.

See commit f3969dc.

[Copilot]

@copilot, also there are a ton of System.Runtime.Extensions.Tests test failures

Restored the original whitespace-tolerant decoding implementation for Convert APIs. The Convert.FromBase64String/FromBase64CharArray/TryFromBase64Chars methods support whitespace in input (e.g., "abc= \t \r\n ="), but the new Base64.DecodeFromChars API is strict and doesn't handle whitespace. Restored Convert.Base64.cs with TryDecodeFromUtf16 fast path and the whitespace-handling loop. See commit 36c3884.

[MihaZupan]

@copilot There have been changes to the Base64 handling of whitespace since your previous commit.
Try to simplify the implementation of Base64-related helpers in Convert again as described in #123151

[Copilot]

@copilot There have been changes to the Base64 handling of whitespace since your previous commit.
Try to simplify the implementation of Base64-related helpers in Convert again as described in https...

Simplified Convert decoding in commit 3464c7d. Since Base64.DecodeFromChars now supports whitespace (ignoreWhiteSpace: true), all Convert decoding methods now delegate directly:

• TryFromBase64Chars → Base64.DecodeFromChars(chars, bytes, out _, out bytesWritten) returning status == Done
• FromBase64String → Base64.DecodeFromChars(s.AsSpan())
• FromBase64CharArray → Base64.DecodeFromChars(new ReadOnlySpan<char>(...))

Removed Convert.Base64.cs entirely along with all the helper methods.

[MihaZupan]

I'm not sure why Build Analysis was green on this one, there are a bunch of related test failures (fixed by #123260)

[pavelsavara]

I think this broke browser tests

Log

[13:26:19] info: [FAIL] System.Tests.ConvertTests.TryFromBase64Chars(encodedAsString: "  BQYH  CAY=  ", expected: [5, 6, 7, 8, 6])
[13:26:19] info: Assert.True() Failure
[13:26:19] info: Expected: True
[13:26:19] info: Actual:   False
[13:26:19] info:    at System.Tests.ConvertTests.TryFromBase64Chars(String encodedAsString, Byte[] expected)
[13:26:19] info:    at System.Object.InvokeStub_ConvertTests.TryFromBase64Chars(Object, Span`1)
[13:26:19] info:    at System.Reflection.MethodBaseInvoker.InvokeWithFewArgs(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)

[am11]

I'm not sure why Build Analysis was green on this one, there are a bunch of related test failures (fixed by #123260)

Interesting, that would mean if a PR adds new tests and those tests are failing, Build Analysis reports the PR as green, and the failures only surface on later PRs. I can’t think of a good reason for that behavior, so this feels like a bug in BA.

[pavelsavara]

On browser this was hidden behind another issue that prevented any tests from running at all.

[jkotas]

From build analysis log:

512 Known test errors not displayed due to space limitations
❌System.Net.Quic.Tests.MsQuicCipherSuitesPolicyTests.NoSupportedCiphers_ThrowsArgumentException - #123216

There was very large amount of known MSQUIC failures. The problem is that build Analysis gives up analyzing failures after it hits a threshold but remains green if all failures that have been analyzed are known.