Runtime 偵錯工具 (Cordbg.exe)

更新：2007 年 11 月

Runtime 偵錯工具可以協助工具廠商和應用程式開發人員尋找並修復以 .NET Framework Common Language Runtime 為目標的程式之錯誤。這個工具使用執行階段偵錯 API 來提供偵錯服務。Cordbg.exe 的原始程式碼已經透過範例應用程式的形式推出。開發人員可以測試該程式碼，以便學會如何使用偵錯服務。目前您只能以 Cordbg.exe 來偵錯 Managed 程式碼；不支援偵錯 Unmanaged 程式碼。

請使用底下語法的第一行，啟動 Cordbg.exe 工作階段。使用 Cordbg.exe 工作階段內(cordbg) 提示的第二行。

cordbg [ProgramName[Program arguments]][optional arguments ]
command [command arguments]

參數

命令	描述
ap[pdomainenum] [option]	列舉所有在目前處理序 (Process) 中的應用程式定義域、組件 (Assembly) 和模組。如果沒有指定 option 引數，命令會列出所有在目前處理序中的應用程式定義域、組件和模組。在中斷連結或附加之後，您必須指定 go 命令以繼續執行。 option 引數可以是下列其中一項： attach 列出處理序中的應用程式定義域，並提示使用者選取要附加至的目標定義域 detach 列出處理序中的應用程式定義域，並提示使用者選取要中斷連結來源的定義域 0 列出處理序中的應用程式定義域 1 列出處理序中的應用程式定義域和組件
as[sociatesource] {s|b breakpoint id} filename	將指定的檔案名稱與目前的堆疊框架指標 (選項 s) 或指定的中斷點 (選項 b) 產生關聯。
a[ttach] pid	附加偵錯工具至執行中的處理序。Cordbg.exe 會刪除目前正在偵錯的程式 (如果有的話)，並嘗試附加至 pid 引數所指定的處理序。處理序識別碼 pid 可以是十進位或十六進位格式。
b[reak] [[file:] line number] | [[ class::] function [:offset]]	設定或顯示中斷點。如果沒有指定任何引數，工具會顯示目前中斷點清單，否則，它會在指定位置設定中斷點。您可以在目前原始程式檔 (Source File) 中的某一行號、在完整原始程式檔中的某一行號，或在類別和選擇性位移 (Offset) 所限定的方法中，設定中斷點。 中斷點持續在整個工作階段執行。您可以以使用 break 一樣的方式使用 stop 命令。 如果指定的中斷點位置無法繫結至程式碼，Cordbg.exe 會將中斷點顯示成「未繫結」。當中斷點是未繫結時，表示尚未載入中斷點位置的基礎程式碼。有多種合理的原因會造成這種情形發生，例如檔案或類別名稱拼錯 (它們的名稱是有大小寫區分的)。另外，如果在執行應用程式前設定中斷點，它們將會是未繫結的。當載入實際的程式碼時，中斷點會變成繫結的。當偵錯工具載入模組時，它會嘗試自動將每一個未繫結的中斷點重新繫結。
ca[tch] [event]	顯示事件類型清單，或使指定的事件類型停止偵錯工具。如果沒有指定引數，工具會顯示事件類型清單，其中會停止偵錯工具的事件類型標示成「on」，而被略過的事件類型標示成「off」。如果指定引數，當指定類型的事件發生時，偵錯工具會停止。根據預設值，偵錯工具只會在未處理的例外狀況 (Exception) 事件上停止 (也就是第二個可能發生的例外狀況)。停止偵錯工具的事件類型會持續在整個工作階段執行。若要使偵錯工具略過事件的特定類型，使用 ignore 命令。 事件引數可以是下列其中之一： e[xceptions] [exception type] 工具會將例外狀況類型加入到要捕捉的最有可能發生的例外狀況清單。如果您不指定例外狀況類型，工具將會捕捉所有最有可能發生的例外狀況。例外狀況類型要區分大小寫，例如 System.ArgumentException。 u[nhandled] 未處理的例外狀況 c[lass] 類別載入事件 m[odule] 模組載入事件 t[hread] 執行緒啟動事件
conn[ect] machine_nameport	用於智慧型裝置專案。 連接到執行 .NET Compact Framework 應用程式的遠端裝置。 參數 定義 machine_name 必要項。遠端電腦的名稱或 IP 位址 Port 必要項。用來連接到遠端電腦的連接埠
cont [count]	繼續執行程式。如果沒有指定引數，程式會繼續執行一次。如果您指定引數，程式會繼續執行指定的次數。當類別載入事件、例外狀況或中斷點停止偵錯工具時，這個命令對繼續執行程式很有幫助。您可以使用和 cont 一樣的方式使用 go 命令。
del[ete] [breakpoint id, ...]	刪除中斷點。如果沒有指定任何引數，工具會刪除所有目前的中斷點。如果指定一或多個 breakpoint id 引數，工具會刪除指定的中斷點。您可以使用 break 或 stop 命令來取得中斷點識別項。您可以使用和 delete 一樣的方式使用 remove 命令。
de[tach]	從目前處理序中斷偵錯工具的連結。處理序會自動地繼續並且執行，就如同偵錯工具沒有附加到它一樣。
dis[assemble] [0xaddress][{+|-} delta] [line count]	顯示目前指令指標或 address 的原生反組譯指令 (如果有指定)。預設顯示的指令數量是 5。如果有指定 linecount 引數，則工具會在目前指令指標或位址的前後顯示指定數目的額外指令。最後一個使用的 linecount 會變成目前工作階段的預設值。如果指定 delta，指定的號碼將會被加入目前的指令指標或指定的位址，以開始進行反向組譯。
d[own] [count]	將堆疊框架指標朝堆疊向下移動至由目前框架所呼叫的框架以做檢查。如果沒有指定引數，堆疊框架指標會向下移動一個框架。如果指定引數，堆疊框架指標會以指定的框架數向下移動。如果可以取得原始程式層級資訊，工具會顯示框架的原始程式行。這個命令經常配合 up 命令一起使用。
du[mp] address [count]	根據偵錯工具的模式 (請參閱 mode)，以十六進位或十進位格式的輸出傾印記憶體的區塊。address 引數是記憶體區塊的位址。count 引數是要傾印的位元組數。
ex[it]	停止目前的處理序並結束偵錯工具。您可以以使用 exit 一樣的方式使用 quit 命令。
f[unceval] [class::] function [ arg0arg1 ...argn]	評估目前執行緒上的指定函式。工具會將新物件存放到變數 $result，並且可以用它來進行後續的評估。有效的引數僅限於其他變數、4 位元組的整數以及常數 Null、True 和 False。 注意事項： 對於成員函式而言，第一個引數必須是成員函式所屬之類別或衍生類別的物件。
g[o] [count]	請參閱 cont。
h[elp] [command ...]	顯示指定命令的描述。如果指定任何引數，Cordbg.exe 會顯示偵錯工具命令的清單。您可以使用 help 一樣的方式使用 ? 命令。
ig[nore] [event]	顯示事件類型清單，或者讓指定的事件類型被偵錯工具略過。如果未指定 event 引數，則工具會顯示事件型別的清單，其中被忽略的事件型別會標示成 "off"，而停止偵錯工具的事件型別則會標示為 "on"。如果指定引數，工具會略過指定類型的事件。若要設定事件類型以停止偵錯工具，請使用 catch 命令。 event 引數可以是下列其中一個事件型別： e[xceptions] [exception type] 工具會將例外狀況類型加入到要忽略的最有可能發生的例外狀況清單。如果您不指定例外狀況類型，工具將會忽略所有最有可能發生的例外狀況。例外狀況類型要區分大小寫，例如 System.ArgumentException。 u[nhandled] 未處理的例外狀況 c[lass] 類別載入事件 m[odule] 模組載入事件 t[hread] 執行緒啟動事件
i[n] [count]	請參閱 step。
k[ill]	停止目前的處理序。偵錯工具保持作用中，以處理進一步的命令。
l[ist] option	顯示模組、類別或全域函式的清單。 option 引數可以是下列其中一項： mod 列出處理序中的載入模組 cl 列出處理序中的載入類別 fu 列出處理序中每個模組的全域函式
m[ode] [[mode name {0|1} ]	設定並顯示不同偵錯工具功能的偵錯工具模式。若要設定數值，請指定 mode name 以及 1 代表 "on" 或 0 代表 "off"。如果沒有指定引數，工具會顯示目前模式設定值的清單。模式會在 Cordbg.exe 執行之間保存在 Windows 登錄中。如需詳細資訊，請參閱偵錯工具模式引數表。
newo[bj] class	使用目前執行緒建立新物件。工具會將新物件存放到變數 $result，並且可以用它來進行後續的評估。
newobjncclass	使用目前的執行緒建立新物件，而不在物件上執行建構函式。這個新物件會初始化為零。工具會將新物件存放到變數 $result，並且可以用它來進行後續的評估。
news[tr] string	使用目前執行緒建立新字串。工具會將新物件存放到變數 $result，並且可以用它來進行後續的評估。
n[ext] [count]	逐步執行程式到下一個原始程式行，而且不進入函式呼叫。如果沒有指定引數，工具會依一個原始程式行逐步執行。如果指定引數，工具會依指定的行數逐步執行。您可以使用 next 一樣的方式使用 so 命令。
ns[ingle] [count]	依一或多個指令逐步執行程式，略過所有的函式呼叫。如果沒有指定引數，工具會依一個指令逐步執行。如果指定 count 引數，工具會依指定的指令數逐步執行。
o[ut] [count]	跳離目前函式逐步執行程式。如果沒有指定引數，工具會執行跳離目前函式一次。如果指定引數，工具會依指定的次數執行跳離函式。
pa[th] [new path]	顯示或設定用來搜尋原始程式檔和偵錯符號的路徑。如果沒有指定引數，工具會顯示目前的路徑。如果指定 newpath 引數，它會變成用來搜尋原始程式檔和偵錯符號的新路徑。這個路徑會保存 (Persist) 在 Windows 登錄中的工作階段之間。
p[rint] [variable name]	顯示一或多個區域變數和其值。如果沒有指定引數，工具會顯示所有區域變數和其值。如果指定引數，工具只會顯示指定區域變數的值。如需詳細資訊，請參閱＜範例＞章節的使用 print 命令。
pro[cessenum]	列舉每一個處理序中的所有 Managed 處理序和應用程式定義域。
q[uit]	請參閱 exit。
ref[reshsource] [source file]	重新載入指定的原始程式檔的原始程式碼。要被重新載入的原始程式檔必須是目前執行中程式的一部分。在以 path 命令設定原始程式檔路徑後，您可以使用 refreshsource 命令來產生遺漏的原始程式碼。
regd[efault] [force]	將預設的 Just-in-Time (JIT) 偵錯工具設定為 Cordbg.exe。如果已經註冊其他偵錯工具，這個命令就不會進行任何作業。使用 force 引數來覆寫已註冊的 JIT 偵錯工具。
reg[isters]	顯示目前執行緒的暫存器內容。
rem[ove] [breakpoint id, ...]	請參閱 delete。
re[sume] [~] [tid]	當偵錯工具繼續執行時，繼續 tid 引數所指定的執行緒。如果使用 ~ 語法，工具會繼續除了指定的執行緒之外的所有執行緒。如果沒有指定引數，這個命令不會產生作用。
r[un] [executable [args]]	刪除目前處理序 (如果有的話)，並啟動新的處理序。如果沒有指定 executable 引數，這個命令會執行先前以 run 命令執行的程式。如果指定 executable 引數，工具會使用選擇性提供的 args 來執行指定的程式。如果 Cordbg.exe 略過類別載入、模組載入和執行緒啟動事件 (如預設所示)，程式會在主要執行緒的第一個可執行的指令上停止。
setvariable value	將指定的 variable 值設定為指定的 value。這個值可以是常值 (Literal) 或其他變數。如需詳細資訊，請參閱＜範例＞章節的使用 set 命令。
setipline number	設定下一個陳述式 (Statement) 以執行到指定的 line number。
sh[ow] [count]	顯示原始程式碼行。如果沒有指定引數，工具會在目前原始程式碼行的前後顯示五行原始程式碼。如果指定引數，工具會在目前行的前後顯示指定的行數。最後一個指定的 count 會變成目前工作階段的預設值。
si [<count>]	請參閱 step。
so [<count>]	請參閱 next。
ss[ingle] [count]	依一或多個指令逐步執行程式，而且逐步執行函式呼叫。如果沒有指定引數，工具僅會依一個指令逐步執行。如果指定引數，工具會依指定的逐步執行數執行。
s[tep] [count]	逐步執行程式到下一個原始程式行，而且逐步執行函式呼叫。如果沒有指定引數，程式會逐步執行到下一行。如果指定引數，程式會依指定的行數逐步執行。您可以使用 step 一樣的方式使用 si 命令或 in 命令。
stop [[file:] line number] | [[class::] function[:offset]] | [=0xaddress]	請參閱 break。
su[spend] [~] [tid]	當偵錯工具繼續執行時，暫止 tid 引數所指定的執行緒。如果使用 ~ 語法，工具會暫止除了指定的執行緒之外的所有執行緒。如果沒有指定引數，這個命令不會產生作用。
t[hreads] [tid]	顯示執行序清單，或設定目前執行緒。如果沒有指定引數，工具會顯示所有仍運作中且已執行 Managed 程式碼之執行緒的清單。如果指定引數，工具會將目前的執行緒設定到指定的執行緒。
up [count]	將堆疊框架指標朝堆疊向上移動至呼叫目前框架的框架以做檢查。如果沒有指定引數，堆疊框架指標會向上移動一個框架。如果指定引數，堆疊框架指標會以指定的框架數向上移動。如果可以取得原始程式層級資訊，工具會顯示框架的原始程式行。
w[here] [count]	顯示目前執行緒的堆疊追蹤。如果沒有指定引數，工具會顯示完整的堆疊追蹤。如果指定引數，工具會顯示指定的堆疊框架數。
wr[itememory] address count byte, ...	寫入指定的位元組到目標處理序。address 引數會指定要寫入位元組的位置。count 引數指定要寫入的位元組數。byte 引數會指定要寫入處理序的項目。如果清單中的位元組數小於 count 引數，工具會包裝位元組清單，並再次複製。如果清單中的位元組數大於 count 引數，工具會忽略額外的位元組。
wt	依原生指令逐步執行應用程式，並從目前指令開始且在離開時列印呼叫樹狀圖。工具會以呼叫樹狀圖列印已在每個函式中執行的原生指令數。當工具到達原本執行命令之函式的傳回指令時，停止追蹤。在追蹤結束時，工具會列印已執行指令的總數。這個命令與 NT 符號偵錯工具的 wt 命令極為相似，您可以用它來進行基本效能分析。目前工具只計算 Managed 程式碼。
xmodulename !string_to_look_for	顯示指定模組中與 string_to_look_for 引數所指定的模式比對相符的符號。您可以在 string_to_look_for 引數中使用星號 (*) 字元來指示工具符合任何項目。工具會忽略在 * 字元之後的任何字元。
? [command ...]	請參閱 help。
>filename	將所有已執行的命令寫入指定的 filename。如果沒有指定 filename，命令會停止寫入命令至檔案。
<filename	從指定的 filename 讀取並執行命令。

注意事項：
Cordbg.exe 命令有區分大小寫。此外，有不少命令具有同義字，表示可以使用數個命令的任何一個來產生相同的結果。例如，您可以使用 break 或 stop 命令來設定中斷點。

模式引數

您可以使用最少數目的必要字元指定模式引數，而讓模式成為唯一的。例如 "mode m 1" 就相當於 "mode moduleloads 1"。

引數	描述
AppDomainLoads	顯示應用程式定義域和組件載入事件
ClassLoads	顯示類別載入事件
DumpMemoryInBytes	顯示記憶體內容為位元組或 DWORD
EmbededCLR	將偵錯工具設定為在智慧型裝置上執行的目標 .NET Compact Framework 應用程式。若要控制這項設定，請指定 1 為 on，或指定 0 為 off。
EnhanceDiag	顯示增強診斷資訊
HexDisplay	以十六進位或十進位格式顯示數字
ILNatPrint	以 Microsoft Intermediate Language (MSIL) 或原生相對語言或是兩者顯示位移
ISAll	逐步執行所有的攔截器
ISClinit	逐步執行類別初始設定式
ISExceptF	逐步執行例外狀況篩選器
ISInt	逐步執行使用者攔截器
ISPolicy	逐步執行內容原則
ISSec	逐步執行安全攔截器
JitOptimizations	指定 JIT 編譯是否要產生容易偵錯的程式碼
LoggingMessages	顯示 Managed 程式碼記錄檔訊息
ModuleLoads	顯示模組載入事件
SeparateConsole	指定已進行偵錯的處理序是否取得自己的主控台
ShowArgs	顯示堆疊追蹤中的方法引數
ShowModules	顯示堆疊追蹤中的模組名稱
ShowStaticsOnPrint	顯示物件的靜態欄位
ShowSuperClassOnPrint	顯示物件的基底類別內容
USAll	逐步執行所有未對應的停止位置
USEpi	逐步執行方法終解
USPro	逐步執行方法初構
USUnmanaged	逐步執行 Unmanaged 程式碼

備註

您應該使用編譯器專用的旗標來編譯要偵錯的應用程式，這些旗標會使編譯器產生偵錯符號。如需這些旗標的詳細資訊，請參閱編譯器的文件。您仍然可以偵錯最佳化的應用程式，但是有些偵錯資訊將會遺失。例如，許多區域變數會看不見，而且有些原始程式行也會不正確。

編譯應用程式之後，請在命令提示字元輸入 cordbg 來啟動偵錯工作階段，如下列範例所示。

D:\Program Files\FrameworkSDK\Bin>cordbg
Microsoft (R) Common Language Runtime Test Debugger Shell. Version 2000.14.2100.0, Copyright (c) Microsoft Corp. 1998-2000
(cordbg)

(cordbg) 提示指示您正在使用偵錯工具。

一旦您使用了偵錯工具，使用命令和適當的引數來叫用 (Invoke) 所需的功能。

當您從命令列啟動偵錯工作階段時，也可以提供要進行偵錯的應用程式名稱、程式引數和選擇性引數。Cordbg.exe 選擇性引數相同於您在 Cordbg.exe 所用的命令，不過必須在它們前面加上驚歎號 (!) 字元。在 ! 字元前面加上反斜線 (\) 字元，您可以使用 ! 字元做為字串中的常值。當使用 x 命令時，這是必要的。

如果命令的數字引數是以前置字元 0x 開頭，Cordbg.exe 便會假設這個引數是十六進位格式。否則，它會假設此引數為十進位格式。

Cordbg.exe 中的大部分命令都可以用星號 (*) 做為字首，讓命令對處理序中的每一個 Managed 執行緒執行一次。命令是在每個執行緒的範圍內執行。用星號做為字首最有用處的命令就是 w[here] 命令。例如，*w 會使每個 Managed 執行緒的堆疊追蹤被列印出來。

如需執行階段的偵錯服務的詳細資訊，請參閱「啟用設定檔和偵錯」規格。此外，工具開發人員應該參閱隨附於 Windows Software Development Kit (SDK) 之 Tools Developers Guide 資料夾下的「偵錯概觀」和「偵錯參考」規格。

範例

啟動 Cordbg.exe 工作階段

下列命令會以程式引數 a 和 2 啟動應用程式 MyApplication.exe 的 Cordbg.exe 工作階段和後續的選擇性命令：在 MyApplication.cs 中的 42 行設定一個中斷點；繼續應用程式；在 MyApplication.exe 中符合字串 "'SomeString'" 的地方顯示符號。

cordbg MyApplication.exe a 2 !b MyApplication.cs:42 !g !x MyApplication.exe\!SomeString

在 Cordbg.exe 工作階段內部執行可執行檔

從 Cordbg.exe 工作階段之內輸入的下列命令 (於 (cordbg) 提示下) 會以程式引數 a 和 2 來執行可執行檔 MyApplication.exe。

run MyApplication.exe a 2

使用 print 命令

下列命令示範您可以使用點標記法與 print 命令，指定物件內的變數。

print obj.var1
print obj1.obj2.var1

如果類別擴充另一個類別，print 命令會顯示指定類別的欄位和基底類別的欄位。例如，如果 m1 類別有 a、b 和 c 欄位，而 m2 類別擴充 m1 且有 d、e 和 f 欄位，則 m2 的 myInstance 執行個體 (Instance) 將列印如下。

myInstance = <addr> <m2>
      a = 1
      b = 2
      c = 3
      m2::d = 4
      m2::e = 5
      m2::f = 6

您可以將含有類別名稱的變數名稱前置，來指定類別靜態變數，如下所示。

print MyClass::StaticVar1
print System::Boolean::True

陣列索引必須是簡單運算式。下列陣列索引使用於 print 命令時有效。

print arr[1]
print arr[i]
print arr1[arr2[1]]
print md[1][5][myObject.a]

下列陣列索引使用於 print 命令時無效，因為陣列索引不是簡單運算式。

print arr[i + 1]
print arr[i + 2]

使用 set 命令

使用 set 命令時，指派給指定變數的值可以是常值或另一個變數。下列是 set 命令的有效用法。

set int1 0x2a
set float1 3.1415
set char1 'a'
set bool1 true
set obj1 0x12345678
set obj1 obj2
set obj1.m_length[obj1.m_height] obj3.m_length[2]

請參閱

參考

.NET Framework 工具

SDK 命令提示字元