Managed 程式碼中的判斷提示Assertions in Managed Code

判斷提示 (或 Assert 陳述式) 可以測試條件,您可以將此條件指定為 Assert 陳述式的引數。An assertion, or Assert statement, tests a condition, which you specify as an argument to the Assert statement. 如果條件判斷值為 true,則不會執行任何動作。If the condition evaluates to true, no action occurs. 如果條件判斷值為 false,則判斷提示會失敗。If the condition evaluates to false, the assertion fails. 如果您是以偵錯組建執行,則您的程式將進入中斷模式。If you are running with a debug build, your program enters break mode.

本主題內容In this topic

System.Diagnostics 命名空間中的判斷提示Asserts in the System.Diagnostics Namespace

Debug.Assert 方法The Debug.Assert method

Debug.Assert 的副作用Side effects of Debug.Assert

追蹤和偵錯需求Trace and Debug Requirements

Assert 引數Assert arguments

自訂 Assert 的行為Customizing Assert behavior

在組態檔中設定判斷提示Setting assertions in configuration files

System.Diagnostics 命名空間中的判斷提示Asserts in the System.Diagnostics Namespace

在 Visual Basic 和 Visual C# 中,您可以從位於 Assert 命名空間中的 DebugTrace 使用 System.Diagnostics 方法。In Visual Basic and Visual C#, you can use the Assert method from either Debug or Trace, which are in the System.Diagnostics namespace. Debug 類別方法未包含在程式的發行版本中,因此不會增加發行程式碼的大小或減緩其速度。Debug class methods are not included in a Release version of your program, so they do not increase the size or reduce the speed of your release code.

C++ 不支援 Debug 類別方法。C++ does not support the Debug class methods. 您可以使用 Trace 類別搭配條件式編譯得到相同的效果,例如 #ifdef DEBUG... #endifYou can achieve the same effect by using the Trace class with conditional compilation, such as #ifdef DEBUG... #endif.

本主題內容In this topic

Debug.Assert 方法The Debug.Assert method

您可以隨意使用 System.Diagnostics.Debug.Assert 方法測試程式碼正確時應為 true 的條件。Use the System.Diagnostics.Debug.Assert method freely to test conditions that should hold true if your code is correct. 例如,假設您撰寫了整數除法函式。For example, suppose you have written an integer divide function. 依據數學規則,除數不可為零。By the rules of mathematics, the divisor can never be zero. 您可以使用判斷提示測試這項條件:You might test this using an assertion:

Function IntegerDivide(ByVal dividend As Integer, ByVal divisor As Integer) As Integer
    Debug.Assert(divisor <> 0)
    Return CInt(dividend / divisor)
End Function
int IntegerDivide ( int dividend , int divisor )
    { Debug.Assert ( divisor != 0 );
        return ( dividend / divisor ); }

您在偵錯工具下執行此程式碼時,將會評估判斷提示陳述式,但是在發行版本中則不會進行比較,因此不會有額外的負荷。When you run this code under the debugger, the assertion statement is evaluated, but in the Release version, the comparison is not made, so there is no additional overhead.

以下是另一個範例。Here is another example. 您擁有實作檢查帳戶的類別,如下所示:You have a class that implements a checking account, as follows:

Dim amount, balance As Double
balance = savingsAccount.balance
Debug.Assert(amount <= balance)
SavingsAccount.Withdraw(amount)
float balance = savingsAccount.Balance;
Debug.Assert ( amount <= balance );
savingsAccount.Withdraw ( amount );

在您從帳戶中提領現金之前,想要先確認帳戶餘額足夠供應您預備提領的金額。Before you withdraw money from the account, you want to make sure that the account balance is sufficient to cover the amount you are preparing to withdraw. 您可以撰寫判斷提示檢查餘額:You might write an assertion to check the balance:

Dim amount, balance As Double
balance = savingsAccount.balance
Trace.Assert(amount <= balance)
SavingsAccount.Withdraw(amount)
float balance = savingsAccount.Balance;
Trace.Assert ( amount <= balance );
savingsAccount.Withdraw ( amount );

請注意,當您建立程式碼的發行版本時,對 System.Diagnostics.Debug.Assert 方法的呼叫就會消失。Note that calls to the System.Diagnostics.Debug.Assert method disappear when you create a Release version of your code. 這表示,在發行版本內,檢查餘額的呼叫將會消失。That means that the call that checks the balance disappears in the Release version. 若要解決這個問題,您應該將 System.Diagnostics.Debug.Assert 取代為 System.Diagnostics.Trace.Assert,後者不會在發行版本中消失:To solve this problem, you should replace System.Diagnostics.Debug.Assert with System.Diagnostics.Trace.Assert, which does not disappear in the Release version:

呼叫 System.Diagnostics.Trace.Assert 與呼叫 System.Diagnostics.Debug.Assert 不同,前者會增加發行版本的額外負荷。Calls to System.Diagnostics.Trace.Assert add overhead to your Release version, unlike calls to System.Diagnostics.Debug.Assert.

