[Learning] Improve error handling for PlatformNotSupportedException during MSI JSON encoding (SIMD intrinsics unavailable)

[Copilot]

Problem

When MSI flows build claims/client-capabilities JSON on platforms without hardware intrinsics support (32-bit processes, old CPUs, or disabled intrinsics), System.Text.Encodings.Web throws PlatformNotSupportedException. This exception bubbles up through Azure.Identity as a cryptic error that appears to be an MSI/KeyVault issue, causing users to debug in the wrong direction.

Stack trace users see:

System.PlatformNotSupportedException: Operation is not supported on this platform.
  at System.Text.Encodings.Web.OptimizedInboxTextEncoder.AllowedAsciiCodePoints.get_AsVector()
  at System.Text.Encodings.Web.OptimizedInboxTextEncoder.GetIndexOfFirstCharToEncodeSsse3(...)
  at System.Text.Json.Utf8JsonWriter.WritePropertyName(...)
  at Microsoft.Identity.Client.Utils.JsonHelper.JsonObjectToString(...)
  at Microsoft.Identity.Client.Internal.ClaimsHelper.GetMergedClaimsAndClientCapabilities(...)

Solution

This PR wraps PlatformNotSupportedException in an actionable MsalClientException with comprehensive diagnostic information to guide users to the correct resolution.

Changes Made

1. Added new error code (MsalError.JsonEncoderIntrinsicsUnsupported = "json_encoder_intrinsics_unsupported")
2. Added diagnostic message generator that includes:
   • Process architecture (X86/X64/ARM from RuntimeInformation.ProcessArchitecture)
   • 64-bit process flag (Environment.Is64BitProcess)
   • Hardware intrinsics environment variable status (DOTNET_EnableHWIntrinsic or COMPlus_EnableHWIntrinsic)
   • Clear mitigation steps
3. Protected JSON serialization paths in ClaimsHelper.GetMergedClaimsAndClientCapabilities(), JsonHelper.JsonObjectToString(), and JsonHelper.Merge()
4. Catches both exception types: Direct PlatformNotSupportedException and TypeInitializationException wrapper (for static initialization scenarios)
5. Added unit tests to validate error code constant and message generation

User Experience Improvement

Before: Hours spent debugging what appears to be an MSI/KeyVault configuration issue

After: Immediate, actionable error message:

MsalClientException: JSON encoding failed due to unavailable hardware intrinsics (SIMD/SSSE3). 
Process architecture: X86, Is 64-bit process: False, DOTNET_EnableHWIntrinsic: (not set). 
Mitigation: Run as 64-bit process, update runtime, or set environment variable DOTNET_EnableHWIntrinsic=0 to force the non-SIMD code path.

Error Code: json_encoder_intrinsics_unsupported

Common Resolution Scenarios

• Azure App Service (32-bit): Switch to 64-bit in Azure Portal
• Old hardware without SSSE3: Set environment variable DOTNET_EnableHWIntrinsic=0
• Explicitly enabled on incompatible system: Change DOTNET_EnableHWIntrinsic=1 to 0

Design Decisions

• System.Text.Json only: Issue doesn't affect Newtonsoft.Json (no hardware intrinsics)
• Defense in depth: Protected at both low-level (JsonHelper) and high-level (ClaimsHelper) to catch the exception regardless of code path
• Minimal changes: Surgical modifications to only necessary code paths
• Rich diagnostics: Error includes all information needed for troubleshooting without additional debugging

Testing

• Added unit tests to verify error code and message generation
• Validated that existing claims/capabilities tests still pass
• Build successful on net8.0 and netstandard2.0 with no warnings

Related Issue

Fixes #[issue number] (related to internal incident https://portal.microsofticm.com/imp/v5/incidents/details/693043934/summary)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug] Improve error handling when System.Text.Encodings.Web SIMD path is unsupported during MSI JSON build (PlatformNotSupportedException → actionable MsalClientException)</issue_title>
<issue_description>### Library version used

latest

