PowerShell for Windows Admins

April 10, 2014  2:16 PM


Richard Siddaway Richard Siddaway Profile: Richard Siddaway

A comment was left on my last post stating that the requires keyword could be used to test for modules.

Requires is a keyword that can be put at the top of scripts and modules. It will prevent the script or module running if the requirement isn’t met.  You can test for a number of items. This list is for  PowerShell 4.0.  earlier versions of PowerShell have fewer options.

PowerShell version:

#Requires –version 3

This means that the code will only run on PowerShell version 3 or later

PowerShell snapin

#Requires –PSSnapin Microsoft.Exchange.Management.PowerShell.E2010

Loads the Exchange snapin.  iIf its not available the script won’t continue.


#Requires -Modules PSWorkflow, @{ModuleName=”PSScheduledJob”;ModuleVersion=}

Use the module name or a hash table with name, version and optionally the GUID for the module. If the required module can’t be loaded the script fails. This is different to my test-module function as I was only interested in discovery – I wasn’t actually using the test. If your script requires a module use the #Requires statement

Elevated privileges

#Requires –RunAsAdministrator

If PowerShell isn’t running with elevated privileges the script terminates.


#Requires –ShellId Microsoft.PowerShell

This uses the default PowerShell Shell.  Note that the console and ISE both return Microsoft.PowerShell    when you test $shellid.  If you want to test for console vs ISE use

£> $host.name


£> $Host.Name

Windows PowerShell ISE Host

April 9, 2014  1:33 PM

Testing module existence

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

I had a comment left on an old post stating that Get-ADuser errored stating it wasn’t a cmdlet. This is because the module wasn’t loaded or on PowerShell 3 and above available to be auto-imported. That got me thinking about testing for a modules existence.

