Device Management PowerShell Cmdlets Sample - An introduction

 

Hi there! I’d like to introduce Ricardo Mendes, a Senior Program Manager in the Enterprise Engineering Center (EEC), a facility dedicated to validating Microsoft’s next wave of customer and partner solutions. In this blog post, Ricardo explores how PowerShell 3.0 can be used to enumerate, control and manage hardware components as well as device drivers.

Natalia Mackevicius
Group Program Manager, Partner and Customer Ecosystem Team

Abstract 

This blog post provides an overview of the Device Management PowerShell Cmdlets sample that is available on TechNet Gallery (https://gallery.technet.microsoft.com/Device-Management-7fad2388). This sample provides cmdlets to enumerate, control and manage devices, similar in capabilities to Device Manager.

 

Introduction

Hardware enumeration is something that the vast majority of Windows users don't need to worry about. Thanks to an extensive PnP infrastructure, the process of identifying devices, installing drivers and controlling those devices is handled transparently by the Operating System. Behind the scenes, years of technology improvement paired with an extensive ecosystem of device driver developers, provides the user worry-free device management.

But sometimes, users need to get a better understanding of the hardware topology (how the different devices are interconnected) as well as control individual devices. There are several scenarios were the ability to inquire and control each individual device on the system is necessary, for example: identifying which physical network port corresponds to a given network connection; balancing IO capabilities by moving IO expansion cards to different slots / NUMA nodes; configuring processor/socket affinity [RI1] on Server workloads in order to boost IO performance; among others.

For a long time, Device Manager has provided rich device management and enumeration capabilities for end-users.

 

The Problem

Although feature-rich; Device Manager, currently, is only available as a graphical UI. Users that need to automate or script operations that rely on Device Manager can't have it running in 'console' mode.

 

Alternatives to Device Manager

For users that need to script device operations or topology enumeration, different options are currently available, including but not limited to: WMIC (WMI Command Line - https://technet.microsoft.com/en-us/library/bb742610.aspx); devcon.exe (https://support.microsoft.com/kb/311272); Get-WmiObject (https://technet.microsoft.com/en-us/library/ee176860.aspx) and CoreInfo.exe (https://technet.microsoft.com/en-us/sysinternals/cc835722.aspx).

Although the above-mentioned options are great alternatives to script device management tasks, a solution based on these will still have to be coded using different calling methods as each command has its own calling convention and custom output.

 

PowerShell Modules Comes into Picture

PowerShell provides several extensibility points, modules being one. Modules can be implemented in different ways, one being binary modules. Those are .NET Framework assemblies (.dll) that contain compiled code.

Windows currently provides plenty of API functions to perform device enumeration and management operations - those functions are exposed by the SetupAPI.

The following sections on this post intend to provide an overview of the Device Management PowerShell Cmdlets sample that is available on TechNet Gallery. The main goal of these cmdlets is to provide a uniform mechanism to enumerate, control and manage devices, similar in capabilities to Device Manager allowing PowerShell scripts to easily execute device related operations.

In a nutshell, the cmdlets were implemented using Visual Studio 2012 and .NET Framework 4.5. All the device related operations are performed by calling into SetupAPI functions. An overview of those functions can be found at: https://msdn.microsoft.com/en-us/library/windows/hardware/ff537796(v=vs.85).aspx.

It’s not a goal of this post to deep dive into the implementation details. Further posts will provide more insights on how the cmdlets work.

The module currently exposes the following cmdlets:

  • Get-Device
  • Get-Driver
  • Get-Numa
  • Enable-Device
  • Disable-Device

In order to install and run the cmdlets, the following are the platform requirements:

  • Windows Server 2012 or Windows 8
  • .NET Framework 4.5
  • · PowerShell 3.0

 

Downloading and using the Device Management PowerShell Cmdlets

The Device Management PowerShell cmdlets are available at: https://gallery.technet.microsoft.com/Device-Management-7fad2388

To download, follow the above link and click on the “Download” button. Save and extract the contents of the.zip file to a folder of your choice.

The next step is to import the module and start using the cmdlets! In order to do so, launch an instance of PowerShell and follow the below steps:

Importing the Cmdlet module:

Import-Module .\PSCmdlet.psd1 –Verbose

 

Listing Devices

All devices present on the system

Get-Device | Sort-Object -Property Name | ft Name, DriverVersion, DriverProvider, IsPresent, HasProblem -AutoSize

“Hidden” devices

Get-Device -ControlOptions DIGCF_ALLCLASSES | Sort-Object -Property Name | Where-Object -Property IsPresent -eq $false | ft Name, DriverVersion, DriverProvider, IsPresent, HasProblem -AutoSize

Disabled devices

Get-Device | Sort-Object -Property Name | Where-Object -Property ConfigurationFlags -Like '*DISABLED*' | ft Name, InstanceId -AutoSize

Enabling / Disabling Devices

$deviceName = Read-Host -Prompt 'Please enter the Name of the Device to Disable'; Get-Device | Where-Object -Property Name -Like $deviceName | Disable-Device

$deviceName = Read-Host -Prompt 'Please enter the Name of the Device to Enable'; Get-Device | Where-Object -Property Name -Like $deviceName | Enable-Device

Topology Enumeration using the PowerShell Cmdlets

Logical Processor and NUMA Information

Get-Numa

Firmware Tables

$hardwareTopology = Get-Numa; $hardwareTopology.FirmwareTables | ft –AutoSize

Summary

The goal of this post was to introduce the Device Management PowerShell cmdlets sample and describe how it can be used. A series of posts is going to follow covering the implementation details as well as new features as these cmdlets are being developed further.

If you find these cmdlets useful, please feel free to contact ricardom@microsoft.com with thoughts, ideas and suggestions.

Thanks,

Ricardo Mendes
Program Manager
Enterprise Engineering Center
https://www.microsoft.com/eec