Eine effektive Kommunikation mit den Anwendern ist für IT-Experten von entscheidender Bedeutung, insbesondere in Umgebungen von Managed Service Providern (MSP). Eine praktische Möglichkeit, mit den Endnutzern zu interagieren, sind Systembenachrichtigungen. Mit diesem PowerShell-Skript können IT-Administratoren Toast-Nachrichten mit optionalen Heldenbildern senden und so eine benutzerfreundliche Methode für die Übermittlung wichtiger Updates, Erinnerungen oder Warnungen bieten. Hier finden Sie einen ausführlichen Überblick über dieses Skript, seine Funktionalität und seine Anwendungsmöglichkeiten.
Hintergrund und Bedeutung
Systembenachrichtigungen dienen als direkter Kommunikationsweg zwischen IT-Administratoren und Benutzern, insbesondere in Umgebungen, in denen E-Mail- oder Chat-Benachrichtigungen übersehen oder ignoriert werden könnten. Dieses Skript zeichnet sich dadurch aus, dass es nicht nur anpassbare Toast-Nachrichten liefert, sondern auch die Einbindung von Heldenbildern ermöglicht, wodurch die Benachrichtigungen visuell ansprechend werden.
MSPs und IT-Abteilungen setzen solche Tools häufig ein, um die Kommunikation mit den Benutzern zu verbessern, sei es, um geplante Wartungsarbeiten anzukündigen, Benutzer vor kritischen Problemen zu warnen oder Schritt-für-Schritt-Anleitungen bereitzustellen. Durch die Nutzung des nativen Benachrichtigungssystems von Windows 10 lässt sich dieses Skript nahtlos in den Arbeitsablauf des Benutzers integrieren, ohne dass zusätzliche Software installiert werden muss.
Das Skript zur Optimierung der Hintergrund-Verwaltung
#Requires -Version 5.1
<#
.SYNOPSIS
Sends a toast message/notification with a hero image to the currently signed in user. Please run as the Current Logged-on User. The script defaults to not using an image if none is provided.
.DESCRIPTION
Sends a toast message/notification with a hero image to the currently signed in user. Please run as 'Current Logged on User'.
This defaults to no image in the Toast Message, but you can specify any png formatted image from a url.
You can also specify the "ApplicationId" to any string.
The default ApplicationId is your company name found in the NINJA_COMPANY_NAME environment variable, but will fallback to "NinjaOne RMM" if it happens to not be set.
The URL image should be less than 2MB in size or less than 1MB on a metered connection.
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
-Title "My Title Here" -Message "My Message Here"
Sends the title "My Title Here" and message "My Message Here" as a Toast message/notification to the currently signed in user.
.EXAMPLE
-Title "My Title Here" -Message "My Message Here" -ApplicationId "MyCompany"
Sends the title "My Title Here" and message "My Message Here" as a Toast message/notification to the currently signed in user.
ApplicationId: Creates a registry entry for your toasts called "MyCompany".
PathToImageFile: Downloads a png image for the icon in the toast message/notification.
.OUTPUTS
None
.NOTES
If you want to change the defaults then with in the param block.
ImagePath uses C:\Users\Public\ as that is accessible by all users.
If you want to customize the application name to show your company name,
then look for $ApplicationId and change the content between the double quotes.
Minimum OS Architecture Supported: Windows 10 (IoT editions are not supported due to lack of shell)
Release Notes: Initial Release
#>
[CmdletBinding()]
param
(
[string]$Title,
[string]$Message,
[string]$ApplicationId,
[string]$PathToImageFile
)
begin {
[string]$ImagePath = "$($env:SystemDrive)\Users\Public\PowerShellToastHeroImage.png"
# Set the default ApplicationId if it's not provided. Use the Company Name if available, otherwise use the default.
$ApplicationId = if ($env:NINJA_COMPANY_NAME) { $env:NINJA_COMPANY_NAME } else { "NinjaOne RMM" }
Write-Host "[Info] Using ApplicationId: $($ApplicationId -replace '\s+','.')"
if ($env:title -and $env:title -notlike "null") { $Title = $env:title }
if ($env:message -and $env:message -notlike "null") { $Message = $env:message }
if ($env:applicationId -and $env:applicationId -notlike "null") { $ApplicationId = $env:applicationId }
if ($env:pathToImageFile -and $env:pathToImageFile -notlike "null") { $PathToImageFile = $env:pathToImageFile }
if ([String]::IsNullOrWhiteSpace($Title)) {
Write-Host "[Error] A Title is required."
exit 1
}
if ([String]::IsNullOrWhiteSpace($Message)) {
Write-Host "[Error] A Message is required."
exit 1
}
if ($Title.Length -gt 64) {
Write-Host "[Warn] The Title is longer than 64 characters. The title will be truncated by the Windows API to 64 characters."
}
if ($Message.Length -gt 200) {
Write-Host "[Warn] The Message is longer than 200 characters. The message might get truncated by the Windows API."
}
function Test-IsSystem {
$id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
return $id.Name -like "NT AUTHORITY*" -or $id.IsSystem
}
if (Test-IsSystem) {
Write-Host "[Error] Please run this script as 'Current Logged on User'."
Exit 1
}
function Set-RegKey {
param (
$Path,
$Name,
$Value,
[ValidateSet("DWord", "QWord", "String", "ExpandedString", "Binary", "MultiString", "Unknown")]
$PropertyType = "DWord"
)
if (-not $(Test-Path -Path $Path)) {
# Check if path does not exist and create the path
New-Item -Path $Path -Force | Out-Null
}
if ((Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore)) {
# Update property and print out what it was changed from and changed to
$CurrentValue = (Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name
try {
Set-ItemProperty -Path $Path -Name $Name -Value $Value -Force -Confirm:$false -ErrorAction Stop | Out-Null
}
catch {
Write-Host "[Error] Unable to Set registry key for $Name please see below error!"
Write-Host "$($_.Exception.Message)"
exit 1
}
Write-Host "[Info] $Path\$Name changed from:"
Write-Host " $CurrentValue to:"
Write-Host " $($(Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name)"
}
else {
# Create property with value
try {
New-ItemProperty -Path $Path -Name $Name -Value $Value -PropertyType $PropertyType -Force -Confirm:$false -ErrorAction Stop | Out-Null
}
catch {
Write-Host "[Error] Unable to Set registry key for $Name please see below error!"
Write-Host "$($_.Exception.Message)"
exit 1
}
Write-Host "[Info] Set $Path\$Name to:"
Write-Host " $($(Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name)"
}
}
# Utility function for downloading files.
function Invoke-Download {
param(
[Parameter()]
[String]$URL,
[Parameter()]
[String]$Path,
[Parameter()]
[int]$Attempts = 3,
[Parameter()]
[Switch]$SkipSleep
)
Write-Host "[Info] Used $PathToImageFile for the image and saving to $ImagePath"
$SupportedTLSversions = [enum]::GetValues('Net.SecurityProtocolType')
if ( ($SupportedTLSversions -contains 'Tls13') -and ($SupportedTLSversions -contains 'Tls12') ) {
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol::Tls13 -bor [System.Net.SecurityProtocolType]::Tls12
}
elseif ( $SupportedTLSversions -contains 'Tls12' ) {
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
}
else {
# Not everything requires TLS 1.2, but we'll try anyways.
Write-Host "[Warn] TLS 1.2 and or TLS 1.3 isn't supported on this system. This download may fail!"
if ($PSVersionTable.PSVersion.Major -lt 3) {
Write-Host "[Warn] PowerShell 2 / .NET 2.0 doesn't support TLS 1.2."
}
}
$i = 1
While ($i -le $Attempts) {
# Some cloud services have rate-limiting
if (-not ($SkipSleep)) {
$SleepTime = Get-Random -Minimum 1 -Maximum 7
Write-Host "[Info] Waiting for $SleepTime seconds."
Start-Sleep -Seconds $SleepTime
}
if ($i -ne 1) { Write-Host "" }
Write-Host "[Info] Download Attempt $i"
$PreviousProgressPreference = $ProgressPreference
$ProgressPreference = 'SilentlyContinue'
try {
# Invoke-WebRequest is preferred because it supports links that redirect, e.g., https://t.ly
# Standard options
$WebRequestArgs = @{
Uri = $URL
MaximumRedirection = 10
UseBasicParsing = $true
OutFile = $Path
}
# Download The File
Invoke-WebRequest @WebRequestArgs
$ProgressPreference = $PreviousProgressPreference
$File = Test-Path -Path $Path -ErrorAction SilentlyContinue
}
catch {
Write-Host "[Error] An error has occurred while downloading!"
Write-Warning $_.Exception.Message
if (Test-Path -Path $Path -ErrorAction SilentlyContinue) {
Remove-Item $Path -Force -Confirm:$false -ErrorAction SilentlyContinue
}
$File = $False
}
if ($File) {
$i = $Attempts
}
else {
Write-Host "[Error] File failed to download."
Write-Host ""
}
$i++
}
if (-not (Test-Path $Path)) {
Write-Host "[Error] Failed to download file!"
exit 1
}
else {
return $Path
}
}
function Show-Notification {
[CmdletBinding()]
Param (
[string]
$ApplicationId,
[string]
$ToastTitle,
[string]
[Parameter(ValueFromPipeline)]
$ToastText
)
# Import all the needed libraries
[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
[Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
[Windows.System.User, Windows.System, ContentType = WindowsRuntime] > $null
[Windows.System.UserType, Windows.System, ContentType = WindowsRuntime] > $null
[Windows.System.UserAuthenticationStatus, Windows.System, ContentType = WindowsRuntime] > $null
[Windows.Storage.ApplicationData, Windows.Storage, ContentType = WindowsRuntime] > $null
# Make sure that we can use the toast manager, also checks if the service is running and responding
try {
$ToastNotifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("$ApplicationId")
}
catch {
Write-Host "$($_.Exception.Message)"
Write-Host "[Error] Failed to create notification."
}
# Create a new toast notification
$RawXml = [xml] @"
<toast>
<visual>
<binding template='ToastGeneric'>
<text id='1'>$ToastTitle</text>
<text id='2'>$ToastText</text>
$(if($PathToImageFile){"<image placement='hero' src='$ImagePath' />"})
</binding>
</visual>
</toast>
"@
# Serialized Xml for later consumption
$SerializedXml = New-Object Windows.Data.Xml.Dom.XmlDocument
$SerializedXml.LoadXml($RawXml.OuterXml)
# Setup how are toast will act, such as expiration time
$Toast = $null
$Toast = [Windows.UI.Notifications.ToastNotification]::new($SerializedXml)
$Toast.Tag = "PowerShell"
$Toast.Group = "PowerShell"
$Toast.ExpirationTime = [DateTimeOffset]::Now.AddMinutes(1)
# Show our message to the user
$ToastNotifier.Show($Toast)
}
}
process {
Write-Host "ApplicationID: $ApplicationId"
if (-not $(Split-Path -Path $ImagePath -Parent | Test-Path -ErrorAction SilentlyContinue)) {
try {
New-Item "$(Split-Path -Path $ImagePath -Parent)" -ItemType Directory -ErrorAction Stop
Write-Host "[Info] Created folder: $(Split-Path -Path $ImagePath -Parent)"
}
catch {
Write-Host "[Error] Failed to create folder: $(Split-Path -Path $ImagePath -Parent)"
exit 1
}
}
$DownloadArguments = @{
URL = $PathToImageFile
Path = $ImagePath
}
Set-RegKey -Path "HKCU:\SOFTWARE\Classes\AppUserModelId\$($ApplicationId -replace '\s+','.')" -Name "DisplayName" -Value $ApplicationId -PropertyType String
if ($PathToImageFile -like "http*") {
Invoke-Download @DownloadArguments
}
elseif ($PathToImageFile -match "^[a-zA-Z]:\\" -and $(Test-Path -Path $PathToImageFile -ErrorAction SilentlyContinue)) {
Write-Host "[Info] Image is a local file, copying to $ImagePath"
try {
Copy-Item -Path $PathToImageFile -Destination $ImagePath -Force -ErrorAction Stop
Set-RegKey -Path "HKCU:\SOFTWARE\Classes\AppUserModelId\$($ApplicationId -replace '\s+','.')" -Name "IconUri" -Value "$ImagePath" -PropertyType String
Write-Host "[Info] System is ready to send Toast Messages to the currently logged on user."
}
catch {
Write-Host "[Error] Failed to copy image file: $PathToImageFile"
exit 1
}
}
elseif ($PathToImageFile -match "^[a-zA-Z]:\\" -and -not $(Test-Path -Path $PathToImageFile -ErrorAction SilentlyContinue)) {
Write-Host "[Error] Image does not exist at $PathToImageFile"
exit 1
}
else {
if ($PathToImageFile) {
Write-Host "[Warn] Provided image is not a local file or a valid URL."
}
Write-Host "[Info] No image will be used."
}
try {
Write-Host "[Info] Attempting to send message to user..."
$NotificationParams = @{
ToastTitle = $Title
ToastText = $Message
ApplicationId = "$($ApplicationId -replace '\s+','.')"
}
Show-Notification @NotificationParams -ErrorAction Stop
Write-Host "[Info] Message sent to user."
}
catch {
Write-Host "[Error] Failed to send message to user."
Write-Host "$($_.Exception.Message)"
exit 1
}
exit 0
}
end {
}
Sparen Sie Zeit mit über 300+ Skripten aus dem NinjaOne Dojo.
Detaillierte Aufschlüsselung des Skripts
Dieses PowerShell-Skript ist so konzipiert, dass es von dem aktuell angemeldeten Benutzer ausgeführt wird. Hier eine schrittweise Erklärung des Arbeitsablaufs:
1.Parameter und Standardeinstellungen
a. Das Skript akzeptiert Parameter für den Titel, die Nachricht, die Anwendungs-ID und einen optionalen Pfad zu einer Bilddatei.
b. Wenn die Anwendungs-ID nicht angegeben wird, verwendet das Skript standardmäßig den in der Umgebungsvariablen NINJA_COMPANY_NAME gespeicherten Firmennamen oder greift auf “NinjaOne RMM” zurück
c. Wenn kein Bild angegeben wird, wird die Meldung ohne Bild angezeigt.
2. Validierung der Umgebung
a. Das Skript prüft, ob es als der aktuell angemeldete Benutzer ausgeführt wird. Wenn nicht, wird das Programm mit einem Fehler beendet.
3. Verwaltung des Registers
a. Das Skript verwendet eine Hilfsfunktion, um Registrierungsschlüssel für den Anzeigenamen und das optionale Symbol der Anwendung zu erstellen oder zu aktualisieren. Dies gewährleistet die korrekte Zuordnung und das Branding der Meldungen.
4. Bildbearbeitung
a. Das Skript kann ein Bild von einer URL herunterladen oder eine lokale Datei verwenden. Dadurch wird sichergestellt, dass das Bild in einem öffentlichen Ordner gespeichert wird, damit es zugänglich ist.
b. Wenn kein gültiges Bild angegeben wird, wird das Skript ohne Bild fortgesetzt.
5. Erstellung von Benachrichtigungen
a. Mithilfe von Windows-APIs erstellt das Skript eine Toast-Benachrichtigung und zeigt sie an.
b. Die Benachrichtigung enthält den angegebenen Titel und die Nachricht und schließt das Bild ein, falls vorhanden.
6. Fehlerbehandlung:
a. Das Skript verfügt über eine robuste Fehlerbehandlung, einschließlich Warnungen für nicht unterstützte Konfigurationen, fehlgeschlagene Downloads und fehlende Parameter.
Potenzielle Anwendungsfälle
Fallstudie: Ankündigung der IT-Wartung
Ein IT-Administrator, der ein Unternehmensnetzwerk verwaltet, muss die Benutzer über geplante Wartungsarbeiten informieren. Mit diesem Skript sendet der Administrator eine Toast-Benachrichtigung mit den folgenden Angaben:
- Titel: “Geplante Wartung um 22 Uhr”
- Nachricht: “Bitte speichern Sie Ihre Arbeit. Die Systeme werden ab 22 Uhr für zwei Stunden ausfallen
- Bild: Ein Firmenlogo, das unter einer öffentlichen URL gehostet wird.
Auf diese Weise wird sichergestellt, dass die Nutzer eine klare und markenbezogene Botschaft direkt auf ihrem Desktop erhalten.
Vergleiche mit anderen Methoden
Integrierte Benachrichtigungstools
Windows verfügt zwar über integrierte Benachrichtigungsfunktionen, diese erfordern jedoch häufig eine komplexe Einrichtung oder Software von Drittanbietern. Dieses Skript vereinfacht den Prozess und bietet mehr Anpassungsmöglichkeiten.
Kundenspezifische Software-Lösungen
Benutzerdefinierte Benachrichtigungssoftware kann ähnliche Funktionen bieten, allerdings zu einem höheren Preis. Dieses Skript bietet eine leichtgewichtige, kostengünstige Alternative, die auf PowerShell-erfahrene Profis zugeschnitten ist.
Häufig gestellte Fragen
- Kann ich dieses Skript unter Windows 7 oder älteren Versionen verwenden?
Nein, das Skript ist aufgrund der Abhängigkeit von modernen Windows-APIs für Windows 10 und höher konzipiert. - Welche Bildformate werden unterstützt?
Das Skript unterstützt .png-Dateien. Stellen Sie sicher, dass die Dateigröße unter 2 MB liegt, um eine optimale Leistung zu erzielen. - Ist es möglich, dieses Skript für mehrere Benutzer zu automatisieren?
Ja, Sie können dieses Skript in einen größeren Automatisierungsrahmen integrieren, aber es muss im Kontext jedes angemeldeten Benutzers laufen.
Auswirkungen der Verwendung dieses Skripts
Die Bereitstellung von Benachrichtigungen mit Bildern verbessert das Engagement der Benutzer und stellt sicher, dass wichtige Informationen wahrgenommen werden. Die Verwalter müssen jedoch vorsichtig sein, um eine Überbeanspruchung zu vermeiden, die zu Meldungsmüdigkeit führen könnte. Außerdem unterstreicht dieses Skript die Bedeutung sicherer und effizienter Kommunikationskanäle im IT-Betrieb.
Best Practices bei der Verwendung dieses Skripts
- Anpassen von Benachrichtigungen
Passen Sie den Titel und die Botschaft so an, dass sie für den Endnutzer relevant und klar sind. - Komprimierte Bilder verwenden
Optimieren Sie die Bilder, um die Dateigröße zu verringern und ein schnelles Laden zu gewährleisten, insbesondere bei Verbindungen mit Gebühreneinzug. - Test in einer kontrollierten Umgebung
Testen Sie das Skript, bevor Sie es in großem Umfang einsetzen, um Kompatibilität und Wirksamkeit sicherzustellen. - Eine saubere Registrierung beibehalten
Überprüfen Sie regelmäßig die vom Skript erstellten Registrierungseinträge, um Unordnung zu vermeiden.
Abschließende Überlegungen
PowerShell ist nach wie vor ein vielseitiges Tool für IT-Experten, und dieses Skript veranschaulicht sein Potenzial bei der Optimierung der Benutzerkommunikation. NinjaOne ergänzt diese Tools durch eine robuste Suite von IT-Management-Lösungen, die es MSPs und IT-Abteilungen ermöglichen, nahtlosen und effizienten Support zu leisten. Unabhängig davon, ob Sie IT-Administrator oder MSP sind, kann die Integration solcher Skripte in Ihre Arbeitsabläufe Ihre betriebliche Effizienz und die Zufriedenheit der Benutzer erheblich steigern.