.NET version

net 8

Scenario

ManagedIdentityClient - managed identity

Is this a new or an existing app?

The app is in production, and I have upgraded to a new version of MSAL

Issue description and reproduction steps

Repro (minimal):

• Host a .NET worker on a machine/App Service/WebJob where HW intrinsics aren’t available (32-bit, old CPU, or intrinsics disabled).
• Acquire MSI token via Azure.Identity (which calls MSAL) while passing claims or client capabilities (any code path that builds JSON).
• Observe crash:

System.PlatformNotSupportedException
  at System.Text.Encodings.Web.OptimizedInboxTextEncoder.AllowedAsciiCodePoints.get_AsVector()
  at System.Text.Encodings.Web.OptimizedInboxTextEncoder.GetIndexOfFirstCharToEncodeSsse3(...)
  at System.Text.Json.Utf8JsonWriter.WritePropertyName(...)
  at Microsoft.Identity.Client.Utils.JsonHelper.JsonObjectToString(...)
  at Microsoft.Identity.Client.Internal.ClaimsHelper.GetMergedClaimsAndClientCapabilities(...)

Relevant code snippets

Expected behavior

MSAL wraps this in an MsalClientException with a clear message and remediation:

“Process may be 32-bit or hardware intrinsics are unavailable. Run x64, update runtime, or set DOTNET_EnableHWIntrinsic=0 to force the non-SIMD path.”

ACTUAL :-

PlatformNotSupportedException bubbles up via Azure.Identity as “ManagedIdentityCredential authentication failed: Operation is not supported on this platform,” which looks like an MSI/KeyVault issue.

Identity provider

Microsoft Entra ID (Work and School accounts and Personal Microsoft accounts)

Regression

No response

Solution and workarounds

Guard JSON merge calls:

try { … } catch (PlatformNotSupportedException ex) { throw new MsalClientException("json_encoder_intrinsics_unsupported", BuildHelpfulMessage(), ex); }</issue_description>

<agent_instructions>When MSI flows build the claims/client-capabilities JSON, System.Text.Encodings.Web may pick a SIMD/SSSE3 path that isn’t supported on some hosts. The runtime throws PlatformNotSupportedException during JSON writing; Azure.Identity rethrows it as an MSI failure. We want MSAL to catch and surface an actionable MsalClientException and add unit tests for this behavior.

System.PlatformNotSupportedException
at System.Text.Encodings.Web.OptimizedInboxTextEncoder.AllowedAsciiCodePoints.get_AsVector()
at System.Text.Encodings.Web.OptimizedInboxTextEncoder.GetIndexOfFirstCharToEncodeSsse3(...)
at System.Text.Json.Utf8JsonWriter.WritePropertyName(...)
at Microsoft.Identity.Client.Utils.JsonHelper.JsonObjectToString(...)
at Microsoft.Identity.Client.Internal.ClaimsHelper.GetMergedClaimsAndClientCapabilities(...)
... Azure.Identity.ManagedIdentityCredential ...

Targeted code areas:

src/client/Microsoft.Identity.Client/Internal/ClaimsHelper.cs

src/client/Microsoft.Identity.Client/Utils/JsonHelper.cs

Design/behavior we want:

Wrap calls that serialize claims/capabilities JSON in:

catch (PlatformNotSupportedException pns) and catch (TypeInitializationException tie) when (tie.InnerException is PlatformNotSupportedException)
(the encoder can throw either directly or during static init).

Rethrow MsalClientException with:

ErrorCode: "json_encoder_intrinsics_unsupported"

Message that includes: process arch (RuntimeInformation.ProcessArchitecture), Environment.Is64BitProcess, and value of DOTNET_EnableHWIntrinsic (or COMPlus_EnableHWIntrinsic) to aid diagnosis.

And add unit tests for these </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@gladjohn related to an internal [incident](https://portal.microsofticm.com/imp/v5/incidents/details/693043934/summary)

Fixes #5521

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[gladjohn]

test can be better here?