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.
var trace = new StackTrace(); string caller = trace.GetFrame(1)?.GetMethod()?.Name ?? "?";
Try it
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.
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
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,
asyncmethods 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
.pdbreport0or 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.StackTraceis 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.StackTracereturns 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.