function test-module {


param (









switch ($psCmdlet.ParameterSetName) {

‘Installed’ {

Get-Module -Name “*$name*” -ListAvailable



‘Loaded’ {

Get-Module -Name “*$name*”


default {

Throw “Error!!! Should not be here”




Define a parameter for the module name and 2 switch parameters – loaded tests if the module is loaded into PowerShell and installed tests if the module can be found on the module path.

I’ve used parameter sets to make the switches mutually exclusive.

A switch statement based on the parameter set name calls the Get-Module in an appropriate manner. Notice that the module name you supply is wrapped in wildcards so you don’t have to type the full module name.

You can use the function like this:

test-module -name cim –installed


test-module -name cim -loaded

You can even do this:

if (-not (test-module -name cim -loaded)){throw “module not found”}

April 8, 2014  2:41 PM

Getting mailbox data and stats per database

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

Way back in the day – http://richardspowershellblog.wordpress.com/2007/12/20/list-mailboxes-by-mailbox-database/ – I showed how to list mailboxes by the database in which they were stored. I had a comment left asking if its possible to list only a specific mailbox and to give the mailbox size as well.

To recap:

Get-Mailbox will return the list of mailboxes

This will quickly show the number of mailboxes per database

Get-Mailbox | group Database –NoElement

This shows the mailboxes in a particular database

Get-Mailbox -Database MDB1

To get the size you use Get-MailboxStatistics

So to put this together:

function get-mbxBYdb {


param (




Get-Mailbox -Database $database |

foreach {

$stat = $_ | Get-MailboxStatistics -WarningAction SilentlyContinue

New-Object -TypeName PSObject -Property @{

Name = $($_.DisplayName)

Address = $($_.PrimarySmtpAddress)

Database = $database

Items = $stat.ItemCount

‘Size(KB)’ = $stat.TotalItemSize.Value.ToKB()




The database name is a mandatory parameter. Get the mailboxes in the database and foreach get the mailbox statistics. You can then create an output object that combines the data from the mailbox object and the statistics object. Examine each type of object individually to determine the exact set of properties you need.

One trick with the size of items is that you can convert to specific size units as shown (MB, GB, TB and bytes are also available)

April 7, 2014  12:49 PM

Finding the class key

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

Time to extend our module for investigating CIM. This time I want to show you how to find the key to the class.

You need to know the key property of a CIM class when you perform a number of actions – most particularly when you create an instance of the class. Its just a matter of iterating through the properties of the class to find any that have a qualifier called KEY.

function Get-ClassKey {


param (






[string]$namespace = ‘root/cimv2’


$class = Get-CimClass -ClassName $classname -Namespace $namespace

foreach ($property in $class.CimClassProperties) {

$property | select -ExpandProperty Qualifiers |

foreach {

if ($_.Name -eq ‘key’){






The classname parameter is made mandatory and the namespace defaults to root/cimv2

Get the class and then loop through the each property – looking for a qualifier called key.

April 4, 2014  12:18 PM

Discovering namespaces part 2

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

I recently showed how to use Get-CimInstance to discover the namespaces present in a particular CIM namespace. I’m going to try to use CIM instaed of WMI but expect the old terminology to creep in occasionally.

The function I showed last time will only find the first level of namespaces in a namespace – what if those namespaces contain namespaces.

This is where you get to meet the concept of recursion. In this case all it means is that we’re going to call our function from within the function. Its easier to show with code.

function get-cimnamespace {

param (

[string]$namespace = ‘root/cimv2’,



if (-not $nobase)


New-Object -TypeName psobject -Property @{

Name = $namespace



Get-CimInstance -ClassName __NameSpace -Namespace $namespace |

foreach {

$ns = New-Object -TypeName psobject -Property @{

Name = “$($psitem.CimSystemProperties.NameSpace)/$($psitem.Name)”


Write-Output $ns

get-cimnamespace -namespace $ns.Name -nobase



The function has 2 parameters – the startign namespace parameter and a switch parameter. The switch controls if the namespace used as a parameter is output.

Get-CimInstance is used to find each instance of the __Namespace class. Foreach instance the namespace name is output and then used to call get-cimnamespace with the new namespace as a paramter. Its already been output so the –nobase switch is used to prevent duplicate output. And that’s recursion.

On my test machine I get this

£> get-cimnamespace






































I’m loading the function as part of a CimInvetsigation module which now has 2 cmdlets:



April 3, 2014  1:14 PM

Windows Server 2012 R2 Update

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

The Windows Server 2012 R2 Update (and the corresponding Windows 8.1 Update) are available to MSDN/TechNet subscribers. General availability follows on 8 April (patch Tuesday)

Details from http://blogs.technet.com/b/windowsserver/archive/2014/04/02/windows-server-2012-r2-update-is-now-available-to-subscribers.aspx

April 3, 2014  1:02 PM

Windows Management Framework V5

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

The Windows Server blog has an announcement, and download link, for WMF v5.


The headline items are OneGet and cmdlets for managing network switches that conform to the Certified for Windows Network program.

OneGet is a way to discover, and install, software packages. In this release you can search for and install software from Chocolatey repositories.

There are also some fixes and enhancements to DSC to improve performance.

April 2, 2014  11:43 AM

CIM snippets–working with file system

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

The latest instalment from the WMI team on using PowerShell and the CIM cmdlets is available – http://blogs.msdn.com/b/wmi/archive/2014/03/28/performing-management-tasks-using-cim-cmdlets-4-files-and-folders.aspx

This time round the examples are to do with working with the file system – files, folders and shares.

If you’ve worked with WMI you’ll be aware of that very often you get 2 classes one with a prefix of CIM (base class from DMTF definition) and one with Win32 prefix which is the Microsoft implementation. They 2 classes are often identical though the Win32 class may have additions.

The WMI class for working with files is different – it only has a CIM version CIM_DataFile.

The first example in the post is about renaming a file. A much simpler coding of the task would be:

Get-CimInstance -ClassName CIM_Datafile -Filter “Name = ‘C:\\Test\\Names.txt'” | Invoke-CimMethod -MethodName Rename -Arguments @{FileName = ‘C:\\Test\\OldNames.txt’}

A couple of points to note:

– when dealing with file paths all \ characters must be doubled. This is because \ is a WMI escape character so you need to escape it to use it literally.

– Invoke-CimMethod uses a hash table for the method arguments with the argument name as the key – this takes away any of the argument order issues you see with Invoke-WmiMethod)

One perennial problem for administrators is users putting their own files on the organization’s file servers.  Want to know if there any files of a specific type in a folder?

Get-CimInstance -ClassName CIM_Datafile -Filter “Extension = ‘txt’ AND Path = ‘\\test\\'”

If you leave the path out of the filter then all files on the drive will be searched – could take a while.  Being specific in your filter will save you a lot of time.

Want to find all the mp3 files on a drive?

Get-CimInstance -ClassName CIM_Datafile -Filter “Extension = ‘mp3′”

You can’t create files and folders with CIM (or WMI) but you can create shares

$margs = @{
Path = ‘C:\Test’
Name = ‘Test2April’
Description = ‘TestShare’
Type = [uint32]0

Invoke-CimMethod -ClassName Win32_Share -MethodName Create -Arguments $margs

Create the hash table of arguments separately  – its easier to read. Bizarrely this time you don’t need to escape the \ in the path

You can see the shares on a system like this:

Get-CimInstance -ClassName Win32_Share

CIM may not be you first port of call when working with the file system but it can be useful – especially on remote systems.

You can find out much more about using CIM to work with the file system in chapetr 8 of PowerShell and WMI – www.manning.com/siddaway2

April 1, 2014  8:14 AM

MVP award renewed

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

Received an email this afternoon renewing my PowerShell MVP award for another year.  This is a great honour and I’d like to thank you for helping to make this possible by reading my blog posts.

March 31, 2014  4:03 AM

DSC resource kit wave 3

Richard Siddaway Richard Siddaway Profile: Richard Siddaway

Desired State Configuration (DSC) is the new server configuration and compliance mechanism that ships with PowerShell 4.0 and Windows Server 2012 R2.

Resources are the way you perform configuration. Now you have more options with the release of wave 3 of the DSC resource kit.

Details from http://blogs.msdn.com/b/powershell/archive/2014/03/28/dsc-resource-kit-wave-3.aspx

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to: