github.com/direktiv/go-powershell@v0.0.0-20220309043221-9f9747a0a631/README.md (about)

     1  # go-powershell
     2  
     3  _NOTE: this repository has been recently (2020-11-18) moved out of the github.com/rancher org to github.com/k3s-io
     4  supporting the [acceptance of K3s as a CNCF sandbox project](https://github.com/cncf/toc/pull/447)_.
     5  ---
     6  
     7  This package is inspired by [jPowerShell](https://github.com/profesorfalken/jPowerShell)
     8  and allows one to run and remote-control a PowerShell session. Use this if you
     9  don't have a static script that you want to execute, bur rather run dynamic
    10  commands.
    11  
    12  ## Installation
    13  
    14      go get github.com/k3s-io/go-powershell
    15  
    16  ## Usage
    17  
    18  To start a PowerShell shell, you need a backend. Backends take care of starting
    19  and controlling the actual powershell.exe process. In most cases, you will want
    20  to use the Local backend, which just uses ``os/exec`` to start the process.
    21  
    22  ```go
    23  package main
    24  
    25  import (
    26  	"fmt"
    27  
    28  	ps "github.com/k3s-io/go-powershell"
    29  	"github.com/k3s-io/go-powershell/backend"
    30  )
    31  
    32  func main() {
    33  	// choose a backend
    34  	back := &backend.Local{}
    35  
    36  	// start a local powershell process
    37  	shell, err := ps.New(back)
    38  	if err != nil {
    39  		panic(err)
    40  	}
    41  	defer shell.Exit()
    42  
    43  	// ... and interact with it
    44  	stdout, stderr, err := shell.Execute("Get-WmiObject -Class Win32_Processor")
    45  	if err != nil {
    46  		panic(err)
    47  	}
    48  
    49  	fmt.Println(stdout)
    50  }
    51  ```
    52  
    53  ## Remote Sessions
    54  
    55  You can use an existing PS shell to use PSSession cmdlets to connect to remote
    56  computers. Instead of manually handling that, you can use the Session middleware,
    57  which takes care of authentication. Note that you can still use the "raw" shell
    58  to execute commands on the computer where the powershell host process is running.
    59  
    60  ```go
    61  package main
    62  
    63  import (
    64  	"fmt"
    65  
    66  	ps "github.com/k3s-io/go-powershell"
    67  	"github.com/k3s-io/go-powershell/backend"
    68  	"github.com/k3s-io/go-powershell/middleware"
    69  )
    70  
    71  func main() {
    72  	// choose a backend
    73  	back := &backend.Local{}
    74  
    75  	// start a local powershell process
    76  	shell, err := ps.New(back)
    77  	if err != nil {
    78  		panic(err)
    79  	}
    80  
    81  	// prepare remote session configuration
    82  	config := middleware.NewSessionConfig()
    83  	config.ComputerName = "remote-pc-1"
    84  
    85  	// create a new shell by wrapping the existing one in the session middleware
    86  	session, err := middleware.NewSession(shell, config)
    87  	if err != nil {
    88  		panic(err)
    89  	}
    90  	defer session.Exit() // will also close the underlying ps shell!
    91  
    92  	// everything run via the session is run on the remote machine
    93  	stdout, stderr, err = session.Execute("Get-WmiObject -Class Win32_Processor")
    94  	if err != nil {
    95  		panic(err)
    96  	}
    97  
    98  	fmt.Println(stdout)
    99  }
   100  ```
   101  
   102  Note that a single shell instance is not safe for concurrent use, as are remote
   103  sessions. You can have as many remote sessions using the same shell as you like,
   104  but you must execute commands serially. If you need concurrency, you can just
   105  spawn multiple PowerShell processes (i.e. call ``.New()`` multiple times).
   106  
   107  Also, note that all commands that you execute are wrapped in special echo
   108  statements to delimit the stdout/stderr streams. After ``.Execute()``ing a command,
   109  you can therefore not access ``$LastExitCode`` anymore and expect meaningful
   110  results.
   111  
   112  ## License
   113  
   114  MIT, see LICENSE file.