Export (0) Print
Expand All

ConditionalAttribute Class

Indicates to compilers that a method is callable if a specified preprocessing identifier is applied to the method.

For a list of all members of this type, see ConditionalAttribute Members.

System.Object
   System.Attribute
      System.Diagnostics.ConditionalAttribute

[Visual Basic]
<AttributeUsage(AttributeTargets.Method)>
<Serializable>
NotInheritable Public Class ConditionalAttribute
   Inherits Attribute
[C#]
[AttributeUsage(AttributeTargets.Method)]
[Serializable]
public sealed class ConditionalAttribute : Attribute
[C++]
[AttributeUsage(AttributeTargets::Method)]
[Serializable]
public __gc __sealed class ConditionalAttribute : public
   Attribute
[JScript]
public
   AttributeUsage(AttributeTargets.Method)
 Serializable
class ConditionalAttribute extends Attribute

Thread Safety

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

Remarks

The ConditionalAttribute supports the conditional methods defined in the Trace and Debug classes.

Methods decorated with the ConditionalAttribute attribute are always compiled into Microsoft intermediate language (MSIL), but calls to the methods can not be made at run time. If the method has arguments, they are type-checked at run time, but not evaluated.

Note   Visual Studio .NET compiles Release builds with the TRACE conditional compilation constant defined, and Debug builds with both the DEBUG and TRACE constants defined, by default. For command-line builds, you must specify all conditional compilation constants.
Note   A ConditionalAttribute that has an associated ConditionString can be attached to the definition of a method, creating a conditional method. Thereafter, when a compiler encounters a call to that method, it can choose to ignore the call unless a compilation variable is defined at the site of the call, with a value that matches in a case-sensitive manner the ConditionString supplied to the ConditionalAttribute.

Compilers might provide several techniques to define such compilation variables, such as:

  • Compiler command-line switches (for example,/define:DEBUG).
  • Environment variables in the operating system shell (for example, SET DEBUG=1).
  • Pragmas in the source code (for example, #define DEBUG, to define the compilation variable, or #undef DEBUG to undefine it).

CLS-compliant compilers are permitted to ignore the ConditionalAttribute.

For more information about using attributes, see Extending Metadata Using Attributes.

Example

[Visual Basic, C#, C++] The following console application example demonstrates the use of ConditionalAttribute with a particular compiler that supports the use of this attribute.

[Visual Basic] 
Imports System
Imports System.Diagnostics
Imports Microsoft.VisualBasic

Public Class Module1

    Public Shared Sub Main()
        Console.WriteLine("Console.WriteLine is always displayed.")

        Dim myWriter As New TextWriterTraceListener(System.Console.Out)
        Debug.Listeners.Add(myWriter)

        Dim A As New Module1()
        A.Sub1()
    End Sub      'Main

    <Conditional("CONDITION1"), Conditional("CONDITION2")> _
    Public Sub Sub1()
        Sub2()
        Sub3()
    End Sub

    <Conditional("CONDITION1")> _
    Public Sub Sub2()
        Debug.WriteLine("CONDITION1 and DEBUG are defined")
    End Sub

    <Conditional("CONDITION2")> _
    Public Sub Sub3()
        Debug.WriteLine("CONDITION2 and DEBUG are defined")
        Trace.WriteLine("CONDITION2 and TRACE are defined")
    End Sub

End Class
' This console application produces the following output when compiled as shown.
'
'C:\samples\ConditionalAttributeSample\CASVB>vbc /out:CASVB.exe /d:CONDITION1=1 /r:System.dll /target:exe CAS.vb
'Microsoft (R) Visual Basic .NET Compiler version 7.00.9429
'for Microsoft (R) .NET Framework version 1.00.3529
'Copyright (C) Microsoft Corporation 1987-2001. All rights reserved.


'C:\samples\ConditionalAttributeSample\CASVB>CASVB
'
'Console.WriteLine is always displayed.

'C:\samples\ConditionalAttributeSample\CASVB>vbc /out:CASVB.exe /d:CONDITION1=1,DEBUG=1 /r:System.dll /target:exe CAS.vb
'Microsoft (R) Visual Basic .NET Compiler version 7.00.9429
'for Microsoft (R) .NET Framework version 1.00.3529
'Copyright (C) Microsoft Corporation 1987-2001. All rights reserved.


'C:\samples\ConditionalAttributeSample\CASVB>CASVB
'
'Console.WriteLine is always displayed.
'CONDITION1 and DEBUG are defined

'C:\samples\ConditionalAttributeSample\CASVB>vbc /out:CASVB.exe /d:CONDITION1=1,CONDITION2=1,DEBUG=1 /r:System.dll /target:exe CAS.vb
'Microsoft (R) Visual Basic .NET Compiler version 7.00.9429
'for Microsoft (R) .NET Framework version 1.00.3529
'Copyright (C) Microsoft Corporation 1987-2001. All rights reserved.


'C:\samples\ConditionalAttributeSample\CASVB>CASVB
'
'Console.WriteLine is always displayed.
'CONDITION1 and DEBUG are defined
'CONDITION2 and DEBUG are defined

[C#] 
using System;
using System.Diagnostics;

class Class1
{
    [STAThread]
    static void Main(string[] args)
    {                
        TextWriterTraceListener myWriter = 
            new TextWriterTraceListener(System.Console.Out);
        Debug.Listeners.Add(myWriter);
        Console.WriteLine("Console.WriteLine is always displayed");
        Method1();
        Method2();
    }
    
    [Conditional("CONDITION1")]
    public static void Method1()
    {
        Debug.Write("Method1 - DEBUG and CONDITION1 are specified\n");
        Trace.Write("Method1 - TRACE and CONDITION1 are specified\n");
    }
    
    [Conditional("CONDITION1"), Conditional("CONDITION2")]    
    public static void Method2()
    {
        Debug.Write("Method2 - DEBUG, CONDITION1 or CONDITION2 are specified\n");
    }
}

/*
This console application produces the following output when compiled as shown.

C:\samples\ConditionalAttributeSample\CASCS>csc /target:exe /d:CONDITION1,DEBUG,TRACE /out:CASCS.exe CAS.cs
Microsoft (R) Visual C# .NET Compiler version 7.00.9429
for Microsoft (R) .NET Framework version 1.0.3529
Copyright (C) Microsoft Corporation 2001. All rights reserved.

C:\PP\samples\ConditionalAttributeSample\CASCS>CASCS

Console.WriteLine is always displayed
Method1 - DEBUG and CONDITION1 are specified
Method1 - TRACE and CONDITION1 are specified
Method2 - DEBUG, CONDITION1 or CONDITION2 are specified

C:\samples\ConditionalAttributeSample\CASCS>csc /target:exe /d:CONDITION2,DEBUG,TRACE /out:CASCS.exe CAS.cs
Microsoft (R) Visual C# .NET Compiler version 7.00.9429
for Microsoft (R) .NET Framework version 1.0.3529
Copyright (C) Microsoft Corporation 2001. All rights reserved.

C:\samples\ConditionalAttributeSample\CASCS>CASCS

Console.WriteLine is always displayed
Method2 - DEBUG, CONDITION1 or CONDITION2 are specified

C:\samples\ConditionalAttributeSample\CASCS>csc /target:exe /d:CONDITION1,TRACE /out:CASCS.exe CAS.cs
Microsoft (R) Visual C# .NET Compiler version 7.00.9429
for Microsoft (R) .NET Framework version 1.0.3529
Copyright (C) Microsoft Corporation 2001. All rights reserved.

C:\samples\ConditionalAttributeSample\CASCS>CASCS

Console.WriteLine is always displayed
Method1 - TRACE and CONDITION1 are specified

*/

[C++] 
/*
C++ with Managed Extensions uses the C++ standard preprocessor.  Use the 
preprocessor directives rather than this attribute.
*/

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Diagnostics

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

Assembly: Mscorlib (in Mscorlib.dll)

See Also

ConditionalAttribute Members | System.Diagnostics Namespace

Show:
© 2014 Microsoft