Add unsafe evolution attributes by jjonescz · Pull Request #125721 · dotnet/runtime

jjonescz · 2026-03-18T10:59:26Z

Relates to test plan dotnet/roslyn#81207

dotnet-policy-service · 2026-03-18T11:00:41Z

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

Copilot

Pull request overview

Adds two runtime attributes to the public System.Runtime contract to support unsafe-context analysis and module-level memory-safety metadata, with corresponding implementations in System.Private.CoreLib.

Changes:

Exposes System.Diagnostics.CodeAnalysis.RequiresUnsafeAttribute as a public attribute applicable to constructors/events/methods/properties.
Introduces System.Runtime.CompilerServices.MemorySafetyRulesAttribute (module-level, editor-browsable never) with a Version payload.
Implements MemorySafetyRulesAttribute in System.Private.CoreLib and updates RequiresUnsafeAttribute to be public (non-conditional) with updated documentation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/libraries/System.Runtime/ref/System.Runtime.cs	Adds the new public attribute declarations to the System.Runtime reference contract.
src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/MemorySafetyRulesAttribute.cs	Implements `MemorySafetyRulesAttribute` with version storage and hidden editor-browsing.
src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs	Makes `RequiresUnsafeAttribute` public and expands its applicable targets.

You can also share your feedback on Copilot code review. Take the survey.

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs

Copilot

Pull request overview

This PR exposes RequiresUnsafeAttribute publicly and introduces a new MemorySafetyRulesAttribute API, updating the reference surface and adding basic tests to validate constructor behavior.

Changes:

Add MemorySafetyRulesAttribute to System.Runtime.CompilerServices (ref + implementation) and test its Version roundtrip.
Make RequiresUnsafeAttribute a public attribute with broader AttributeTargets and add a smoke test.
Add CoreLib package-validation suppressions for the new/changed APIs.

Reviewed changes

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

Show a summary per file

File	Description
src/libraries/System.Runtime/tests/System.Runtime.Tests/System/Runtime/CompilerServices/AttributesTests.cs	Adds a theory test for `MemorySafetyRulesAttribute.Version`.
src/libraries/System.Runtime/tests/System.Runtime.Tests/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttributeTests.cs	Adds a minimal constructor smoke test for `RequiresUnsafeAttribute`.
src/libraries/System.Runtime/ref/System.Runtime.cs	Updates the public ref surface to include `RequiresUnsafeAttribute` and `MemorySafetyRulesAttribute`.
src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/MemorySafetyRulesAttribute.cs	Introduces the CoreLib implementation of `MemorySafetyRulesAttribute`.
src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs	Changes `RequiresUnsafeAttribute` from internal/debug-only to public and updates usage/summary.
src/coreclr/System.Private.CoreLib/CompatibilitySuppressions.xml	Adds compat suppressions for the new attribute and attribute-usage differences.
src/coreclr/nativeaot/System.Private.CoreLib/src/CompatibilitySuppressions.xml	Mirrors the compat suppressions for NativeAOT CoreLib.

You can also share your feedback on Copilot code review. Take the survey.

...ies/System.Private.CoreLib/src/System/Runtime/CompilerServices/MemorySafetyRulesAttribute.cs

src/libraries/System.Runtime/ref/System.Runtime.cs

src/coreclr/System.Private.CoreLib/CompatibilitySuppressions.xml

src/coreclr/nativeaot/System.Private.CoreLib/src/CompatibilitySuppressions.xml

EgorBo · 2026-03-18T16:41:58Z

Does ILLink strip these attributes? If it does - should we fix it? cc @agocke

agocke · 2026-03-18T16:48:15Z

The linker doesn’t strip attributes

EgorBo

jkotas · 2026-03-19T16:27:17Z

Does ILLink strip these attributes? If it does - should we fix it?

Linker can strip attributes that are not needed at runtime. It is controlled by https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/ILLink/ILLink.LinkAttributes.Shared.xml

Unless we start reading this attribute at runtime (no plans for that currently), we may want to add it to the trimmed list.

agocke

LGTM, matches recent LDM decisions.

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs

src/libraries/System.Runtime/ref/System.Runtime.cs

jcouv · 2026-03-19T17:42:59Z

@agocke I disabled auto-merge as I have a question. For some reason my comment didn't post earlier, but it shows up now.

Copilot

Pull request overview

Adds the BCL surface area needed for the “unsafe evolution” feature by introducing the new attributes in the appropriate namespaces and wiring them into reference assemblies and tests.

Changes:

