Export (0) Print
Expand All

StackFrame Class

Provides information about a StackFrame, which represents a function call on the call stack for the current thread.

System.Object
  System.Diagnostics.StackFrame

Namespace:  System.Diagnostics
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
<SerializableAttribute> _
<ComVisibleAttribute(True)> _
<SecurityPermissionAttribute(SecurityAction.InheritanceDemand, UnmanagedCode := True)> _
Public Class StackFrame

The StackFrame type exposes the following members.

  NameDescription
Public methodStackFrameInitializes a new instance of the StackFrame class.
Public methodStackFrame(Boolean)Initializes a new instance of the StackFrame class, optionally capturing source information.
Public methodStackFrame(Int32)Initializes a new instance of the StackFrame class that corresponds to a frame above the current stack frame.
Public methodStackFrame(Int32, Boolean)Initializes a new instance of the StackFrame class that corresponds to a frame above the current stack frame, optionally capturing source information.
Public methodStackFrame(String, Int32)Initializes a new instance of the StackFrame class that contains only the given file name and line number.
Public methodStackFrame(String, Int32, Int32)Initializes a new instance of the StackFrame class that contains only the given file name, line number, and column number.
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetFileColumnNumberGets the column number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
Public methodGetFileLineNumberGets the line number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
Public methodGetFileNameGets the file name that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable.
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetILOffsetGets the offset from the start of the Microsoft intermediate language (MSIL) code for the method that is executing. This offset might be an approximation depending on whether or not the just-in-time (JIT) compiler is generating debugging code. The generation of this debugging information is controlled by the DebuggableAttribute.
Public methodGetMethodGets the method in which the frame is executing.
Public methodGetNativeOffsetGets the offset from the start of the native just-in-time (JIT)-compiled code for the method that is being executed. The generation of this debugging information is controlled by the DebuggableAttribute class.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringBuilds a readable representation of the stack trace. (Overrides Object.ToString.)
Top

  NameDescription
Public fieldStatic memberOFFSET_UNKNOWNDefines the value that is returned from the GetNativeOffset or GetILOffset method when the native or Microsoft intermediate language (MSIL) offset is unknown. This field is constant.
Top

A StackFrame is created and pushed on the call stack for every function call made during the execution of a thread. The stack frame always includes MethodBase information, and optionally includes file name, line number, and column number information.

StackFrame information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing StackFrame objects.

The following example demonstrates the use of the StackFrame class to provide the stack frame information for a stack trace.


Imports System
Imports System.Diagnostics



Class Program

    Shared Sub Main(ByVal args() As String)
        Try
            Method1()
        Catch e As Exception
            Dim st As New StackTrace()
            Dim st1 As New StackTrace(New StackFrame(True))
            Console.WriteLine(" Stack trace for Main: {0}", st1.ToString())
            Console.WriteLine(st.ToString())
        End Try
        Console.WriteLine("Press Enter to exit.")
        Console.ReadLine()

    End Sub 'Main

    Private Shared Sub Method1()
        Try
            Method2(4)
        Catch e As Exception
            Dim st As New StackTrace()
            Dim st1 As New StackTrace(New StackFrame(True))
            Console.WriteLine(" Stack trace for Method1: {0}", st1.ToString())
            Console.WriteLine(st.ToString())
            ' Build a stack trace for the next frame.
            Dim st2 As New StackTrace(New StackFrame(1, True))
            Console.WriteLine(" Stack trace for next level frame: {0}", st2.ToString())
            Throw e
        End Try

    End Sub 'Method1

    Private Shared Sub Method2(ByVal count As Integer)
        Try
            If count < 5 Then
                Throw New ArgumentException("count too large", "count")
            End If
        Catch e As Exception
            Dim st As New StackTrace()
            Dim st1 As New StackTrace(New StackFrame(2, True))
            Console.WriteLine(" Stack trace for Method2: {0}", st1.ToString())
            Console.WriteLine(st.ToString())
            Throw e
        End Try

    End Sub 'Method2
End Class 'Program


The following example demonstrates the use of the members of the StackFrame class.


Imports System
Imports System.Diagnostics

Imports SampleInternal

Namespace SamplePublic

   ' This console application illustrates various uses
   ' of the StackTrace and StackFrame classes.

   Class ConsoleApp

      <STAThread()>  _
      Shared Sub Main()
         Dim mainClass As New ClassLevel1

         Try
            mainClass.InternalMethod()
         Catch
            Console.WriteLine(" Main method exception handler")

            ' Display file and line information, if available.
            Dim st As New StackTrace(New StackFrame(True))
            Console.WriteLine(" Stack trace for current level: {0}", _
               st.ToString())
            Console.WriteLine(" File: {0}", _
               st.GetFrame(0).GetFileName())
            Console.WriteLine(" Line Number: {0}", _
               st.GetFrame(0).GetFileLineNumber().ToString())

            Console.WriteLine()
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
         End Try
      End Sub 'Main
   End Class 'ConsoleApp
End Namespace 'StackFramePublic 

