b4cb5e95a2
These changes provide the ability to debug remote running scripts started with the Invoke-Command cmdlet. The design is event based and provides new public events that allow subscribers to be notified when an Invoke-Command remote session is ready for debugging. Since Invoke-Command allows running scripts on multiple targets at once (fan-out) the notification event is raised for each remote session as it becomes ready for debugging. The subscriber to these events will be a script debugger implementation (such as PowerShell console, ISE, or VSCode) and will handle all debugging details such as simultaneously debugging multiple remote sessions at once in separate windows.
But these changes also include an internal implementation which is used by default if host debuggers don't want to handle the debugging details. This internal implementation is what PowerShell console, ISE uses so they can have this new behavior without having to modify their debugger implementations. The internal implementation serializes each remote session of Invoke-Command so that they can be debugged one at a time. The remote session debugger is "pushed" onto the internal debugger stack so that debugging transitions to the remote session. Existing debugging commands work so that the "quit" debugging command will stop the current remote session script from running and allow the next remote session to be debugged. Similarly the "continue" debugging command allows the script to continue running outside step mode and again go to the next remote session for debugging. The "stepout" debugging command steps out of all Invoke-Command remote sessions and lets the script continue to run for each remote session in parallel as they are normally run.
The purpose of Invoke-Command step-in remote debugging is allow seamless debugging of a local script that calls Invoke-Command on remote targets. But there is also a new Invoke-Command "-RemoteDebug" parameter that lets you Invoke-Command on the command line and have it drop directly into the debugger.
An example from the PowerShell command line looks like this:
```
PS C:\> C:\TestICM.ps1
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'Invoke-Command'
At C:\TestICM.ps1:2 char:1
+ Invoke-Command -cn $computerName,paulhig-3 -File c:\LinuxScript.ps1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[DBG]: PS C:\>> list
1: $computerName = "localhost"
2:* Invoke-Command -cn $computerName,paulhig-3 -File c:\LinuxScript.ps1
3: "Test Complete!"
[DBG]: PS C:\>> stepin
At line:1 char:1
+ Write-Output "Running script on Linux!"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[paulhig-3]:[DBG]: [Process:14072]: [Runspace5]: PS C:\Users\paulhi\Documents>
```
Notice that the debugger "stepin" command transitioned from local script debugging to debugging the remote session on computer "paulhig-3", as can be seen by the change in the debugger prompt.
You can also do this from the command line to drop directly into the debugger
```
Invoke-Command -cn localhost -Script $scriptblock -RemoteDebug
```
These changes also remove an old behavior that was incompatible with this new step-in feature. Previously if a remote session running script hit a break point it would stop in the debugger and go to the "disconnected session" state. This was to allow the user to reconnect using Enter-PSSession and then interactively debug the remote session script. This behavior has been removed and now the user needs to attach a debugger using the newer Debug-Runspace cmdlet.
|
||
|---|---|---|
| .github | ||
| .vscode | ||
| assets | ||
| demos | ||
| docker | ||
| docs | ||
| src | ||
| test | ||
| tools | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .spelling | ||
| .travis.yml | ||
| appveyor.yml | ||
| build.psm1 | ||
| build.sh | ||
| CHANGELOG.md | ||
| codecov.yml | ||
| global.json | ||
| LICENSE.txt | ||
| license_thirdparty_proprietary.txt | ||
| nuget.config | ||
| powershell.sln | ||
| README.md | ||
| ThirdPartyNotices.txt | ||
PowerShell
Welcome to the PowerShell GitHub Community! PowerShell is a cross-platform (Windows, Linux, and macOS) automation and configuration tool/framework that works well with your existing tools and is optimized for dealing with structured data (e.g. JSON, CSV, XML, etc.), REST APIs, and object models. It includes a command-line shell, an associated scripting language and a framework for processing cmdlets.
New to PowerShell?
If you are new to PowerShell and would like to learn more, we recommend reviewing the getting started documentation.
Get PowerShell
You can download and install a PowerShell package for any of the following platforms.
| Platform | Downloads | How to Install |
|---|---|---|
| Windows 10 / Server 2016 (x64) | .msi | Instructions |
| Windows 8.1 / Server 2012 R2 (x64) | .msi | Instructions |
| Windows 7 (x64) | .msi | Instructions |
| Windows 7 (x86) | .msi | Instructions |
| Ubuntu 16.04 | .deb | Instructions |
| Ubuntu 14.04 | .deb | Instructions |
| CentOS 7 | .rpm | Instructions |
| Many Linux distributions | [.AppImage][rl-ai] | Instructions |
| macOS 10.11 | [.pkg][rl-macos] | Instructions |
| Docker | Instructions |
[rl-ai]: TODO: Post link when available [rl-macos]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.16/powershell-6.0.0-alpha.16.pkg
To install a specific version, visit releases.
Chat Room
Want to chat with other members of the PowerShell community?
We have a Gitter Room which you can join below.
There is also the community driven PowerShell Slack Team which you can sign up for at Slack Signup.
Building the Repository
| Linux | Windows | macOS |
|---|---|---|
| Instructions | Instructions | Instructions |
If you have any problems building, please consult the developer FAQ.
Build status of master branches
| AppVeyor (Windows) | Travis CI (Linux / macOS) |
|---|---|
 |
Build status of nightly builds
| AppVeyor (Windows) | Travis CI (Linux / macOS) | Code Coverage Status |
|---|---|---|
 |
 |
Downloading the Source Code
The PowerShell repository has a number of other repositories embedded as submodules.
To make things easy, you can just clone recursively:
git clone --recursive https://github.com/PowerShell/PowerShell.git
If you already cloned but forgot to use --recursive, you can update submodules manually:
git submodule update --init
See working with the PowerShell repository for more information.
Developing and Contributing
Please see the Contribution Guide for how to develop and contribute.
If you have any problems, please consult the known issues, developer FAQ, and GitHub issues. If you do not see your problem captured, please file a new issue and follow the provided template. If you are developing .NET Core C# applications targeting PowerShell Core, please check out our FAQ to learn more about the PowerShell SDK NuGet package.
Also make sure to check out our PowerShell-RFC repository for request-for-comments (RFC) documents to submit and give comments on proposed and future designs.
Legal and Licensing
PowerShell is licensed under the MIT license.
Governance
Governance policy for PowerShell project is described here.
Code of Conduct
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.