Add System.Runtime.CompilerServices.MemorySafetyRulesAttribute to System.Private.CoreLib (+ ref) and validate its Version round-trips in tests.
Promote System.Diagnostics.CodeAnalysis.RequiresUnsafeAttribute from internal/debug-only to a public attribute with updated AttributeUsage (+ ref) and add a basic constructor test.
Ensure the new CoreLib source file is included in the shared projitems for compilation.

Reviewed changes

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

Show a summary per file

File	Description
src/libraries/System.Runtime/tests/System.Runtime.Tests/System/Runtime/CompilerServices/AttributesTests.cs	Adds test coverage for `MemorySafetyRulesAttribute.Version`.
src/libraries/System.Runtime/tests/System.Runtime.Tests/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttributeTests.cs	New test validating `RequiresUnsafeAttribute` can be constructed.
src/libraries/System.Runtime/ref/System.Runtime.cs	Updates the reference surface to include `RequiresUnsafeAttribute` and `MemorySafetyRulesAttribute`.
src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/MemorySafetyRulesAttribute.cs	Introduces the new module-level attribute with `Version` property.
src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs	Makes the attribute public and updates its intended semantics/targets.
src/libraries/System.Private.CoreLib/src/System.Private.CoreLib.Shared.projitems	Includes the new attribute source file in the CoreLib build inputs.

You can also share your feedback on Copilot code review. Take the survey.

jkotas · 2026-03-19T18:11:39Z

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs

+        AttributeTargets.Constructor | AttributeTargets.Event | AttributeTargets.Method | AttributeTargets.Property,
+        Inherited = false,
+        AllowMultiple = false)]
+    public sealed class RequiresUnsafeAttribute : Attribute


This is included from multiple project files to make the same sources files compiled downlevel. It needs to follow the same public/internal pattern as nullability attributes with CORELIB ifdef:

runtime/src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/NullableAttributes.cs

Lines 18 to 23 in 37c9693

#if SYSTEM_PRIVATE_CORELIB

public

#else

internal

#endif

sealed class DisallowNullAttribute : Attribute { }

Good catch, thanks. I see the RequiresUnsafeAttribute is source-shared with Microsoft.Bcl.Memory.csproj and it makes sense we don't want to have it public there; but I'm surprised no CI check would catch this public API surface change in Microsoft.Bcl.Memory?

@ericstj Is it expected that we do not run public API surface validation for Microsoft.Bcl.Memory?

jcouv

LGTM Thanks (commit 4)

jcouv · 2026-03-19T19:59:41Z

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs

+        AttributeTargets.Constructor | AttributeTargets.Event | AttributeTargets.Method | AttributeTargets.Property,
+        Inherited = false,
+        AllowMultiple = false)]
+    public sealed class RequiresUnsafeAttribute : Attribute


Another thought from reading Richard's slide deck: should RequiresUnsafe be marked as experimental for .NET 11?

What do we think could potentially change here for the attribute that would warrant it being marked that way

I don't expect the attribute will change since it's pretty simple, but I don't know if that should be relevant.
The whole feature is experimental (ie. not "shipped") in .NET 11. Normally, that means that users have to opt into using an explicitly experimental feature.
FWIW, for roslyn APIs, we decided all APIs added for a not-yet-shipped feature get [Experimental] (systematically, no case-by-case consideration).

I'm not sure in this case it serves any practical purpose if we don't believe that the attribute itself will change.

Functionally this would just cause this everywhere:

#pragma warning disable DiagnosticId [RequiresUnsafe] #pragma warning restore DiagnosticId public void M() { // ... }

or require us to globally suppress the diagnostic and hinder user adoption of the attribute as well, when user adoption will already require explicit opt-in at the language level.

I agree that we want to streamline usage/adoption, but we also intentionally include one explicit speed bump specifically for experimental features. This feature should not be exempt.
I'm not sure what form it should take though (suppression for [Experimental] analyzer, flag given to the SDK with the word "Experimental" in it, ...).

Reframing as a more general question: what are the gestures we'll require from users to opt-in and do they clearly convey that the feature is experimental in .NET 11?

Is the language going to require LangVersion=preview even in .NET 11?

What's the compiler behavior if it encounters an assembly with MemorySafetyRules or an API with RequiresUnsafe and the user hasn't opted in at the language level?

This attribute in particular does feel more like RequiresPreviewFeatures (in the same way as we did static virtuals in interface for language + generic math for libraries in .NET 6) than Experimental, but I could also see us just saying the attribute isn't going to change and annotating APIs as requiring unsafe is always ok. The analyzer experience may just depend on the language (you won't see any warnings in VB or F#, for example) or language version (C#'s analysis may change between C# 15 and 16, which is the same plan we had nullable on where the nullable attributes weren't annotated on the libraries side).