Namespace SampleInternal

   Public Class ClassLevel1

      Public Sub InternalMethod()
         Try
            Dim nestedClass As New ClassLevel2
            nestedClass.Level2Method()
         Catch e As Exception
            Console.WriteLine(" InternalMethod exception handler")

            ' Build a stack trace from one frame, skipping the 
            ' current frame and using the next frame.  By default,
            ' file and line information are not displayed.
            Dim st As New StackTrace(New StackFrame(1))
            Console.WriteLine(" Stack trace for next level frame: {0}", _
               st.ToString())
            Console.WriteLine(" Stack frame for next level: ")
            Console.WriteLine("   {0}", st.GetFrame(0).ToString())

            Console.WriteLine(" Line Number: {0}", _
               st.GetFrame(0).GetFileLineNumber().ToString())

            Console.WriteLine()
            Console.WriteLine("   ... throwing exception to next level ...")
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
            Throw e
         End Try
      End Sub 'InternalMethod
   End Class 'ClassLevel1

   Public Class ClassLevel2

      Public Sub Level2Method()
         Try
            Dim nestedClass As New ClassLevel3
            nestedClass.Level3Method()

         Catch e As Exception
            Console.WriteLine(" Level2Method exception handler")

            ' Display the full call stack at this level.
            Dim st1 As New StackTrace(True)
            Console.WriteLine(" Stack trace for this level: {0}", _
               st1.ToString())

            ' Build a stack trace from one frame, skipping the current
            ' frame and using the next frame.
            Dim st2 As New StackTrace(New StackFrame(1, True))
            Console.WriteLine(" Stack trace built with next level frame: {0}", _
                st2.ToString())

            ' Build a stack trace skipping the current frame, and
            ' including all the other frames.
            Dim st3 As New StackTrace(1, True)
            Console.WriteLine(" Stack trace built from the next level up: {0}", _
                st3.ToString())

            Console.WriteLine()
            Console.WriteLine("   ... throwing exception to next level ...")
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
            Throw e
         End Try
      End Sub 'Level2Method
   End Class 'ClassLevel2

   Public Class ClassLevel3

      Public Sub Level3Method()
         Try
            Dim nestedClass As New ClassLevel4()
            nestedClass.Level4Method()
         Catch e As Exception
            Console.WriteLine(" Level3Method exception handler")

            ' Build a stack trace from a dummy stack frame.
            ' Explicitly specify the source file name and line number.
            Dim st As New StackTrace(New StackFrame("source.cs", 60))
            Console.WriteLine(" Stack trace with dummy stack frame: {0}", _
               st.ToString())
            Dim i As Integer
            For i = 0 To st.FrameCount - 1
               ' Display the stack frame properties.
               Dim sf As StackFrame = st.GetFrame(i)
               Console.WriteLine(" File: {0}", sf.GetFileName())
               Console.WriteLine(" Line Number: {0}", _
                  sf.GetFileLineNumber())
               ' The column number defaults to zero when not initialized.
               Console.WriteLine(" Column Number: {0}", _
                  sf.GetFileColumnNumber())
               If sf.GetILOffset <> StackFrame.OFFSET_UNKNOWN
                  Console.WriteLine(" Intermediate Language Offset: {0}", _
                      sf.GetILOffset())
               End If
               If sf.GetNativeOffset <> StackFrame.OFFSET_UNKNOWN
                 Console.WriteLine(" Native Offset: {0}", _
                     sf.GetNativeOffset())
               End If
            Next i 
            Console.WriteLine()
            Console.WriteLine("   ... throwing exception to next level ...")
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
            Throw e
         End Try
      End Sub 'Level3Method
   End Class 'ClassLevel3

   Public Class ClassLevel4

      Public Sub Level4Method()
         Try
            Dim [nestedClass] As New ClassLevel5()
            [nestedClass].Level5Method()
         Catch e As Exception
            Console.WriteLine(" Level4Method exception handler")

            ' Build a stack trace from a dummy stack frame.
            ' Explicitly specify the source file name, line number
            ' and column number.
            Dim st As New StackTrace(New StackFrame("source.cs", 79, 24))
            Console.WriteLine(" Stack trace with dummy stack frame: {0}", _
               st.ToString())

            ' Access the StackFrames explicitly to display the file
            ' name, line number and column number properties.
            ' StackTrace.ToString only includes the method name. 
            Dim i As Integer
            For i = 0 To st.FrameCount - 1
               Dim sf As StackFrame = st.GetFrame(i)
               Console.WriteLine(" File: {0}", sf.GetFileName())
               Console.WriteLine(" Line Number: {0}", _
                  sf.GetFileLineNumber())
               Console.WriteLine(" Column Number: {0}", _
                  sf.GetFileColumnNumber())
            Next i
            Console.WriteLine()
            Console.WriteLine("   ... throwing exception to next level ...")
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
            Throw e
         End Try
      End Sub 'Level4Method 
   End Class 'ClassLevel4


   Public Class ClassLevel5

      Public Sub Level5Method()
         Try
            Dim nestedClass As New ClassLevel6()
            nestedClass.Level6Method()
         Catch e As Exception
            Console.WriteLine(" Level5Method exception handler")

            Dim st As New StackTrace()

            ' Display the most recent function call.
            Dim sf As StackFrame = st.GetFrame(0)
            Console.WriteLine()
            Console.WriteLine("  Exception in method: ")
            Console.WriteLine("      {0}", sf.GetMethod())

            If st.FrameCount > 1 Then
               ' Display the highest-level function call in the trace.
               sf = st.GetFrame((st.FrameCount - 1))
               Console.WriteLine("  Original function call at top of call stack):")
               Console.WriteLine("      {0}", sf.GetMethod())
            End If

            Console.WriteLine()
            Console.WriteLine("   ... throwing exception to next level ...")
            Console.WriteLine("-------------------------------------------------")
            Console.WriteLine()
            Throw e
         End Try
      End Sub 'Level5Method
   End Class 'ClassLevel5 


   Public Class ClassLevel6
      Public Sub Level6Method()
         Throw New Exception("An error occurred in the lowest internal class method.")
      End Sub 'Level6Method
   End Class 'ClassLevel6 

End Namespace 'StackFrameInternal


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Community Additions

ADD
Show:
© 2015 Microsoft