Remove ThrowHelper from Microsoft.Extensions.Primitives by svick · Pull Request #130416 · dotnet/runtime

svick · 2026-07-09T16:17:21Z

Summary

Removes ThrowHelper from Microsoft.Extensions.Primitives, replacing it with the BCL argument-validation throw helpers (ArgumentNullException.ThrowIfNull, ArgumentOutOfRangeException.ThrowIf*)
and direct throw statements. On downlevel target frameworks these are provided by the
shared ExceptionPolyfills.

The new patterns are more succinct and more modern and should be just as efficient.

The perf consideration is that a method containing the throw opcode is less likely to be inlined. This means the check (e.g. if (parameter is null)) should stay on the hot path, but the actual throwing should be done in another method (like the old ThrowHelper.Throw*Exception, an internal method in the new pattern or StringSegment.Throw*). Hiding the check in yet another method (like ArgumentNullException.ThrowIfNull) shouldn't hurt, because that method should be easily inlined.

Changes

Deletes ThrowHelper.cs along with its ExceptionArgument / ExceptionResource enums, and removes some per-type local throw helpers (InplaceStringBuilder's ThrowValidationError).
Null checks now use ArgumentNullException.ThrowIfNull.
Range checks now use ArgumentOutOfRangeException.ThrowIf* (e.g. ThrowIfLessThan). The caller's argument name is usually captured via CallerArgumentExpression.
InvalidOperationException sites become direct throw new ... using the existing SR resources. These shouldn't be on the hot path where the throw opcode would made a difference.
ExceptionPolyfills gains ThrowIfGreaterThan / ThrowIfGreaterThanOrEqual (matching the real ArgumentOutOfRangeException API surface) so the above works on the netstandard2.0 / net462 targets, where the real BCL methods aren't available.
StringSegment preserves its single-comparison fast path; the obsolete InplaceStringBuilder, where performance is mostly irrelevant, is simplified to straightforward validation.

Note

This pull request description was drafted with the assistance of GitHub Copilot.

Replace the local ThrowArgumentOutOfRangeException helper with the BCL ArgumentOutOfRangeException.ThrowIf* APIs. The hot-path single unsigned comparison is kept as a guard, delegating the throw to cold out-of-line helpers that re-check the signed value so the exception reports the actual argument (e.g. -1) with an enriched message instead of the unsigned wrap-around. Adds ThrowIfGreaterThan/ThrowIfGreaterThanOrEqual polyfills for downlevel target frameworks. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace manual 'if (x < 0) throw' checks with ArgumentOutOfRangeException.ThrowIf* and remove the now-unnecessary ThrowValidationError fast-path helper. Perf is not a concern for this obsolete type, so validation runs unconditionally. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dotnet-policy-service · 2026-07-09T16:18:34Z

Tagging subscribers to this area: @dotnet/area-extensions-primitives
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR removes the internal ThrowHelper pattern from Microsoft.Extensions.Primitives, replacing it with BCL argument-validation helpers (ArgumentNullException.ThrowIfNull, ArgumentOutOfRangeException.ThrowIf*) and direct throw sites, while adding downlevel support via ExceptionPolyfills.

Changes:

Delete ThrowHelper.cs (and its enums) and update call sites to use BCL ThrowIf* helpers / direct throws.
Update StringSegment to use new cold out-of-line throw helpers (keeping unsigned-comparison fast paths).
Extend ExceptionPolyfills with ThrowIfGreaterThan / ThrowIfGreaterThanOrEqual, and adjust tests for updated exception ParamName.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/libraries/Microsoft.Extensions.Primitives/tests/StringSegmentTest.cs	Updates expected `ArgumentOutOfRangeException.ParamName` to match new throw helper behavior.
src/libraries/Microsoft.Extensions.Primitives/src/ThrowHelper.cs	Deleted legacy throw-helper and supporting enums/resources indirection.
src/libraries/Microsoft.Extensions.Primitives/src/StringValues.cs	Replaces null-check ThrowHelper usage with `ArgumentNullException.ThrowIfNull`.
src/libraries/Microsoft.Extensions.Primitives/src/StringTokenizer.cs	Replaces ThrowHelper usage with `ThrowIfNull` / direct `ArgumentNullException`.
src/libraries/Microsoft.Extensions.Primitives/src/StringSegment.cs	Introduces cold throw helpers to preserve inlining/fast-path checks while modernizing validation.
src/libraries/Microsoft.Extensions.Primitives/src/InplaceStringBuilder.cs	Simplifies validation/throws to modern helpers and direct throws.
src/libraries/Microsoft.Extensions.Primitives/src/CompositeChangeToken.cs	Replaces ThrowHelper null-check with `ArgumentNullException.ThrowIfNull`.
src/libraries/Microsoft.Extensions.Primitives/src/ChangeToken.cs	Replaces ThrowHelper validation and InvalidOperation throws with direct throws/resources.
src/libraries/Common/src/System/ExceptionPolyfills.cs	Adds downlevel polyfills for `ArgumentOutOfRangeException.ThrowIfGreaterThan*`.

svick · 2026-07-10T09:53:55Z

+            ArgumentNullException.ThrowIfNull(value);
+            ArgumentOutOfRangeException.ThrowIfLessThan(offset, 0);
+            ArgumentOutOfRangeException.ThrowIfGreaterThan(count, value.Length - offset, nameof(offset));
+            if (Capacity - _offset < count)
            {
-                ThrowValidationError(value, offset, count);
+                throw new InvalidOperationException(SR.Format(SR.Capacity_NotEnough, value.Length, Capacity - _offset));
            }


I have added the check.

svick · 2026-07-10T09:18:32Z

One more thing: I think ThrowHelper could have served as a pattern to ensure that exception messages use resources. If that's something we want, I think an analyzer would be a better choice.

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

+            ArgumentOutOfRangeException.ThrowIfGreaterThan(count, value.Length - offset, nameof(offset));
+            if (Capacity - _offset < count)
            {
-                ThrowValidationError(value, offset, count);
+                throw new InvalidOperationException(SR.Format(SR.Capacity_NotEnough, value.Length, Capacity - _offset));
            }


tarekgh

LGTM!

svick and others added 3 commits July 9, 2026 15:56

Remove ThrowHelper from MS.E.Primitives

a22d151

Copilot AI review requested due to automatic review settings July 9, 2026 16:17

github-actions Bot added the area-Extensions-Primitives label Jul 9, 2026

dotnet-policy-service Bot assigned svick Jul 9, 2026

Copilot started reviewing on behalf of svick July 9, 2026 16:18 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

This was referenced Jul 9, 2026

slow macOS - "##[error]The job running on agent Azure Pipelines 9 ran longer than the maximum time of 60 minutes." dotnet/dnceng#1883

Open

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

Added a missing check based on review comment

eaf25e2

Copilot AI review requested due to automatic review settings July 10, 2026 09:53

Copilot started reviewing on behalf of svick July 10, 2026 09:54 View session

svick marked this pull request as ready for review July 10, 2026 09:54

svick requested review from mrek-msft, rosebyte and tarekgh July 10, 2026 09:54

Copilot AI reviewed Jul 10, 2026

View reviewed changes

mrek-msft approved these changes Jul 10, 2026

View reviewed changes

build-analysis Bot mentioned this pull request Jul 10, 2026

[ci-scan] Test failure: System.Globalization.Tests.IdnMappingGetUnicodeTests DllNotFoundException 'libSystem.Globalization.Native' on browser-wasm CoreCLR #130479

Open

tarekgh added this to the 11.0.0 milestone Jul 10, 2026

tarekgh approved these changes Jul 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Remove ThrowHelper from Microsoft.Extensions.Primitives#130416

Remove ThrowHelper from Microsoft.Extensions.Primitives#130416
svick wants to merge 4 commits into
dotnet:mainfrom
svick:primitives-throwhelper

svick commented Jul 9, 2026

Uh oh!

dotnet-policy-service Bot commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

svick Jul 10, 2026

Uh oh!

svick commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

tarekgh left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

svick commented Jul 9, 2026

Summary

Changes

Uh oh!

dotnet-policy-service Bot commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

svick Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

svick commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

tarekgh left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants