Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/puppetlabs/ruby-pwsh
A ruby gem for interacting with PowerShell
https://github.com/puppetlabs/ruby-pwsh
hacktoberfest module powershell ruby supported
Last synced: about 1 month ago
JSON representation
A ruby gem for interacting with PowerShell
- Host: GitHub
- URL: https://github.com/puppetlabs/ruby-pwsh
- Owner: puppetlabs
- License: mit
- Created: 2019-09-05T05:05:41.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-27T11:09:54.000Z (about 1 month ago)
- Last Synced: 2024-09-29T04:22:27.364Z (about 1 month ago)
- Topics: hacktoberfest, module, powershell, ruby, supported
- Language: Ruby
- Homepage:
- Size: 673 KB
- Stars: 15
- Watchers: 73
- Forks: 23
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# ruby-pwsh
[](https://github.com/puppetlabs/ruby-pwsh/blob/main/CODEOWNERS)
[](https://github.com/puppetlabs/ruby-pwsh/actions/workflows/ci.yml)
> _The PowerShell gem._
This gem enables you to execute PowerShell from within ruby without having to instantiate and tear down a PowerShell process for each command called.
It supports Windows PowerShell as well as PowerShell Core (and, soon, _just_ PowerShell) - if you're running *PowerShell v3+, this gem supports you.
The `Manager` class enables you to execute and interoperate with PowerShell from within ruby, leveraging the strengths of both languages as needed.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'ruby-pwsh'
```
And then execute:
```shell
bundle install
```
Or install it yourself as:
```shell
gem install ruby-pwsh
```
## Usage
Instantiating the manager can be done using some defaults:
```ruby
# Instantiate the manager for Windows PowerShell, using the default path and arguments
# Note that this takes a few seconds to instantiate.
posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# If you try to create another manager with the same arguments it will reuse the existing one.
ps = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# Note that this time the return is very fast.
# We can also use the defaults for PowerShell Core, though these only work if PowerShell is
# installed to the default paths - if it is installed anywhere else, you'll need to specify
# the full path to the pwsh executable.
pwsh = Pwsh::Manager.instance(Pwsh::Manager.pwsh_path, Pwsh::Manager.pwsh_args)
```
Execution can be done with relatively little additional work - pass the command string you want executed:
```ruby
# Instantiate the Manager:
posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# Pretty print the output of `$PSVersionTable` to validate the version of PowerShell running
# Note that the output is a hash with a few different keys, including stdout.
pp(posh.execute('$PSVersionTable'))
# Lets reduce the noise a little and retrieve just the version number:
# Note: We cast to a string because PSVersion is actually a Version object.
pp(posh.execute('[String]$PSVersionTable.PSVersion'))
# We could store this output to a ruby variable if we wanted, for further use:
ps_version = posh.execute('[String]$PSVersionTable.PSVersion')[:stdout].strip
pp("The PowerShell version of the currently running Manager is #{ps_version}")
```
## Reference
You can find the full reference documentation online, [here](https://rubydoc.info/gems/ruby-pwsh).
## Supported Operating Systems
The following platforms are supported:
- Windows
- CentOS
- Debian
- Fedora
- OSX
- RedHat
- Ubuntu
- AlmaLinux
## Limitations
- When PowerShell [Script Block Logging](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_logging_windows?view=powershell-7.4#enabling-script-block-logging) is enabled, data marked as sensitive in your manifest may appear in these logs as plain text. It is **highly recommended**, by both Puppet and Microsoft, that you also enable [Protected Event Logging](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_logging_windows?view=powershell-7.4#protected-event-logging) alongside this to encrypt the logs to protect this information.
## License
This codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.