PowerShell/docs/debugging/README.md

Debugging
=========

VS Code
=======

[Experimental .NET Core Debugging in VS Code][core-debug] enables
cross-platform debugging with the [Visual Studio Code][vscode] editor.
This is made possible by the [OmniSharp][] extension for VS Code.

Please review their [detailed instructions][vscclrdebugger]. In
addition to being able to build PowerShell, you need:

- C# Extension for VS Code installed
- `powershell` executable in your path (self-host if not on Windows)

The committed `.vscode` folder in the root of this repository contains
the `launch.json` and `tasks.json` files which provide Core PowerShell
debugging configurations and a build task.

The "build" task will run `Start-PSBuild`.

The ".NET Core Launch" configuration will build and start a
`powershell` process, with `justMyCode` disabled, and `stopAtEntry`
enabled. The debugger is highly experimental, so if it does not break
at `Main`, try again.

Note that the debugger does not yet provide `stdin` handles, so once
`ReadKey` is called in the `ReadLine` loop, `System.Console` will
throw exceptions. The options around this are 1) provide
`[ "-c", "... ; exit" ]` to the "Launch" configuration's `args` so
that the `ReadLine` listener is never called, 2) ignore the exceptions
and only debug code before the listener, or 3) use the "Attach"
configuration.

The ".NET Core Attach" configuration will start listening for a
process named `powershell`, and will attach to it. If you need more
fine grained control, replace `processName` with `processId` and
provide a PID. (Please be careful not to commit such a change).

Important Note
--------------

Debugging is very sensitive to the versions of our .NET Core packages, VS Code,
and the C# extension.

- Use the VS Code [Insiders][] build
- Use the latest pre-release of the [C# extension][]
- Refer to the pre-release [documentation][]

[core-debug]: https://blogs.msdn.microsoft.com/visualstudioalm/2016/03/10/experimental-net-core-debugging-in-vs-code/
[vscode]: https://code.visualstudio.com/
[OmniSharp]: https://github.com/OmniSharp/omnisharp-vscode
[vscclrdebugger]: http://aka.ms/vscclrdebugger
[insiders]: https://code.visualstudio.com/insiders
[C# extension]: https://github.com/OmniSharp/omnisharp-vscode/releases
[documentation]: https://github.com/OmniSharp/omnisharp-vscode/pull/157

PowerShell
==========

The `Trace-Command` cmdlet can be used to enable tracing of certain PowerShell
subsystems. Use `Get-TraceSource` for a list of tracers:

* CmdletProviderClasses
* CommandDiscovery
* CommandSearch
* ConsoleHost
* ConsoleHostRunspaceInit
* ConsoleHostUserInterface
* ConsoleLineOutput
* DisplayDataQuery
* ETS
* FileSystemProvider
* FormatFileLoading
* FormatViewBinding
* LocationGlobber
* MemberResolution
* Modules
* MshSnapinLoadUnload
* ParameterBinderBase
* ParameterBinderController
* ParameterBinding
* PathResolution
* PSDriveInfo
* PSSnapInLoadUnload
* RunspaceInit
* SessionState
* TypeConversion
* TypeMatch

Then trace it like this:

```powershell
Trace-Command -Expression { Get-ChildItem . } -Name PathResolution -PSHost
```

The `-PSHost` specifies the sink, in this case the console host, so we can see
the tracing messages.

LLDB with SOS plugin
====================

The `./tools/debug.sh` script can be used to launch PowerShell inside of LLDB
with the SOS plugin provided by .NET Core. This provides an additional way to
debug PowerShell on Linux, but VS Code is recommended for a better user
experience (and its single-stepping capabilities).

The script is self-documented and contains a link to the
[CoreCLR debugging help][clr-debug] .

[clr-debug]: https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md#debugging-coreclr-on-linux

corehost
========

The native executable prouduced by .NET CLI will produce trace output
if launched with `COREHOST_TRACE=1 ./powershell`.

CoreCLR PAL
===========

The native code in the CLR has debug channels to selectively output
information to the console. These are controlled by the
`PAL_DBG_CHANNELS`, e.g., `export PAL_DBG_CHANNELS="+all.all"`, as
detailed in the `dbgmsg.h` [header][].

[header]: https://github.com/dotnet/coreclr/blob/release/1.0.0-rc2/src/pal/src/include/pal/dbgmsg.h