From 5f5411deb95b536903edac5c6e77dd410e539b5c Mon Sep 17 00:00:00 2001
From: Bartosz Klonowski <bartosz-klonowski@cx-code.pl>
Date: Wed, 2 Jul 2025 21:06:29 +0200
Subject: [PATCH 1/3] Add an example of using UnscopedRefAttribute to fix
 CS8170

---
 .../compiler-messages/cs8170.md               | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/csharp/language-reference/compiler-messages/cs8170.md b/docs/csharp/language-reference/compiler-messages/cs8170.md
index 660b91c6fd8b1..57a8a532d48f3 100644
--- a/docs/csharp/language-reference/compiler-messages/cs8170.md
+++ b/docs/csharp/language-reference/compiler-messages/cs8170.md
@@ -83,3 +83,30 @@ public class Other
     }
 }
 ```
+
+Another approach is to use the <xref:System.Diagnostics.CodeAnalysis.UnscopedRefAttribute?displayProperty=nameWithType> attribute. It will mark the reference to be allowed to escape the scope.
+Below is the example of applying <xref:System.Diagnostics.CodeAnalysis.UnscopedRefAttribute?displayProperty=nameWithType> to `int M()` method, which fixes the CS8170:
+
+```csharp
+using System.Diagnostics.CodeAnalysis;
+
+struct Program
+{
+    public int d;
+
+    [UnscopedRef]
+    public ref int M()
+    {
+        return ref d;    // No error - ref is valid to escape the scope in this line of that method
+    }
+}
+
+public class Other
+{
+    public void Method()
+    {
+        var p = new Program();
+        var d = p.M();
+    }
+}
+```

From c3fb5a3d9018a133d041972799631799a6e4bde6 Mon Sep 17 00:00:00 2001
From: Bartosz Klonowski <bartosz-klonowski@cx-code.pl>
Date: Thu, 3 Jul 2025 19:51:12 +0200
Subject: [PATCH 2/3] Use ref when assigning result of M to d var

---
 docs/csharp/language-reference/compiler-messages/cs8170.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/csharp/language-reference/compiler-messages/cs8170.md b/docs/csharp/language-reference/compiler-messages/cs8170.md
index 57a8a532d48f3..5eee7acb1da12 100644
--- a/docs/csharp/language-reference/compiler-messages/cs8170.md
+++ b/docs/csharp/language-reference/compiler-messages/cs8170.md
@@ -35,7 +35,7 @@ public class Other
     public void Method()
     {
         var p = new Program();
-        var d = p.M();
+        ref int d = ref p.M();
     }
 }
 ```
@@ -106,7 +106,7 @@ public class Other
     public void Method()
     {
         var p = new Program();
-        var d = p.M();
+        ref int d = ref p.M();
     }
 }
 ```

From 5cb6f63abdaf61e2172bc4eb5f6847d984d6c98a Mon Sep 17 00:00:00 2001
From: Bartosz Klonowski <bartosz-klonowski@cx-code.pl>
Date: Thu, 3 Jul 2025 19:54:38 +0200
Subject: [PATCH 3/3] Warn for being sure about safety of leaving the scope by
 ref

---
 docs/csharp/language-reference/compiler-messages/cs8170.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/csharp/language-reference/compiler-messages/cs8170.md b/docs/csharp/language-reference/compiler-messages/cs8170.md
index 5eee7acb1da12..56c0d5bfdd24a 100644
--- a/docs/csharp/language-reference/compiler-messages/cs8170.md
+++ b/docs/csharp/language-reference/compiler-messages/cs8170.md
@@ -84,7 +84,8 @@ public class Other
 }
 ```
 
-Another approach is to use the <xref:System.Diagnostics.CodeAnalysis.UnscopedRefAttribute?displayProperty=nameWithType> attribute. It will mark the reference to be allowed to escape the scope.
+Another approach is to use the <xref:System.Diagnostics.CodeAnalysis.UnscopedRefAttribute?displayProperty=nameWithType> attribute. It will mark the reference to be allowed to escape the scope.<br/>
+Use this only when you know that it is safe for the reference to leave the scope.
 Below is the example of applying <xref:System.Diagnostics.CodeAnalysis.UnscopedRefAttribute?displayProperty=nameWithType> to `int M()` method, which fixes the CS8170:
 
 ```csharp