Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Keywords and Statements

The scoped modifier

Reference for the C# scoped modifier: restrict how far a ref, in, out or ref struct parameter or local can escape, so stackalloc spans and refs stay safe.

scoped is a modifier for ref, in, out parameters, for parameters and locals of a ref struct type (such as Span<T>), and for ref locals. It tells the compiler: "this value may be used inside the current method only; it will never be stored or returned." That promise lets the compiler accept calls that it would otherwise reject as unsafe.

Without it, the compiler has to assume that a method which receives a Span<int> might return it or save it somewhere. If the caller built that span from stackalloc, which dies when the caller returns, passing it could create a dangling reference. With scoped, the callee guarantees it will not leak the value, so the call is safe.

C#
static int Sum(scoped ReadOnlySpan<int> values) { /* use values locally */ }

Try it

C# A scoped parameter accepts stack memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# scoped ref and ref safety rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

What the compiler refuses. This snippet does not compile, because a scoped parameter may not be returned:

C#
static ref int Id(scoped ref int x) => ref x;
// error CS9075: Cannot return a parameter by reference 'x' because it is scoped to the current method

And this one does not compile, because Keep may return the span that points at local:

C#
static Span<int> Bad()
{
    Span<int> local = stackalloc int[4];
    return Keep(local);
}
static Span<int> Keep(Span<int> s) => s;
// error CS8352: Cannot use variable 'local' in this context because it may expose
// referenced variables outside of their declaration scope

Syntax

C#
void M(scoped ref T r);
void M(scoped in T r);
void M(scoped Span<T> s);       // ref struct parameter
scoped Span<int> local = ...;   // ref struct local
scoped ref int r = ref x;       // ref local
Where Meaning
Parameter The method will not return or store the parameter (or anything derived from it) beyond the call.
Local The variable may not be assigned to anything with a wider scope, nor returned.
out parameters out is already implicitly scoped; ref and in are not.

Errors: returning or storing a scoped value gives CS8352, CS8347 or CS9075. scoped on a non-ref, non-ref struct parameter is error CS9048 ("The 'scoped' modifier can be used for refs and ref struct values only").

Usage notes

  • The modifier was added in C# 11 together with the improved ref-safety rules. It is rarely needed in everyday code. You meet it mostly when writing low-level APIs over Span<T>.
  • A this parameter in a struct instance method is implicitly scoped ref, which is why a struct method cannot return a ref to the struct itself.
  • A parameter marked scoped also lets callers pass a ref to a local variable without the compiler worrying that it will escape.
  • [UnscopedRef] (from System.Diagnostics.CodeAnalysis) does the opposite: it lifts the implicit scoping of an out parameter or a struct this.
  • Declaring a scoped local with a stackalloc initializer is allowed and often unnecessary, since Span<int> x = stackalloc int[n] already has a safe-to-escape scope of the current method.
  • scoped has no run-time effect. It only changes what the compiler accepts, so it cannot make code slower.