Class: WinRM::Transport::CommandExecutor

Inherits:
Object
  • Object
show all
Includes:
Logging
Defined in:
lib/winrm/transport/command_executor.rb

Overview

Object which can execute multiple commands and Powershell scripts in one shared remote shell session. The maximum number of commands per shell is determined by interrogating the remote host when the session is opened and the remote shell is automatically recycled before the threshold is reached.

Author:

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Logging

#debug, #log_subject

Constructor Details

#initialize(service, logger = nil, closer = nil) ⇒ CommandExecutor

Creates a CommandExecutor given a ‘WinRM::WinRMWebService` object.

Parameters:

  • service (WinRM::WinRMWebService) —

    a winrm web service object

  • logger (#debug, #info) (defaults to: nil) —

    an optional logger/ui object that responds to ‘#debug` and `#info` (default: `nil`)

  • closer (ShellCloser) (defaults to: nil) —

    an optional object to automatically close the active open remote shell when CommandExecutor garbarge collects



54
55
56
57
58
59
 
# File 'lib/winrm/transport/command_executor.rb', line 54

def initialize(service, logger = nil, closer = nil)
  @service        = service
  @logger         = logger
  @closer         = closer
  @command_count  = 0
end

Instance Attribute Details

#max_commands ⇒ Integer? (readonly)

Returns the safe maximum number of commands that can be executed in one remote shell session, or ‘nil` if the threshold has not yet been determined.

Returns:

  • (Integer, nil) —

    the safe maximum number of commands that can be executed in one remote shell session, or ‘nil` if the threshold has not yet been determined



40
41
42
 
# File 'lib/winrm/transport/command_executor.rb', line 40

def max_commands
  @max_commands
end

#shell ⇒ String? (readonly)

Returns the identifier for the current open remote shell session, or ‘nil` if the session is not open.

Returns:

  • (String, nil) —

    the identifier for the current open remote shell session, or ‘nil` if the session is not open



44
45
46
 
# File 'lib/winrm/transport/command_executor.rb', line 44

def shell
  @shell
end

Instance Method Details

#close ⇒ Object

Closes the open remote shell session. This method can be called multiple times, even if there is no open session.



63
64
65
66
67
68
69
 
# File 'lib/winrm/transport/command_executor.rb', line 63

def close
  return if shell.nil?

  service.close_shell(shell)
  remove_finalizer
  @shell = nil
end

#open ⇒ String

Opens a remote shell session for reuse. The maxiumum command-per-shell threshold is also determined the first time this method is invoked and cached for later invocations.

Returns:

  • (String) —

    the remote shell session indentifier



76
77
78
79
80
81
82
83
 
# File 'lib/winrm/transport/command_executor.rb', line 76

def open
  close
  @shell = service.open_shell
  add_finalizer(shell)
  @command_count = 0
  determine_max_commands unless max_commands
  shell
end

#run_cmd(command, arguments = []) {|stdout, stderr| ... } ⇒ WinRM::Output

Runs a CMD command.

Parameters:

  • command (String) —

    the command to run on the remote system

  • arguments (Array<String>) (defaults to: []) —

    arguments to the command

Yields:

  • (stdout, stderr) —

    yields more live access the standard output and standard error streams as they are returns, if streaming behavior is desired

Returns:

  • (WinRM::Output) —

    output object with stdout, stderr, and exit code



94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/winrm/transport/command_executor.rb', line 94

def run_cmd(command, arguments = [], &block)
  reset if command_count_exceeded?
  ensure_open_shell!

  @command_count += 1
  result = nil
  service.run_command(shell, command, arguments) do |command_id|
    result = service.get_command_output(shell, command_id, &block)
  end
  result
end

#run_powershell_script(script_file) {|stdout, stderr| ... } ⇒ WinRM::Output

Run a Powershell script that resides on the local box.

Parameters:

  • script_file (IO, String) —

    an IO reference for reading the Powershell script or the actual file contents

Yields:

  • (stdout, stderr) —

    yields more live access the standard output and standard error streams as they are returns, if streaming behavior is desired

Returns:

  • (WinRM::Output) —

    output object with stdout, stderr, and exit code



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/winrm/transport/command_executor.rb', line 115

def run_powershell_script(script_file, &block)
  # this code looks overly compact in an attempt to limit local
  # variable assignments that may contain large strings and
  # consequently bloat the Ruby VM
  run_cmd(
    "powershell",
    [
      "-encodedCommand",
      ::WinRM::PowershellScript.new(
        script_file.is_a?(IO) ? script_file.read : script_file
      ).encoded
    ],
    &block
  )
end