本主題內容In this topic

Debug.Assert 的副作用Side effects of Debug.Assert

當您使用 System.Diagnostics.Debug.Assert 時,請確認 Assert 內的任何程式碼都不會在 Assert 移除後變更程式的結果。When you use System.Diagnostics.Debug.Assert, make sure that any code inside Assert does not change the results of the program if Assert is removed. 否則,您可能意外引入只會出現在程式發行版本中的 Bug。Otherwise, you might accidentally introduce a bug that only shows up in the Release version of your program. 處理包含函式或程序呼叫的判斷提示時要特別小心,例如下面的範例:Be especially careful about asserts that contain function or procedure calls, such as the following example:

' unsafe code
Debug.Assert (meas(i) <> 0 )
// unsafe code
Debug.Assert (meas(i) != 0 );

這個 System.Diagnostics.Debug.Assert 用法乍看之下好像很安全,但假設每次呼叫 meas 函式時都會更新計數器。This use of System.Diagnostics.Debug.Assert might appear safe at first glance, but suppose the function meas updates a counter each time it is called. 當您建置發行版本時,將會去除這個 meas 呼叫,如此計數器就不會更新。When you build the Release version, this call to meas is eliminated, so the counter does not get updated. 這是具有副作用的函式範例。This is an example of a function with a side effect. 去除具有副作用的函式呼叫將導致只出現在發行版本中的 Bug。Eliminating a call to a function that has side effects could result in a bug that only appears in the Release version. 若要避免這類問題,請不要在 System.Diagnostics.Debug.Assert 陳述式中放置函式呼叫。To avoid such problems, do not place function calls in a System.Diagnostics.Debug.Assert statement. 請改用暫存變數:Use a temporary variable instead:

temp = meas( i )
Debug.Assert (temp <> 0)
temp = meas( i );
Debug.Assert ( temp != 0 );

即使是使用 System.Diagnostics.Trace.Assert 時,您仍然會想要避免將函式呼叫放入 Assert 陳述式中。Even when you use System.Diagnostics.Trace.Assert, you might still want to avoid placing function calls inside an Assert statement. 這類呼叫應該是安全的,因為發行組建中不會去除 System.Diagnostics.Trace.Assert 陳述式。Such calls should be safe, because System.Diagnostics.Trace.Assert statements are not eliminated in a Release build. 但是,如果您養成不使用這類建構的習慣,使用 System.Diagnostics.Debug.Assert 時就比較不會犯錯。However, if you avoid such constructs as a matter of habit, you are less likely to make a mistake when you use System.Diagnostics.Debug.Assert.

本主題內容In this topic

追蹤和偵錯需求Trace and Debug Requirements

如果您使用 Visual StudioVisual Studio 精靈建立專案,根據預設,TRACE 符號會同時在發行和偵錯組態中定義。If you create your project using the Visual StudioVisual Studio wizards, the TRACE symbol is defined by default in both Release and Debug configurations. 根據預設,DEBUG 符號只會在偵錯組建中定義。The DEBUG symbol is defined by default only in the Debug build.

