sdk/samples/FrameworkSamples/CLR/DebuggerViewsCS/readme.htm

   1 <html><head><META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8" /><META NAME="save" CONTENT="history" /><title xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">Debugger Views Application Sample</title><META NAME="Description" CONTENT="&#xD;&#xA;                    This sample demonstrates a feature introduced with Microsoft Visual Studio 2005, the capability to change the way you view a class in the debug windows. By applying new attributes such as the T:System.Diagnostics.DebuggerDisplay ..."></META><META NAME="MS.LOCALE" CONTENT="en-us" /><style>
   2 body
   3 {font-family:Verdana;font-size:medium;}
   4 div#mainSection, div#header
   5 {font-size:70%;width: 100%;}
   6 div#mainBody
   7 {font-size:90%;}
   8 div#mainSection div table
   9 {font-size: 100%;text-align: left;}
  10 span#nsrTitle
  11 {color:#003399;font-size:90%;font-weight:600;}
  12 div#header
  13 {background-color:#D4DFFF;}
  14 .heading
  15 {font-size:120%;color:#003399;}
  16 .subHeading
  17 {font-size:100%;margin-bottom:4;}
  18 li
  19 {margin-top:-2;margin-bottom:3;}
  20 p
  21 {margin-top:10;margin-bottom:5;}
  22 div.tableSection p
  23 {margin-top:1;margin-bottom:4;}
  24 div#mainSection table th
  25 {background-color:#EFEFF7;color:#000066;text-align:left;}
  26 div#mainSection table td
  27 {background-color:#F7F7FF;}
  28 div#mainSection table
  29 {margin-top:5px;margin-bottom: px;}
  30                         </style></head><body><div id="header"><table width="100%" id="topTable"></table></div><div id="mainSection"><div id="mainBody"><br /><font color="DarkGray">[This readme is a partial copy of the sample's topic in the SDK documentation.]</font><br /><font color="DarkGray" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"></font><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"></p><div class="introduction"><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  31                     This sample demonstrates a feature introduced with Microsoft Visual Studio 2005, the capability to change the way you view a class in the debug windows. By applying new attributes such as the <span sdata="cer" target="T:System.Diagnostics.DebuggerDisplayAttribute">DebuggerDisplayAttribute</span> to a class and its members, you can control how the value, type, and name columns are displayed for that type in the <span class="ui">Locals</span> debug window, and whether a value is shown, hidden, or expanded when viewed. This sample is currently available only in Microsoft Visual C# 2005.
  32                 </p><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  33                     For information about using the samples, see the following topics:
  34                 </p><ul xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><li><p><span sdata="link">How to: View and Download Samples</span></p></li><li><p><span sdata="link">How to: Set Sample Settings</span></p></li></ul><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  35                     This sample includes source files for three classes that contain the debugger attributes and source files that do not, as shown in the following table.
  36                 </p><div class="caption"></div><div class="tableSection"><table width="50%" cellspacing="2" cellpadding="5" frame="lhs" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><tr><th><p>
  37                     Files with debugger attributes
  38                 </p></th><th><p>
  39                     Files without debugger attributes
  40                 </p></th></tr><tr><td><p>
  41                     DebugAddress.cs
  42                 </p></td><td><p>
  43                     NonDebugAddress.cs
  44                 </p></td></tr><tr><td><p>
  45                     DebugCustomer.cs
  46                 </p></td><td><p>
  47                     NonDebugCustomer.cs
  48                 </p></td></tr><tr><td><p>
  49                     DebugCustomerName.cs
  50                 </p></td><td><p>
  51                     NonDebugCustomerName.cs
  52                 </p></td></tr></table></div><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  53                     The DebuggerViewsExample.cs file contains the entry point of the console application and is used by both sets of files. Uncomment the code in the debug versions (DebugAddress.cs, DebugCustomer.cs, and DebugCustomerName.cs) to run the sample.
  54                 </p></div><h3 class="procedureSubHeading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">To build the sample using the Command Prompt</h3><div class="subSection"><ol xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><li><p>
  55                     Open a Command Prompt window and navigate to the \CS subdirectory under the DebuggerViewsCS directory. For information about required settings and the SDK Command Prompt, see <span sdata="link">How to: Set Sample Settings</span>.
  56                 </p></li><li><p>
  57                     Type <span class="input">msbuild DebuggerViewsCS.sln</span> at the command line.
  58                 </p><div class="alert"><table width="100%" cellspacing="0" cellpadding="0"><tr><th align="left"><b>Note:</b></th></tr><tr><td><p>
  59                                          This sample demonstrates features of Visual Studio. You must start and run it within the Visual Studio debugging environment to view its output.
  60
  61
  62                                                         </p></td></tr></table></div></li></ol></div><h3 class="procedureSubHeading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">To build the sample using Visual Studio</h3><div class="subSection"><ol xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><li><p>
  63                     Open Windows Explorer and navigate to the \CS subdirectory under the DebuggerViewsCS directory.
  64                 </p></li><li><p>
  65                     Double-click <span class="input">DebuggerViewsCS.sln</span> to open the file in Visual Studio 2005.
  66                 </p></li><li><p>
  67                     On the <span class="ui">Build</span> menu, click <span class="ui">Build Solution</span>.
  68                 </p></li></ol></div><h3 class="procedureSubHeading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">To run the sample</h3><div class="subSection"><ol xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><li><p>
  69                     On the <span class="ui">View</span> menu of Visual Studio, click <span class="ui">Solution Explorer</span>.
  70                 </p></li><li><p>
  71                     In the <span class="ui">Solution Explorer</span> window, double-click <span class="input">DebuggerViewsExample.cs</span> to open the file in Visual Studio 2005.
  72                 </p></li><li><p>
  73                     On the <span class="ui">Project</span> menu, click <span class="ui">Show all files</span>.
  74                 </p></li><li><p>
  75                     Insert a breakpoint (press F9) on the line where the <span class="code">GetCustomers</span> method instantiates a variable of type <span class="code">Customer</span>, as shown here:
  76                 </p><p><span class="code">Customer c = new Customer(cn, Address.GetAddressById(customerAddresses, cn.Id));</span></p></li><li><p>
  77                     Press F5 to start and run the sample application in the Visual Studio 2005 debugging environment.
  78                 </p></li><li><p>
  79                     When the application breaks at the breakpoint, press F10 to step to the next line of code.
  80                 </p></li><li><p>
  81                     Observe current values in the <span class="ui">Locals</span> window by expanding the hierarchy of the application's properties, collections, and other objects. To display the <span class="ui">Locals</span> window, click <span class="ui">Windows</span> from the <span class="ui">Debug</span> menu and then click <span class="ui">Locals</span>.
  82                 </p></li><li><p>
  83                     On the <span class="ui">Debug</span> menu, click <span class="ui">Stop Debugging</span>, press Shift+F5, or click the icon in the Debugging toolbar, to stop code execution.
  84                 </p></li><li><p>
  85                     Uncomment the code in the three files whose names start with Debug. Then comment out the code in the three files whose names start with NonDebug, or select those three files in the <span class="ui">Solution Explorer</span> window, right-click, and then click <span class="ui">Exclude From Project</span>.
  86                 </p></li><li><p>
  87                     On the <span class="ui">Debug</span> menu, choose <span class="ui">Start</span> with the same breakpoint set. When the application breaks, observe the details in the <span class="ui">Locals</span> window values column, which now has additional information provided by debugging attributes.
  88                 </p></li></ol></div><h1 class="heading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><span onclick="ExpandCollapse(sectionToggle0)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(sectionToggle0, event)" tabindex="0">Remarks</span></h1><div id="sectionSection0" class="section"><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  89                     To provide an example of using a debugging attribute, the <span class="input">DebugCustomer.cs</span> file contains the following <span sdata="langKeyword" value="DebuggerDisplay"><span class="keyword">DebuggerDisplay</span></span> attribute for the <span class="code">CustomerName</span> class:
  90                 </p><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><span class="code">[DebuggerDisplay("{(FirstName == null) ? \"\":FirstName} {LastName} ==&gt; (Customer ID = {Id})")]</span></p><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
  91                     When debugging, this attribute displays the following value in the <span class="ui">Locals</span> window. The name <span class="code">cn</span> is an instance of a <span class="code">CustomerName</span> object.
  92                 </p><div class="caption"></div><div class="tableSection"><table width="50%" cellspacing="2" cellpadding="5" frame="lhs" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><tr><th><p>
  93                     Name
  94                 </p></th><th><p>
  95                     Value
  96                 </p></th><th><p>
  97                     Type
  98                 </p></th></tr><tr><td><p>
  99                     cn
 100                 </p></td><td><p>
 101                     "Sally" "HighBridge" ==&gt; (Customer ID = 12345)
 102                 </p></td><td><p>
 103                     Microsoft.Samples.CustomerName
 104                 </p></td></tr></table></div><p xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
 105                     Without the attribute, the <span class="ui">Locals</span> window displays the following:
 106                 </p><div class="caption"></div><div class="tableSection"><table width="50%" cellspacing="2" cellpadding="5" frame="lhs" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><tr><th><p>
 107                     Name
 108                 </p></th><th><p>
 109                     Value
 110                 </p></th><th><p>
 111                     Type
 112                 </p></th></tr><tr><td><p>
 113                     cn
 114                 </p></td><td><p>
 115                     {Microsoft.Samples.CustomerName}
 116                 </p></td><td><p>
 117                     Microsoft.Samples.CustomerName
 118                 </p></td></tr></table></div></div><h1 class="heading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt"><span onclick="ExpandCollapse(seeAlsoToggle)" style="cursor:default;" onkeypress="ExpandCollapse_CheckKey(seeAlsoToggle, event)" tabindex="0">See Also</span></h1><div id="seeAlsoSection" class="section"><h4 class="subHeading" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">Other Resources</h4><div class="seeAlsoStyle"><span sdata="link" xmlns:mshelp="http://msdn.microsoft.com/mshelp" xmlns:msxsl="urn:schemas-microsoft-com:xslt">Debugging in Visual Studio</span></div></div></div></div></body></html>