From 0e8fd83b8b85ce7f018b577c1e42f6990ad30715 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:03:18 +0000
Subject: [PATCH 1/2] Initial plan


From 5f26b63dd106e41ae898a14f9e5d9718e0ce48c1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:17:23 +0000
Subject: [PATCH 2/2] Update String.GetPinnableReference() docs to clarify
 read-only constraint

Closes dotnet/runtime#130225

The XML documentation on `String.GetPinnableReference()` has been updated
to explicitly state that the returned `ref readonly char` interior pointer
is read-only. Writing to the referenced memory (for example, by casting away
`const` in C++/CLI when using `PtrToStringChars`) is not permitted and will
silently corrupt the CLR heap.

Co-authored-by: AaronRobinsonMSFT <30635565+AaronRobinsonMSFT@users.noreply.github.com>
---
 .../src/System/String.cs                      | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/libraries/System.Private.CoreLib/src/System/String.cs b/src/libraries/System.Private.CoreLib/src/System/String.cs
index 234f5e61529ad2..8549bf5d88035d 100644
--- a/src/libraries/System.Private.CoreLib/src/System/String.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/String.cs
@@ -518,8 +518,25 @@ public static bool IsNullOrWhiteSpace([NotNullWhen(false)] string? value)
         }
 
         /// <summary>
-        /// Returns a reference to the first element of the String. If the string is null, an access will throw a NullReferenceException.
+        /// Returns a read-only reference to the first element of the String. If the string is null, an access will throw a NullReferenceException.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// The <see cref="string"/> type is immutable: the value of a <see cref="string"/> object
+        /// cannot be changed after the object is created. The reference returned by this method is
+        /// <c>ref readonly</c> and must only be used for reading characters; writing to
+        /// the referenced memory is not permitted and results in undefined behavior, including
+        /// potential corruption of the managed heap.
+        /// </para>
+        /// <para>
+        /// When using this method (or the equivalent C++/CLI <c>PtrToStringChars</c> function) to
+        /// obtain a pinned interior pointer to the string's character data, the resulting pointer
+        /// must be treated as read-only. In C++/CLI, <c>PtrToStringChars</c> exposes the pointer
+        /// as <c>const wchar_t*</c> to reflect this constraint. Casting away <c>const</c>
+        /// and writing through the pointer will silently corrupt the CLR heap and may cause
+        /// crashes or incorrect behavior at an unrelated location later in program execution.
+        /// </para>
+        /// </remarks>
         [EditorBrowsable(EditorBrowsableState.Never)]
         [NonVersionable]
         public ref readonly char GetPinnableReference() => ref _firstChar;