Skip to content

Latest commit

 

History

History
211 lines (174 loc) · 7.4 KB

cli.md

File metadata and controls

211 lines (174 loc) · 7.4 KB

Using NetCoreDbg with CLI (Command Line Interface)

Fast start

To start debugger and run program with one command just type

$ netcoredbg --interpreter=cli -- dotnet hello.dll param1 param2

Note: to debug Release build of dlls with pdbs Just-My-Code should be disabled, see below.

Command reference

command    alias  args   
--------------------------
backtrace  bt     [all]    Print backtrace info.
break      b      <loc>    Set breakpoint at specified location, where the
                           location might be source_file_name:line or function name.
                           Optional, module name also could be provided as part
                           of location: module.dll!source_file_name:line
catch                      Set exception breakpoints.
continue   c               Continue debugging after stop/pause.
delete     clear  <num>    Delete breakpoint with specified number.
detach                     Detach from the debugged process.
disable                    Disable breakpoint N.
enable                     Enable breakpoint N.
file              <file>   load executable file to debug.
finish                     Continue execution till end of the current function.
interrupt                  Interrupt program execution, stop all threads.
list       l               List source code lines, 5 by default.
next       n               Step program, through function calls.
print      p      <expr>   Print variable value or evaluate an expression.
quit       q               Quit the debugger.
run        r               Start debugged program.
attach                     Attach to the debugged process.
detach                     Detach from the debugged process.
step       s               Step program until a different source line.
source            <file>   Read commands from a file.
wait                       Wait until debugee stops (in async. mode)
set               args...  Set miscellaneous options (see 'help set')

command    alias  args   
---------------------------
info              <topic>  Show misc. things about the program being debugged.
save              args...  Save misc. things to the files.
help              [topic]  Show help on specified topic or print
                           this help message (if no argument specified).

Preparing debug information

For showing classes and function names by NCDB required to have PDB files. But for showing source code of debuggee application also need to add tag EmbedAllSources to csproj file:

<EmbedAllSources>true</EmbedAllSources>

Start debugger

To start the debugger in CLI mode just type

$ netcoredbg --interpreter=cli

To load the debugging program file command with the name of an executable used to start assembly as argument should be used, for example dotnet:

ncdb> file dotnet

The name of the assembly for debugging and all the required parameters could be set with "set args" command, for example:

ncdb> set args hello.dll param1 param2

Debugging Release build of dlls

To debug Release build of dlls with pdbs Just-My-Code should be disabled:

ncdb> set just-my-code 0

Running debugging program

Now the debugger is ready to run your assembly. The debugging information is not loaded at this moment and will be available after debuggee program starts. But breakpoints could be set here using break command (see below). Keep in mind that all breakpoints set here will have "pending" status until "hit entry point" event will occur. Debugging information is provided by *.pdb file. If the debugger can't find the correspoinding *.pdb the debugging will not be possible, even hitting the entry point will not pause the debuggee process. Example:

ncdb> run
thread created, id: 15498

library loaded: /usr/share/dotnet/shared/Microsoft.NETCore.App/5.0.11/System.Private.CoreLib.dll
no symbols loaded, base address: 0x7f69fe5b0000, size: 9470976(0x908400)

library loaded: /home/user/src/sample/bin/Debug/net5.0/sample.dll
symbols loaded, base address: 0x7f6a79e01000, size: 4608(0x1200)
breakpoint modified,  Breakpoint 2 at foo()
breakpoint modified,  Breakpoint 1 at Main()

library loaded: /usr/share/dotnet/shared/Microsoft.NETCore.App/5.0.11/System.Runtime.dll
no symbols loaded, base address: 0x7f69ff000000, size: 230912(0x38600)

library loaded: /usr/share/dotnet/shared/Microsoft.NETCore.App/5.0.11/System.Console.dll
no symbols loaded, base address: 0x7f69ff070000, size: 376832(0x5c000)

stopped, reason: breakpoint 1 hit, thread id: 15498, stopped threads: all, times= 0, frame={sample.Program.Main() at /home/user/src/sample/Program.cs:13

Setting breakpoints

There are set 2 kinds of breakpoints - by function name and by filename:line-number. Examples:

Set breakpoint at a line 66 of Program.cs:

ncdb> break Program.cs:66
^done, Breakpoint 1 at /home/oleg/work/hello/Program.cs:66

Set breakpoint at function func2():

ncdb> b func2
^done, Breakpoint 2 at func2()

Set breakpoint at func1(int i) member function of Program class of hello namespace:

ncdb> b hello.Program.func1(int)
^done, Breakpoint 3 at func1()

Deleting breakpoints

To delete breakpoint just type delete and it number:

ncdb> delete 2
^done

Showing all breakpoints

info command with break argument shows all breakpoints. Information about hits and if this break point was resolved also will be shown:

ncdb> info break
    #  Enb  Rslvd  Hits       Source/Function
---------------------------------------------
    1    y  y      1          Main
    2    y  y      1          foo

Continue execution

To continue program's execution type:

ncdb> continue

or

ncdb> c

Stepping

There are 3 commands available for stepping your program: step, next and finish.

step command executes program until it reaches the next source line. next command executes program until it reaches the source line below the current line. finish command continues execution until the current stack frame returns.

Print variables

To print a value of a variable type print or p and a variable's name, for example:

ncdb> print i
^done,
i = 3
cli> p s.a
^done,
s.a = 2

Command history

The CLI remembers the history of the commands which user used during the current and previous sessions. It's possible to move back and forth in the history pressing and arrows. Also possible to edit the command line and search history in forward -s or reverse -r directions.

Showing source code

NCDB allows to show source code of debuggee program, while execution stopped at breakpoint:

ncdb> list
8	    		Console.WriteLine("foo!!!");
9	    	}
10	
11	    	static int A = 10;
12	        static void Main(string[] args)
13	        {
14	            Console.WriteLine("Hello World!");
15	            foo();
16	        }
17	    }

list command also support various arguments:

list ,XX - print 10 lines ending with XX

list XX, - print 10 lines starting with XX line

list XX,YY - print lines from XX to YY

list - - print 10 lines just before the last printed

list + - print 10 lines just after the last printed

list XX - print 10 lines with XX centered

Showing back trace

To see stack of calls at the current break point type:

ncdb> bt
#0 sample.Program.foo() at /home/alexander/src/sample/Program.cs:7
#1 sample.Program.Main() at /home/alexander/src/sample/Program.cs:15

Quit

To leave debugging session type:

ncdb> quit