1Debugging CoreFX on Windows 2========================== 3 4You can Debug .NET Core via Visual Studio or WinDBG. 5 6For Visual Studio debugging, follow the instructions at [Debugging tests in Visual Studio](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md) to run and debug tests. 7For bugs that cannot be reproduced within Visual Studio (certain low-probability race conditions, SafeHandle life-time problems, etc) you will need to use WinDBG. 8 9## Required Software 10 11WinDBG free download: 12 13* [WDK and WinDBG downloads](https://msdn.microsoft.com/en-us/windows/hardware/hh852365.aspx) 14 15Note: You can select the Standalone Debugging Tools for Windows or download only WinDBG via the WDK. 16 17## Prerequisites to Debugging with WinDBG 18 191. Build the entire repository. This ensures that all packages are downloaded and that you have up-to-date symbols. 20 212. Install WinDBG as post-mortem debugger 22As Administrator: 23 24``` 25windbg -I 26``` 27 28You may need to do this for both x64 and x86 versions. 29Any application that crashes should now automatically start a WinDBG session. 30 31## Debugging tests 32To run a single test from command line: 33 34* Locate the test binary folder based on the CSPROJ name. 35 36For example: `src\System.Net.Sockets\tests\Functional\System.Net.Sockets.Tests.csproj` will build and output binaries at `bin\tests\Windows_NT.AnyCPU.Debug\System.Net.Sockets.Tests\netcoreapp1.0`. 37 38* Execute the test 39 40Assuming that your repo is at `C:\corefx`: 41 42``` 43cd C:\corefx\bin\tests\Windows_NT.AnyCPU.Debug\System.Net.Sockets.Tests\netcoreapp1.0 44C:\corefx\bin\tests\Windows_NT.AnyCPU.Debug\System.Net.Sockets.Tests\netcoreapp1.0\CoreRun.exe xunit.console.netcore.exe System.Net.Sockets.Tests.dll -xml testResults.xml -notrait category=nonwindowstests -notrait category=OuterLoop -notrait category=failing 45``` 46 47* If the test crashes or encounteres a `Debugger.Launch()` method call, WinDBG will automatically start and attach to the `CoreRun.exe` process 48 49The following commands will properly configure the debugging extension and fix symbol and source-code references: 50 51``` 52.symfix 53.srcfix 54.reload 55!load C:\corefx\packages\runtime.win7-x64.Microsoft.NETCore.Runtime.CoreCLR\<version>\tools\sos 56``` 57 58_Important_: Pass in the correct path to your SOS extension discovered during the Prerequisites, step 2. 59 60Documentation on how to use the SOS extension is available on [MSDN](https://msdn.microsoft.com/en-us/library/bb190764\(v=vs.110\).aspx). 61 62For quick reference, type the following in WinDBG: 63 64``` 650:000> !sos.help 66``` 67 68## Traces 69 70In Windows, EventSource generated traces are collected via ETW using either logman or PerfView. 71 72### Using Logman 73[Logman](https://technet.microsoft.com/en-us/library/bb490956.aspx) ships with Windows and doesn't need to be downloaded or installed. 74Given that the ETW providers are dynamically generated and registered by .Net, you need to use the GUIDs and not the names whenever logman is used. 75 76#### Trace a single provider 77 78The following example shows how to trace Sockets: 79 80``` 81 logman -start SocketTrace -o %SYSTEMDRIVE%\sockets.etl -p "{e03c0352-f9c9-56ff-0ea7-b94ba8cabc6b}" -ets 82 83 // Repro 84 85 logman -stop SocketTrace -ets 86``` 87 88Logs are going to be placed in %SYSTEMDRIVE%\sockets.etl. 89 90#### Trace multiple providers 91 921. Create a file called providers.txt with the following contents: 93 94 ``` 95 "{e03c0352-f9c9-56ff-0ea7-b94ba8cabc6b}" 96 "{066c0e27-a02d-5a98-9a4d-078cc3b1a896}" 97 "{bdd9a83e-1929-5482-0d73-2fe5e1c0e16d}" 98 ``` 99 1002. Create the trace 101 102 ``` 103 logman create trace SystemNetTrace -o sn.etl -pf providers.txt 104 ``` 105 1063. Start the trace 107 108 ``` 109 logman start SystemNetTrace 110 ``` 111 1124. Repro the issue 1135. Stop the trace 114 115 ``` 116 logman stop SystemNetTrace 117 ``` 118 119 The trace can be restarted from step 3. 120 1216. Remove the trace profile if it's not going to be reused 122 ``` 123 logman delete SystemNetTrace 124 ``` 125 1267. The logs are placed in sn.etl. 127 128### Using PerfView 129 1301. Install [PerfView](http://www.microsoft.com/en-us/download/details.aspx?id=28567) 1312. Run PerfView as Administrator 1323. Press Alt+C to collect events 1334. Disable all other collection parameters 1345. Add Additional Providers (see below - Important: keep the "*" wildcard before the names.) 135 136![PerfView example](perfview_example.gif) 137 138### Built-in EventSource tracing 139 140The following EventSources are built-in to CoreFX. The ones that are not marked as [__TestCode__] can be enabled in production scenarios for log collection. 141 142#### Global 143* `*System.Diagnostics.Eventing.FrameworkEventSource {8E9F5090-2D75-4d03-8A81-E5AFBF85DAF1}`: Global EventSource used by multiple namespaces. 144 145#### System.Collections 146* `*System.Collections.Concurrent.ConcurrentCollectionsEventSource {35167F8E-49B2-4b96-AB86-435B59336B5E}`: Provides an event source for tracing Coordination Data Structure collection information. 147 148#### System.Linq 149* `*System.Linq.Parallel.PlinqEventSource {159eeeec-4a14-4418-a8fe-faabcd987887}`: Provides an event source for tracing PLINQ information. 150 151#### System.Net namespaces 152 153Helper scripts are available at https://github.com/dotnet/corefx/tree/master/src/Common/tests/Scripts/Tools. Run `net_startlog.cmd` as Administrator, run the application, then run `net_stoplog.cmd`. Open the `.etl` file with PerfView. 154 155* `*Microsoft-System-Net-Http {bdd9a83e-1929-5482-0d73-2fe5e1c0e16d}`: HTTP-related traces. 156* `*Microsoft-System-Net-Mail {42c8027b-f048-58d2-537d-a4a9d5ee7038}`: SMTP-related traces. 157* `*Microsoft-System-Net-NameResolution {5f302add-3825-520e-8fa0-627b206e2e7e}`: DNS-related traces. 158* `*Microsoft-System-Net-NetworkInformation {b8e42167-0eb2-5e39-97b5-acaca593d3a2}`: Network configuration-related traces. 159* `*Microsoft-System-Net-Ping {a771ec4a-7260-59ce-0475-db257437ed8c}`: Ping-related traces. 160* `*Microsoft-System-Net-Primitives {a9f9e4e1-0cf5-5005-b530-3d37959d5e84}`: Traces related to core networking-related types. 161* `*Microsoft-System-Net-Requests {3763dc7e-7046-5576-9041-5616e21cc2cf}`: WebRequest-related traces. 162* `*Microsoft-System-Net-Sockets {e03c0352-f9c9-56ff-0ea7-b94ba8cabc6b}`: Sockets-related traces. 163* `*Microsoft-System-Net-Security {066c0e27-a02d-5a98-9a4d-078cc3b1a896}`: Security-related traces. 164* `*Microsoft-System-Net-WebHeaderCollection {fd36452f-9f2b-5850-d212-6c436231e3dc}`: WebHeaderCollection-related traces. 165* `*Microsoft-System-Net-WebSockets-Client {71cddde3-cf58-52d5-094f-927828a09337}`: ClientWebSocket-related traces. 166* `*Microsoft-System-Net-TestLogging {18579866-5c03-5954-91ff-bdc63681458c}`: [__TestCode__] Test-code tracing (I/O async completions, performance test reporting). 167 168#### System.Threading 169* `*System.Threading.SynchronizationEventSource {EC631D38-466B-4290-9306-834971BA0217}`: Provides an event source for tracing Coordination Data Structure synchronization information. 170* `*System.Threading.Tasks.TplEventSource {2e5dba47-a3d2-4d16-8ee0-6671ffdcd7b5}`: Provides an event source for tracing TPL information. 171* `*System.Threading.Tasks.Parallel.EventSource`: Provides an event source for tracing TPL information. 172* `*System.Threading.Tasks.Dataflow.DataflowEventSource {16F53577-E41D-43D4-B47E-C17025BF4025}`: Provides an event source for tracing Dataflow information. 173 174## Notes 175* You can find the test invocation command-line by looking at the logs generated after the `msbuild /t:rebuild,test` within the test folder. 176