Welcome back to another post on Wahmans Powershell Blog!
Today, we’re exploring a very useful cmdlet in the world of Windows PowerShell remoting: `New-WSManSessionOption`. This cmdlet might not be something you use daily, but it provides essential control when managing remote sessions using WS-Management (WinRM).
## What does `New-WSManSessionOption` do?
According to Microsoft:
> `New-WSManSessionOption` creates a session option hash table to use as input parameters for WS-Management cmdlets.
This cmdlet allows us to customize how we interact with remote computers using WSMan. We can tweak settings like timeouts, certificate checks, and more.
Let’s look at some practical examples, ranging from basic to advanced use cases.
—
### 📘 Example 1: Basic Use – Increasing the Operation Timeout
When dealing with remote machines, a command might take longer than expected. Use `New-WSManSessionOption` to increase timeout limits.
“`powershell
$sessionOptions = New-WSManSessionOption -OperationTimeout 60000
$session = New-PSSession -ComputerName “Server01” -SessionOption $sessionOptions
“`
This example sets the operation timeout to 60,000 milliseconds (60 seconds) to accommodate long-running commands.
—
### 🔒 Example 2: Disable Certificate Validation for HTTPS Connections
Great for lab or test environments using self-signed certificates where strict validation is unnecessary:
“`powershell
$sessionOptions = New-WSManSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
$session = New-PSSession -ComputerName “Server02” -UseSSL -SessionOption $sessionOptions
“`
> 🚨 Note: Use this only in a secure, trusted lab setting. Never bypass certificate validation in production environments.
—
### 🌐 Example 3: Using a Proxy for WSMan Connections
Connecting to remote servers via a proxy? Here’s how you can define proxy settings:
“`powershell
$proxyUri = “http://proxy.company.local:8080”
$sessionOptions = New-WSManSessionOption -ProxyAccessType IEConfig -ProxyAuthentication Negotiate
$session = New-PSSession -ComputerName “server03.contoso.com” -SessionOption $sessionOptions
“`
This will use Internet Explorer’s proxy configuration and Negotiate authentication.
—
### 🧠 Example 4: Advanced – Custom Time and Envelope Sizes
Let’s say you’re pushing big scripts or getting large data back. Increase message envelope size and timeout:
“`powershell
$sessionOptions = New-WSManSessionOption -OperationTimeout 120000 -MaximumEnvelopeSizeKB 1024
$session = New-PSSession -ComputerName “Server04” -SessionOption $sessionOptions
“`
This gives more room and time for data-heavy remoting tasks, preventing timeouts or envelope errors.
—
`New-WSManSessionOption` is a behind-the-scenes powerhouse that helps you control the nuances of remoting. Whether you’re troubleshooting a slow response or working with proxies and security settings, this cmdlet gives you the flexibility you need.
💡 Next time you’re creating a `PSSession`, consider what session options you might need — `New-WSManSessionOption` might be exactly what you’re looking for!
Until next time —
**Happy scripting, and I will see you in the next post!**
Leave a Reply