Struct WinrmClient 

pub struct WinrmClient { /* private fields */ }

Async WinRM (WS-Management) HTTP client.

Manages the full remote-shell lifecycle: create a shell, execute commands, poll output, signal termination, and delete the shell. Each high-level method (run_command, run_powershell) handles this lifecycle automatically; the lower-level methods are available for callers that need finer control.

The client is cheaply cloneable via the inner reqwest::Client connection pool but is not Clone itself – create one per logical session.

Implementations

impl WinrmClient

pub fn new( config: WinrmConfig, credentials: WinrmCredentials, ) -> Result<Self, WinrmError>

Create a new WinrmClient from the given configuration and credentials.

Builds the underlying HTTP client with the configured timeouts and TLS settings. Returns WinrmError::Http if the HTTP client cannot be constructed (e.g. invalid TLS configuration).

pub fn builder(config: WinrmConfig) -> WinrmClientBuilder

Create a WinrmClientBuilder for constructing a client with the typestate builder pattern.

pub async fn create_shell(&self, host: &str) -> Result<String, WinrmError>

Create a new remote shell on the given host. Returns the shell ID.

The shell uses UTF-8 codepage (65001) and disables the user profile (WINRS_NOPROFILE). The caller must eventually call delete_shell to release server resources.

pub async fn open_psrp_shell( &self, host: &str, creation_xml_b64: &str, resource_uri: &str, ) -> Result<Shell<'_>, WinrmError>

Create a PSRP (PowerShell Remoting) shell on the given host.

Unlike Self::create_shell this uses the PowerShell resource URI and embeds the creationXml (base64-encoded PSRP opening fragments) directly in the Create Shell body.

Returns a Shell whose subsequent operations (Execute, Receive, Send, Signal, Delete) will use the PowerShell resource URI.

pub async fn execute_command( &self, host: &str, shell_id: &str, command: &str, args: &[&str], ) -> Result<String, WinrmError>

Execute a command in an existing remote shell. Returns the command ID.

The caller is responsible for subsequently calling receive_output to poll for results.

pub async fn receive_output( &self, host: &str, shell_id: &str, command_id: &str, ) -> Result<ReceiveOutput, WinrmError>

Poll for command output (stdout, stderr, exit code, and completion flag).

Must be called repeatedly until ReceiveOutput::done is true. Each call may return partial output that should be accumulated.

pub async fn signal_terminate( &self, host: &str, shell_id: &str, command_id: &str, ) -> Result<(), WinrmError>

Send a terminate signal to a running command.

This is a best-effort operation – errors are typically non-fatal since the shell will be deleted shortly after.

pub async fn delete_shell( &self, host: &str, shell_id: &str, ) -> Result<(), WinrmError>

Delete (close) a remote shell, releasing server-side resources.

Should always be called after command execution is complete, even if an error occurred. The high-level run_command and run_powershell methods handle this automatically.

pub async fn run_command( &self, host: &str, command: &str, args: &[&str], ) -> Result<CommandOutput, WinrmError>

Run a command on a remote host, collecting all output.

This is the primary entry point for command execution. It handles the full shell lifecycle: create -> execute -> poll -> signal -> delete. The shell is always cleaned up, even if the command fails.

pub async fn run_powershell( &self, host: &str, script: &str, ) -> Result<CommandOutput, WinrmError>

Run a PowerShell script on a remote host.

The script is encoded as UTF-16LE base64 and executed via powershell.exe -EncodedCommand, which avoids quoting and escaping issues. Internally delegates to run_command.

pub async fn run_command_with_cancel( &self, host: &str, command: &str, args: &[&str], cancel: CancellationToken, ) -> Result<CommandOutput, WinrmError>

Execute a command with cancellation support.

Like run_command, but can be cancelled via a CancellationToken.

pub async fn run_powershell_with_cancel( &self, host: &str, script: &str, cancel: CancellationToken, ) -> Result<CommandOutput, WinrmError>

Execute a PowerShell script with cancellation support.

Like run_powershell, but can be cancelled via a CancellationToken.

pub async fn run_wql( &self, host: &str, query: &str, namespace: Option<&str>, ) -> Result<String, WinrmError>

Execute a WQL query against WMI via WS-Enumeration.

Returns the raw XML response items as a string. The response contains WMI object instances matching the query. Use a namespace of None for the default root/cimv2.

Example

let xml = client.run_wql("server", "SELECT Name,State FROM Win32_Service", None).await?;
println!("{xml}");

pub async fn open_shell(&self, host: &str) -> Result<Shell<'_>, WinrmError>

Open a reusable shell session on the given host.

Returns a Shell that can execute multiple commands without the overhead of creating and deleting a shell each time.

The shell should be explicitly closed via Shell::close when done. If dropped without closing, a warning is logged.

pub async fn reconnect_shell( &self, host: &str, shell_id: &str, resource_uri: &str, ) -> Result<Shell<'_>, WinrmError>

Reconnect to a previously-disconnected shell.

Sends a WS-Man Reconnect SOAP request to validate that the server-side shell identified by shell_id is still alive and returns a Shell handle that resumes operations on it.

impl WinrmClient

pub async fn upload_file( &self, host: &str, local_path: &Path, remote_path: &str, ) -> Result<u64, WinrmError>

Upload a local file to a remote Windows host.

The file is chunked into ~2 KB pieces, base64-encoded, and written via PowerShell [IO.File]::WriteAllBytes / [IO.File]::Open('Append'). The small chunk size is dictated by the WinRS command-line limit (~8191 chars) after triple encoding (base64 → UTF-16LE → base64).

Returns the number of bytes uploaded.

pub async fn download_file( &self, host: &str, remote_path: &str, local_path: &Path, ) -> Result<u64, WinrmError>

Download a file from a remote Windows host.

Reads the file via PowerShell base64 encoding and decodes locally.

Returns the number of bytes downloaded.