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