Managing and maintaining a consistent naming convention across IT assets is vital for streamlined operations, inventory accuracy, and compliance. Among the various metadata attributes assigned to a Windows system, the device description often gets overlooked.
However, this small piece of information can significantly improve clarity in IT environments, especially when integrated with asset tracking and remote management platforms. In this post, we explore how to update device description with PowerShell — a small, impactful change that can improve administrative efficiency.
Background
In many environments — particularly those managed by Managed Service Providers (MSPs) or internal IT teams — device metadata plays a crucial role in device identification and organization. The “device description” field is used to provide contextual information about the machine, such as its purpose or assigned user. Unfortunately, updating this description manually through GUI interfaces is inefficient, particularly at scale.
This PowerShell script fills that gap, allowing IT professionals to automate the process of updating or clearing device descriptions. By supporting environment variable inputs and validating proper use, it ensures reliable execution whether deployed interactively or through remote management platforms like NinjaOne.
The Script
#Requires -Version 4
<#
.SYNOPSIS
Updates the current device description.
.DESCRIPTION
Updates the current device description.
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms.
Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party.
Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider.
Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations.
Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks.
Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script.
EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
.EXAMPLE
-Description "Kitchen Computer"
Attempting to set device description to 'Kitchen Computer'.
SystemDirectory : C:\Windows\system32
Organization : vm.net
BuildNumber : 9600
RegisteredUser : NA
SerialNumber : 00252-70000-00000-AA382
Version : 6.3.9600
Successfully set device description to 'Kitchen Computer'.
PARAMETER: -Description "ReplaceMeWithADeviceDescription"
Specify the device description you would like to set.
PARAMETER: -ClearDescription
Clear the current device description.
.NOTES
Minimum OS Architecture Supported: Windows 10, Windows Server 2012 R2
Release Notes: Initial Release
#>
[CmdletBinding()]
param (
[Parameter()]
[String]$Description,
[Parameter()]
[Switch]$ClearDescription = [System.Convert]::ToBoolean($env:clearDeviceDescription)
)
begin {
if($env:deviceDescription -and $env:deviceDescription -notlike "null"){ $Description = $env:deviceDescription }
# Trim any leading or trailing whitespace from the description, if it exists
if ($Description) {
$Description = $Description.Trim()
}
# Ensure that a description is provided if clearing the description is not requested
if (!$Description -and !$ClearDescription) {
Write-Host -Object "[Error] You must provide a description to set."
exit 1
}
# Ensure that both clearing and setting the description are not requested simultaneously
if ($ClearDescription -and $Description) {
Write-Host -Object "[Error] You cannot clear and set the device description at the same time."
exit 1
}
# Clear the description if requested
if ($ClearDescription) {
$Description = $Null
}
# Measure the length of the description
$DescriptionLength = $Description | Measure-Object -Character | Select-Object -ExpandProperty Characters
# Warn if the description is longer than 40 characters
if ($DescriptionLength -ge 40) {
Write-Host -Object "[Warning] The description '$Description' is greater than 40 characters. It may appear trimmed in certain situations."
}
# Function to check if the script is running with elevated (administrator) privileges
function Test-IsElevated {
$id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
$p = New-Object System.Security.Principal.WindowsPrincipal($id)
$p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
}
if (!$ExitCode) {
$ExitCode = 0
}
}
process {
# Check if the script is running with elevated (administrator) privileges
if (!(Test-IsElevated)) {
Write-Host -Object "[Error] Access Denied. Please run with Administrator privileges."
exit 1
}
try {
Write-Host -Object "Attempting to set device description to '$Description'."
# Determine the PowerShell version and set the operating system description accordingly
if ($PSVersionTable.PSVersion.Major -lt 5) {
# Use Get-WmiObject for PowerShell versions less than 5
Get-WmiObject -Class Win32_OperatingSystem -ErrorAction Stop | Set-WmiInstance -Property @{ 'Description' = $Description } -ErrorAction Stop
}
else {
# Use Get-CimInstance for PowerShell version 5 or greater
Get-CimInstance -Class Win32_OperatingSystem -ErrorAction Stop | Set-CimInstance -Property @{ 'Description' = $Description } -ErrorAction Stop
}
Write-Host -Object "Successfully set device description to '$Description'."
}
catch {
# Handle any errors that occur while retrieving the device description
Write-Host -Object "[Error] Failed to set the device description."
Write-Host -Object "[Error] $($_.Exception.Message)"
exit 1
}
exit $ExitCode
}
end {
}
Detailed Breakdown
Let’s examine the script line by line to understand how it works and why each section matters.
Parameter Handling
powershell
CopyEdit
param (
[String]$Description,
[Switch]$ClearDescription = [System.Convert]::ToBoolean($env:clearDeviceDescription)
)
The script accepts two parameters:
- $Description: The desired device description.
- $ClearDescription: A switch to clear the current description, optionally set via an environment variable.
Preprocessing Logic
powershell
CopyEdit
if($env:deviceDescription -and $env:deviceDescription -notlike “null”){ $Description = $env:deviceDescription }
This line checks if a device description is supplied via the environment and uses it if present. It also ensures whitespace is trimmed and validates that the user isn’t trying to both set and clear the description in one run — a common misstep that the script gracefully handles.
Description Length Check
powershell
CopyEdit
$DescriptionLength = $Description | Measure-Object -Character | Select-Object -ExpandProperty Characters
if ($DescriptionLength -ge 40) {
Write-Host -Object “[Warning] … may appear trimmed …”
}
Here, the script warns the user if the description exceeds 40 characters — a practical limit due to UI rendering constraints in many management tools.
Privilege Validation
The script contains a custom function, Test-IsElevated, to verify it’s running with administrator privileges. This is essential, as writing to the system’s OS-level properties requires elevated permissions.
Main Execution Logic
Depending on the PowerShell version, the script uses either Set-WmiInstance or Set-CimInstance to update the Win32_OperatingSystem.Description property. This bifurcation ensures compatibility across Windows versions and PowerShell builds.
Error Handling
A robust try-catch block handles failures gracefully, providing informative output to help diagnose issues without crashing the script unexpectedly.
Potential Use Cases
Case Study: An MSP manages 200+ endpoints across various clients. Each machine must reflect its deployment purpose — e.g., “Reception Terminal” or “Finance Workstation.” By integrating this script with NinjaOne’s scripting module and passing values via environment variables, technicians can dynamically update the device description during onboarding or post-deployment audits, improving asset visibility in client dashboards.
Comparisons
Manual GUI Method
- Requires logging into each device.
- Time-consuming and error-prone.
Group Policy
- Cannot directly modify the OS description field.
- Limited customization options.
PowerShell Script
- Fast, automated, and scalable.
- Easily integrates into RMM platforms like NinjaOne.
- Supports dynamic input via environment variables.
FAQs
Q: Can I run this script remotely?
Yes. As long as the session is elevated and has the necessary permissions, it can be executed via remote shells or RMM platforms.
Q: What if the device description is too long?
The script will still set it, but a warning will be issued. UI rendering in some tools might truncate it.
Q: Will this persist after a reboot?
Yes. The device description set here is stored persistently in WMI and survives reboots.
Q: What happens if I try to set and clear the description at the same time?
The script exits with an error, ensuring only one operation is performed per run.
Implications
Updating the device description might seem minor, but it has significant administrative implications. Accurate device metadata enhances security auditing, simplifies inventory management, and improves context-aware scripting or policy enforcement. In environments where roles are assigned dynamically or repurposed regularly, this field provides quick insight into device use — crucial for troubleshooting and compliance.
Recommendations
- Run as Administrator: Always execute the script with elevated privileges to avoid permission errors.
- Integrate with RMM Tools: Pass parameters using environment variables for seamless automation.
- Standardize Descriptions: Use a naming convention to ensure consistency across your environment.
- Limit Length: Keep descriptions under 40 characters when possible to prevent UI truncation.
Final Thoughts
This PowerShell script exemplifies how a small automation can drive significant operational efficiency. Whether you’re managing ten endpoints or ten thousand, updating the device description programmatically helps maintain clarity and consistency.
NinjaOne users can leverage this script within the platform’s scripting engine, injecting variables dynamically for precision updates during routine tasks, onboarding, or incident response. It’s a perfect example of combining PowerShell’s power with NinjaOne’s flexibility to streamline endpoint management.