Usare Powershell per creare un messaggio di notifica popup con immagine in Windows

Una comunicazione efficace con gli utenti è fondamentale per i professionisti dell’IT, soprattutto negli ambienti dei provider di servizi gestiti (MSP). Un modo pratico per interagire con gli utenti finali è rappresentato dalle notifiche di sistema. Questo script PowerShell consente agli amministratori IT di inviare messaggi toast con immagini eroiche opzionali, offrendo un metodo facile da usare per trasmettere aggiornamenti importanti, promemoria o avvisi. Ecco un approfondimento su questo script per creare un messaggio di notifica, sulle sue funzionalità e sulle sue potenziali applicazioni.

Contesto e importanza

Le notifiche di sistema servono come linea di comunicazione diretta tra gli amministratori IT e gli utenti, soprattutto in ambienti in cui le notifiche via e-mail o chat potrebbero essere perse o ignorate. Questo script si distingue perché non solo fornisce messaggi toast personalizzabili, ma consente anche l’inclusione di immagini “hero”, per rendere le notifiche visivamente coinvolgenti.

Gli MSP e i reparti IT utilizzano spesso strumenti come questo per migliorare la comunicazione con gli utenti, per annunciare per esempio una manutenzione programmata, per avvisare gli utenti di problemi critici o per fornire guide passo per passo. Sfruttando il sistema di notifiche nativo di Windows 10, questo script per creare un messaggio di notifica si integra perfettamente nel flusso di lavoro dell’utente senza richiedere l’installazione di software aggiuntivi.

Lo script per creare un messaggio di notifica:

#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 {
    
    
    
}

 

Descrizione dettagliata dello script

Questo script PowerShell per creare un messaggio di notifica è progettato per essere eseguito dall’utente attualmente connesso. Ecco una spiegazione passo per passo del suo flusso di lavoro:

1.Parametri e impostazioni predefinite

a. Lo script per creare un messaggio di notifica accetta parametri per il titolo, il messaggio, l’ID dell’applicazione e un percorso opzionale per un file immagine.

b. Se l’ID dell’applicazione non viene specificato, lo script per creare un messaggio di notifica si basa sul nome dell’azienda memorizzato nella variabile d’ambiente NINJA_COMPANY_NAME o fa riferimento a “NinjaOne RMM”.

c. Se non viene fornita un’immagine, la notifica verrà visualizzata senza immagine.

2. Convalida dell’ambiente

a. Lo script per creare un messaggio di notifica controlla se viene eseguito come utente correntemente connesso. In caso contrario, termina con un errore.

3. Gestione del registro

a. Lo script per creare un messaggio di notifica utilizza una funzione helper per creare o aggiornare le chiavi di registro per il nome visualizzato dell’applicazione e l’icona opzionale. In questo modo si garantisce che attribuzione e personalizzazione delle notifiche siano corrette.

4. Gestione delle immagini

a. Lo script per creare un messaggio di notifica può scaricare un’immagine da un URL o utilizzare un file locale. Questo garantisce che l’immagine sia salvata in una cartella pubblica per l’accessibilità.

b. Se non viene fornita alcuna immagine valida, lo script procede senza alcuna immagine.

5. Creazione della notifica

a. Utilizzando le API di Windows, lo script costruisce e visualizza una notifica di toast.

b. La notifica include il titolo e il messaggio specificati e incorpora l’immagine, se fornita.

6. Gestione degli errori

a. Lo script per creare un messaggio di notifica è dotato di una solida gestione degli errori, compresi gli avvisi per le configurazioni non supportate, per i download falliti e per i parametri mancanti.

Casi d’uso potenziali

Caso di studio: Annuncio di manutenzione IT

Un amministratore IT che gestisce una rete aziendale deve notificare agli utenti la manutenzione programmata. Utilizzando questo script per creare un messaggio di notifica, l’amministratore invia una notifica di toast con i seguenti dettagli:

• Titolo: “Manutenzione programmata alle 22:00”
• Messaggio: “Per favore, salva il tuo lavoro. I sistemi saranno fermi per due ore a partire dalle 22”.
• Immagine: Un logo aziendale ospitato su un URL pubblico.

Questo approccio garantisce che gli utenti ricevano un messaggio chiaro e personalizzato direttamente sul loro desktop.

Confronto con altri metodi

Strumenti di notifica integrati

Sebbene Windows disponga di funzioni di notifica integrate, spesso richiedono un’impostazione complessa o un software di terze parti. Questo script semplifica il processo per creare un messaggio di notifica e offre una maggiore personalizzazione.

Soluzioni software personalizzate

I software per le notifiche personalizzate possono offrire funzioni simili, ma a un costo. Questo script offre un’alternativa leggera e conveniente per creare un messaggio di notifica, pensata per i professionisti esperti di PowerShell.

Domande frequenti

1. Posso utilizzare questo script su Windows 7 o versioni precedenti?
   No, lo script per creare un messaggio di notifica è progettato per Windows 10 e versioni successive a causa della dipendenza dalle moderne API di Windows.
2. Quali sono i formati di immagine supportati?
   Lo script per creare un messaggio di notifica supporta i file .png. Assicurati che la dimensione del file sia inferiore a 2 MB per ottenere prestazioni ottimali.
3. Posso automatizzare questo script per più utenti?
   Sì, puoi integrare questo script per creare un messaggio di notifica in un framework di automazione più ampio, ma deve essere eseguito nel contesto di ciascun utente connesso.

Implicazioni dell’uso di questo script

La distribuzione di notifiche con immagini migliora il coinvolgimento degli utenti, garantendo che le informazioni critiche vengano viste. Tuttavia, gli amministratori devono fare attenzione a non farne un uso eccessivo, perché potrebbe portare allo stress da notifica. Inoltre, questo script per creare un messaggio di notifica sottolinea l’importanza di canali di comunicazione sicuri ed efficienti nelle operazioni IT.

Best practice per l’utilizzo di questo script

1. Personalizza le notifiche
   Adatta il titolo e il messaggio per garantire la pertinenza e la chiarezza per l’utente finale.
2. Utilizza immagini compresse
   Ottimizza le immagini per ridurre le dimensioni dei file e garantire un caricamento rapido, soprattutto sulle connessioni con larghezza di banda limitata o a consumo.
3. Testa in un ambiente controllato
   Prima di distribuirlo in modo ampio, testa lo script per creare un messaggio di notifica, per garantirne la compatibilità e l’efficacia.
4. Mantieni un registro pulito
   Esamina regolarmente le voci di registro create dallo script per evitare che si accumulino.

Considerazioni finali

PowerShell rimane uno strumento versatile per i professionisti dell’IT e questo script per creare un messaggio di notifica è un esempio del suo potenziale nel semplificare la comunicazione con gli utenti. NinjaOne integra strumenti come questo offrendo una solida suite di soluzioni per la gestione dell’IT, che consente agli MSP e ai reparti IT di fornire un’assistenza continua ed efficiente. Che tu sia un amministratore IT o un MSP, l’integrazione di questi script nel tuo flusso di lavoro può migliorare in modo significativo l’efficienza operativa e la soddisfazione degli utenti.