Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
function Get-Something {
Short description of function.
Longer description of function.
Get-Something -ComputerName 'Computer01'
Example description
$servers | Get-Something
Example description
General notes about the function
Author: Øyvind Kallstad
This function uses CIM to query one or more computers.
A CIM session is saved in the current PowerShell session with the name of the remote computer, and will be re-used if possible.
This means that if you run this function against a computer and you already have a session, you don't have to use the Credential
parameter after the first time. The function will try to use 'Wsman' as protocol, but will fall back to using 'Dcom' if needed.
NOTE! This is just a template!
Related link
param (
# Specifies the target computer. Enter a fully qualified domain name, NetBIOS name, or an IP address. When the remote computer is in a different domain than the local computer,
# the fully qualified domain name is required.
[Parameter(Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)]
[string[]] $ComputerName = $env:COMPUTERNAME,
# Specifies a user account that has permission to perform this action.
[System.Management.Automation.Credential()] $Credential = [System.Management.Automation.PSCredential]::Empty,
# Use this parameter to force the creation of a new CIM session. The default behaviour is to save the session and reuse it if possible.
[switch] $ForceNewCimSession
begin {
# code to execute before pipline processing
process {
foreach ($computer in $ComputerName) {
try {
# define hashtable for Test-WSMan properties
$wsmanProperties = @{
ComputerName = $computer
ErrorAction = 'SilentlyContinue'
if ($PSBoundParameters['Credential']){
#$wsmanProperties.Authentication = 'Basic'
# if you can't use Kerberos authentication, comment out this line and uncomment the line above to use Basic authentication instead
$wsmanProperties.Authentication = 'Kerberos'
$wsmanProperties.Credential = $Credential
# check if wsman is responding
$wsmanTest = Test-WSMan @wsmanProperties
# based on the result of the wsman test, we decide on the protocol to use for the cim session
if (-not([string]::IsNullOrEmpty($wsmanTest))) {
$cimSessionOption = New-CimSessionOption -Protocol Wsman
Write-Verbose 'Using protocol "Wsman"'
else {
$cimSessionOption = New-CimSessionOption -Protocol Dcom
Write-Verbose 'Using protocol "Dcom"'
# define hashtable for cim session properties
$cimSessionProperties = @{
Name = $computer
ComputerName = $computer
SessionOption = $cimSessionOption
Verbose = $false
ErrorAction = 'Stop'
if ($PSBoundParameters['Credential']){ $cimSessionProperties.Credential = $Credential}
# first check to see if a cim session already exist, if so use this - if not, we create a new one
# if -ForceNewCimSession is used, always create a new cim session
if ((-not($cimSession = Get-CimSession -Name $computer -ErrorAction SilentlyContinue)) -or ($ForceNewCimSession)) {
Write-Verbose 'Creating new CIM session'
$cimSession = New-CimSession @cimSessionProperties -SkipTestConnection
} else { Write-Verbose 'Using existing CIM session' }
## YOUR CODE GOES HERE - example:
Write-Output (Get-CimInstance -CimSession $cimSession -Query 'SELECT * FROM Win32_OperatingSystem' -Verbose:$false -ErrorAction Stop)
catch {
# if the connection fail we don't want to keep the session
Remove-CimSession -Name $computer -ErrorAction SilentlyContinue
Write-Warning "At line:$($_.InvocationInfo.ScriptLineNumber) char:$($_.InvocationInfo.OffsetInLine) Command:$($_.InvocationInfo.InvocationName), Exception: '$($_.Exception.Message.Trim())'"
end {
# code to execute after pipline processing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment