Getting Started with New-WSManInstance in PowerShell

Welcome back to Wahmans Powershell blog! Today, we’re diving into the New-WSManInstance cmdlet. If you’re managing remote Windows systems or working with Windows Remote Management (WinRM), this is one of the essential tools in your PowerShell toolbox.

What is New-WSManInstance?

The New-WSManInstance cmdlet is used to create a new instance of a management resource. In simpler terms, this lets you interact with remote systems via WS-Management, using the open-standard DMTF (Distributed Management Task Force) protocol.

This is particularly powerful for automating administrative tasks over multiple machines through WinRM sessions.

Basic Syntax

New-WSManInstance [-ResourceURI] <Uri> [-SelectorSet <IDictionary>] [-ValueSet <IDictionary>] [-ComputerName <String>] [-Credential <PSCredential>] [CommonParameters]

Examples

Example 1: Creating a New Event Subscribing Filter (Beginner)

This example creates a basic event filter instance using the WMI Event subscription.

$filter = @{ 
  Name = 'DemoFilter'
  Query = 'SELECT * FROM __InstanceCreationEvent WITHIN 5 WHERE TargetInstance ISA "Win32_Process"'
  EventNamespace = 'root\cimv2'
}

New-WSManInstance -ResourceURI "http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/__EventFilter" -ValueSet $filter

This sets up an event filter that listens for new process creation every 5 seconds.

Example 2: Creating a Scheduled Task Registration (Intermediate)

$task = @{
  Description = "PowerShell Demo Task"
  Author = "Admin"
}

New-WSManInstance -ResourceURI "http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_ScheduledJob" -ValueSet $task

Though not always recommended for task scheduling, this shows the capability of interacting remotely with scheduled jobs.

Example 3: Adding a Firewall Rule Remotely (Intermediate)

With administrative permissions, you can create firewall rules on a remote machine with:

$firewallRule = @{
  Name = 'Allow_HTTP'
  DisplayName = 'Allow HTTP traffic'
  Direction = 'In'
  Action = 'Allow'
  Protocol = 'TCP'
  LocalPort = '80'
  Enabled = 'True'
}

New-WSManInstance -ResourceURI "http://schemas.microsoft.com/wbem/wsman/1/wmi/root/standardcimv2/MSFT_NetFirewallRule" -ValueSet $firewallRule -ComputerName 'RemotePC01'

This will open up port 80 (HTTP) traffic on the remote machine.

Example 4: Advanced Use – Creating a WinRM Session Configuration (Advanced)

If you’re customizing WinRM settings across machines, you can create session configurations programmatically.

$sessionConfig = @{
  ResourceUri = 'http://schemas.microsoft.com/wbem/wsman/1/config'
  ValueSet = @{
    AllowUnencrypted = $false
    MaxConcurrentUsers = 15
  }
}

New-WSManInstance @sessionConfig

This updates session configuration settings such as unencrypted communication and max users allowed.

Conclusion

As you can see, New-WSManInstance is a highly versatile cmdlet for creating WMI or CIM instances over the WS-Management protocol. Whether you’re automating firewall configurations, remote tasks, or system administration policies, learning how to wield this tool will take your scripting to the next level!

Happy scripting, and I will see you in the next post!