否則為了要讓 Trace 方法運作,您程式的原始程式檔頂端就必須要有下列其中一個項目:Otherwise, for Trace methods to work, your program must have one of the following at the top of the source file:

  • #Const TRACE = True (在 Visual Basic 中)#Const TRACE = True in Visual Basic

  • #define TRACE (在 Visual C# 和 C++ 中)#define TRACE in Visual C# and C++

    或者,您的程式必須是使用 TRACE 選項所建置:Or your program must be built with the TRACE option:

  • /d:TRACE=True (在 Visual Basic 中)/d:TRACE=True in Visual Basic

  • /d:TRACE (在 Visual C# 和 C++ 中)/d:TRACE in Visual C# and C++

    如果您需要在 C# 或 Visual Basic 的發行組建中使用 Debug 方法,則必須在發行組態中定義 DEBUG 符號。If you need to use the Debug methods in a C# or Visual Basic Release build, you must define the DEBUG symbol in your Release configuration.

    C++ 不支援 Debug 類別方法。C++ does not support the Debug class methods. 您可以使用 Trace 類別搭配條件式編譯得到相同的效果,例如 #ifdef DEBUG... #endifYou can achieve the same effect by using the Trace class with conditional compilation, such as #ifdef DEBUG... #endif. 您可以在 [<專案> 屬性頁] 對話方塊中定義這些符號。You can define these symbols in the <Project> Property Pages dialog box. 如需詳細資訊,請參閱變更 Visual Basic 偵錯組態的專案設定變更 C 或 C++ 偵錯組態的專案設定For more information, see Changing Project Settings for a Visual Basic Debug Configuration or Changing Project Settings for a C or C++ Debug Configuration.

Assert 引數Assert arguments

System.Diagnostics.Trace.AssertSystem.Diagnostics.Debug.Assert 最多可接受三個引數。System.Diagnostics.Trace.Assert and System.Diagnostics.Debug.Assert take up to three arguments. 第一個引數是強制性的,代表您要檢查的條件。The first argument, which is mandatory, is the condition you want to check. 如果您只使用一個引數呼叫 System.Diagnostics.Trace.Assert(Boolean)System.Diagnostics.Debug.Assert(Boolean)Assert 方法將會檢查該條件,而如果結果為 false,則會將呼叫堆疊的內容輸出至 [輸出] 視窗。If you call System.Diagnostics.Trace.Assert(Boolean) or System.Diagnostics.Debug.Assert(Boolean) with only one argument, the Assert method checks the condition and, if the result is false, outputs the contents of the call stack to the Output window. 下列範例將示範 System.Diagnostics.Trace.Assert(Boolean)System.Diagnostics.Debug.Assert(Boolean)The following example shows System.Diagnostics.Trace.Assert(Boolean) and System.Diagnostics.Debug.Assert(Boolean):

Debug.Assert(stacksize > 0)
Trace.Assert(stacksize > 0)
Debug.Assert ( stacksize > 0 );
Trace.Assert ( stacksize > 0 );

若出現第二個和第三個引數,這兩個引數必須為字串。The second and third arguments, if present, must be strings. 如果您使用兩個或三個引數呼叫 System.Diagnostics.Trace.AssertSystem.Diagnostics.Debug.Assert,第一個引數就是條件。If you call System.Diagnostics.Trace.Assert or System.Diagnostics.Debug.Assert with two or three arguments, the first argument is a condition. 方法會檢查條件,如果結果是 false,就會輸出第二個和第三個字串。The method checks the condition and, if the result is false, outputs the second string and third strings. 下列範例將示範搭配兩個引數使用的 System.Diagnostics.Debug.Assert(Boolean, String)System.Diagnostics.Trace.Assert(Boolean, String)The following example shows System.Diagnostics.Debug.Assert(Boolean, String) and System.Diagnostics.Trace.Assert(Boolean, String) used with two arguments:

Debug.Assert(stacksize > 0, "Out of stack space")
Trace.Assert(stacksize > 0, "Out of stack space")
Debug.Assert ( stacksize > 0, "Out of stack space" );
Trace.Assert ( stacksize > 0, "Out of stack space" );

下列範例將示範 AssertAssertThe following example shows Assert and Assert:

Debug.Assert(stacksize > 0, "Out of stack space. Bytes left:" , Format(size, "G"))
Trace.Assert(stacksize > 0, "Out of stack space. Bytes left:" , Format(size, "G"))
Trace.Assert(stacksize > 0, "Out of stack space. Bytes left:", "inctemp failed on third call" )
Debug.Assert ( stacksize > 100, "Out of stack space" , "Failed in inctemp" );
Trace.Assert ( stacksize > 0, "Out of stack space", "Failed in inctemp" );

本主題內容In this topic

自訂 Assert 的行為Customizing Assert behavior

如果您以使用者介面模式執行應用程式,Assert 方法將在條件失敗時顯示 [判斷提示失敗] 對話方塊。If you run your application in user-interface mode, the Assert method displays the Assertion Failed dialog box when the condition fails. 判斷提示失敗時發生的動作是由 ListenersListeners 屬性所控制。The actions that occur when an assertion fails are controlled by the Listeners or Listeners property.

自訂輸出行為的方法包括將 TraceListener 物件加入至 Listeners 集合內、從 TraceListener 集合內移除 Listeners,或覆寫現有 System.Diagnostics.TraceListener.FailTraceListener 方法,讓它擁有不同的行為。You can customize the output behavior by adding a TraceListener object to the Listeners collection, by removing a TraceListener from the Listeners collection, or by overriding the System.Diagnostics.TraceListener.Fail method of an existing TraceListener to make it behave differently.

例如,您可以覆寫 System.Diagnostics.TraceListener.Fail 方法以寫入事件記錄檔,而非顯示 [判斷提示失敗] 對話方塊。For example, you could override the System.Diagnostics.TraceListener.Fail method to write to an event log instead of displaying the Assertion Failed dialog box.

若要以這種方式自訂輸出,您的程式必須包含接聽程式,而且必須繼承自 TraceListener,並覆寫其 System.Diagnostics.TraceListener.Fail 方法。To customize the output in this way, your program must contain a listener, and you must inherit from TraceListener and override its System.Diagnostics.TraceListener.Fail method.

如需詳細資訊,請參閱追蹤接聽項For more Information, see Trace Listeners.

本主題內容In this topic

在組態檔中設定判斷提示Setting assertions in configuration files

您可以在程式組態檔中設定判斷提示,就像在程式碼中一樣。You can set assertions in your program configuration file as well as in your code. 如需詳細資訊,請參閱 System.Diagnostics.Trace.AssertSystem.Diagnostics.Debug.AssertFor more information, see System.Diagnostics.Trace.Assert or System.Diagnostics.Debug.Assert.

請參閱See also