Is the language going to require LangVersion=preview even in .NET 11?

I think we should, but we should confirm with the crew.
Similarly, when C# 10 shipped, we kept the feature StaticAbstractMembersInInterfaces attached to LangVersion=preview. The feature was marked as "shipped" with C# 11.

What's the compiler behavior if it encounters an assembly with MemorySafetyRules or an API with RequiresUnsafe and the user hasn't opted in at the language level?

If you turn on the new memory safety rules but use an older language version (than the version where the feature is "shipped") you get a compiler error.

This attribute in particular does feel more like RequiresPreviewFeatures

Ah, that's possible, I'm not sure between [RequiresPreviewFeatures] or [Experimental].

Is the language going to require LangVersion=preview even in .NET 11?

I think we should, but we should confirm with the crew.

I think we already discussed this and yes, that's the plan. There is even a comment for it:

https://github.com/dotnet/roslyn/blob/c2a993bf925f60e328823fbe0057cd5cbcff219e/src/Compilers/CSharp/Portable/Errors/MessageID.cs#L494

case MessageID.IDS_FeatureUnsafeEvolution: // https://github.com/dotnet/roslyn/issues/82546: keep this in preview until C# 16

Add unsafe evolution attributes

6f51237

Copilot AI review requested due to automatic review settings March 18, 2026 10:59

github-actions bot added the area-System.Runtime.CompilerServices label Mar 18, 2026

dotnet-policy-service bot assigned jjonescz Mar 18, 2026

Copilot started reviewing on behalf of jjonescz March 18, 2026 11:01 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

stephentoub reviewed Mar 18, 2026

View reviewed changes

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs Show resolved Hide resolved

stephentoub reviewed Mar 18, 2026

View reviewed changes

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs Show resolved Hide resolved

jjonescz added 2 commits March 18, 2026 14:43

Add suppressions

7ab7854

Add tests

ed25edb

jjonescz marked this pull request as ready for review March 18, 2026 15:28

jjonescz requested a review from MichalStrehovsky as a code owner March 18, 2026 15:28

Copilot AI review requested due to automatic review settings March 18, 2026 15:28

This comment was marked as resolved.

Sign in to view

Copilot started reviewing on behalf of jjonescz March 18, 2026 15:29 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Fix api compat

6703970

EgorBo approved these changes Mar 19, 2026

View reviewed changes

jcouv mentioned this pull request Mar 19, 2026

Test plan for "Unsafe Evolution" dotnet/roslyn#81207

Open

63 tasks

agocke approved these changes Mar 19, 2026

View reviewed changes

agocke enabled auto-merge (squash) March 19, 2026 17:37

jcouv disabled auto-merge March 19, 2026 17:42

jcouv reviewed Mar 19, 2026

View reviewed changes

...raries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/RequiresUnsafeAttribute.cs Show resolved Hide resolved

src/libraries/System.Runtime/ref/System.Runtime.cs Show resolved Hide resolved

Merge branch 'main' into 125134-UnsafeEvolutionAttributes

c568e5d

Copilot AI review requested due to automatic review settings March 19, 2026 17:53

Copilot started reviewing on behalf of jjonescz March 19, 2026 17:54 View session

Copilot AI reviewed Mar 19, 2026

View reviewed changes

jkotas reviewed Mar 19, 2026

View reviewed changes

jkotas requested changes Mar 19, 2026

View reviewed changes

jcouv approved these changes Mar 19, 2026

View reviewed changes

jcouv reviewed Mar 19, 2026

View reviewed changes

Add ifdef around accessibility

f12cf80

jkotas approved these changes Mar 20, 2026

View reviewed changes

	#if SYSTEM_PRIVATE_CORELIB
	public
	#else
	internal
	#endif
	sealed class DisallowNullAttribute : Attribute { }

Conversation

jjonescz commented Mar 18, 2026 • edited by jcouv Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dotnet-policy-service bot commented Mar 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EgorBo commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

agocke commented Mar 18, 2026

Uh oh!

EgorBo left a comment

Choose a reason for hiding this comment

Uh oh!

jkotas commented Mar 19, 2026

Uh oh!

agocke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jcouv commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjonescz Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcouv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tannergooding Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

jjonescz commented Mar 18, 2026 •

edited by jcouv

Loading

EgorBo commented Mar 18, 2026 •

edited

Loading

jjonescz Mar 20, 2026 •

edited

Loading

tannergooding Mar 19, 2026 •

edited

Loading