Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

The StackTrace and StackFrame classes

Reference for System.Diagnostics.StackTrace and StackFrame in C#: capture the call stack, read method names, skip frames, and understand inlining and line numbers.

System.Diagnostics.StackTrace describes the chain of method calls that led to a point in your program. Each entry is a StackFrame that knows its method, and, when debug symbols are available, its file name, line and column. You can capture the current stack, or the stack stored in an exception.

For everyday debugging you rarely need to build one: Exception.StackTrace and Environment.StackTrace already give text. The classes are for code that needs structured access, such as logging helpers that report their caller or diagnostic tools that filter frames.

C#
var trace = new StackTrace();
string caller = trace.GetFrame(1)?.GetMethod()?.Name ?? "?";

Try it

C# Walking the current stack

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# The stack inside an exception

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.

Syntax

C#
public class StackTrace
{
    public StackTrace();
    public StackTrace(bool fNeedFileInfo);
    public StackTrace(int skipFrames);
    public StackTrace(int skipFrames, bool fNeedFileInfo);
    public StackTrace(Exception e);
    public StackTrace(Exception e, bool fNeedFileInfo);

    public int FrameCount { get; }
    public virtual StackFrame? GetFrame(int index);
    public virtual StackFrame[] GetFrames();
    public override string ToString();
}

public class StackFrame
{
    public virtual MethodBase? GetMethod();
    public virtual string? GetFileName();
    public virtual int GetFileLineNumber();
    public virtual int GetILOffset();
}
Name Description
skipFrames How many frames to omit from the top. 1 omits the method that created the trace.
fNeedFileInfo Try to read file names and line numbers from debug symbols. Slower; off by default.
e Build the trace from the stack recorded in an exception.
GetFrame(i) Frame i, where 0 is the innermost (most recent call). null if out of range.
GetFileLineNumber() Line number, or 0 when no symbols are available.

Returns: GetFrames() is an array ordered from the innermost frame to the outermost. Errors: none special; missing information yields null or 0.

Usage notes

  • Order. Frame 0 is where the trace was created; the last frame is the program's entry point.
  • Inlining and optimizations change the stack. In an optimized build the JIT can inline small methods, so they never appear. Mark a method [MethodImpl(MethodImplOptions.NoInlining)] if you rely on it being a frame, as the first example does.
  • Names can look odd. Local functions, lambdas, async methods and top-level statements get compiler-generated names such as <Main>$. Put code in named methods when you display frames.
  • Line numbers need symbols. Release builds without a .pdb report 0 or no file. Do not print line numbers in tests or documentation: they change with every edit.
  • Cost. Capturing a trace walks the stack and allocates; do not do it in hot paths. For the caller's name use [CallerMemberName], which is resolved at compile time and is free at run time.
  • Exceptions capture their own. Exception.StackTrace is only filled once the exception has been thrown. new StackTrace(e) shows the same frames as structured data, only up to the catch point.
  • Environment.StackTrace returns the current stack as a string, including runtime frames at the top.
  • Reflection data is limited under NativeAOT and trimming, so method names or frames can be missing in published apps.
  • Security. Stack text exposes class names and paths. Log it, but do not send it to end users.