Set lock screen wallpaper

[PastLives-GIT]

Set-LockScreen.ps1 Script Description

Introduction

Set-LockScreen.ps1 is a PowerShell script that sets the specified image file as the lock screen wallpaper for the current Windows user.
It calls the Windows.System.UserProfile.LockScreen API from the Windows Runtime (WinRT) and does not require administrator privileges.

---

Features

• Accepts an image file path as input
• Automatically checks whether the file exists
• Supports common image formats (JPG, PNG, BMP, etc.)
• Sets the lock screen background for the current user
• Provides detailed error messages and status feedback

---

Parameters

Parameter	Required	Type	Description
Path	Yes	String	Full or relative path to the image file

The parameter position is 0, so the path can be passed directly as a positional parameter without specifying -Path.

---

Usage

1. Save the script

Save the script content as Set-LockScreen.ps1.

2. Run the script

Option 1: Configure in scripts.yaml

Example:

Enabled: true
Component:
  Scripts:
    - Name: SetLockScreenWallpaper
      Command: powershell
      ArgsLight:
        - -NoProfile
        - -ExecutionPolicy
        - Bypass
        - -File
        - <path-to-script>\Set-LockScreen.ps1
        - -Path
        - <path-to-image>
      ArgsDark:
        - -NoProfile
        - -ExecutionPolicy
        - Bypass
        - -File
        - <path-to-script>\Set-LockScreen.ps1
        - -Path
        - <path-to-image>
      TimeoutMillis: 10000
      AllowedSources: [Any]

Replace <path-to-script> with the actual directory where you saved the script, and <path-to-image> with the full path to your target image.

Option 2: Run directly with PowerShell (for testing before configuring in scripts.yaml)

In Windows PowerShell 5.1, run:

<path-to-script>\Set-LockScreen.ps1 -Path "<path-to-image>"

Or use a positional parameter directly:

<path-to-script>\Set-LockScreen.ps1 "<path-to-image>"

If the execution policy prevents the script from running, use:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File <path-to-script>\Set-LockScreen.ps1 -Path "<path-to-image>"

---

Complete Script Source Code

<#
.SYNOPSIS
    将指定图片设置为 Windows 锁屏壁纸。
.DESCRIPTION
    使用 Windows.System.UserProfile.LockScreen API 设置当前用户的锁屏背景。
.PARAMETER Path
    图片文件的完整或相对路径。
.EXAMPLE
    .\Set-LockScreen.ps1 -Path "C:\Users\Public\Pictures\lock.jpg"
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true, Position = 0)]
    [ValidateNotNullOrEmpty()]
    [string]$Path
)

$ErrorActionPreference = 'Stop'

# 解析为绝对路径，并检查文件是否存在
$fullPath = [System.IO.Path]::GetFullPath($Path)
if (-not (Test-Path -LiteralPath $fullPath -PathType Leaf)) {
    Write-Error "找不到图片文件: $fullPath"
}

# 可选：检查常见图片扩展名
$allowedExtensions = @('.jpg', '.jpeg', '.png', '.bmp', '.gif', '.tif', '.tiff', '.jfif')
$extension = [System.IO.Path]::GetExtension($fullPath)
if ($allowedExtensions -notcontains $extension.ToLowerInvariant()) {
    Write-Warning "文件扩展名 '$extension' 可能不受锁屏壁纸 API 支持。"
}

# 加载 WinRT 异步等待辅助程序集
Add-Type -AssemblyName System.Runtime.WindowsRuntime

function Wait-WinRTAsyncAction {
    param($AsyncAction)

    $asTaskMethod = [System.WindowsRuntimeSystemExtensions].GetMethods() |
        Where-Object {
            $_.Name -eq 'AsTask' -and
            $_.GetParameters().Count -eq 1 -and
            $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncAction'
        } |
        Select-Object -First 1

    if ($null -eq $asTaskMethod) {
        throw '无法加载 WinRT IAsyncAction 转换方法。'
    }

    $task = $asTaskMethod.Invoke($null, @($AsyncAction))
    $task.Wait(-1) | Out-Null
}

function Wait-WinRTAsyncOperation {
    param($AsyncOperation, [Type]$ResultType)

    $asTaskMethod = [System.WindowsRuntimeSystemExtensions].GetMethods() |
        Where-Object {
            $_.Name -eq 'AsTask' -and
            $_.GetParameters().Count -eq 1 -and
            $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1'
        } |
        Select-Object -First 1

    if ($null -eq $asTaskMethod) {
        throw '无法加载 WinRT IAsyncOperation<T> 转换方法。'
    }

    $genericMethod = $asTaskMethod.MakeGenericMethod($ResultType)
    $task = $genericMethod.Invoke($null, @($AsyncOperation))
    $task.Wait(-1) | Out-Null
    return $task.Result
}

# 加载 WinRT 类型
[Windows.Storage.StorageFile, Windows.Storage, ContentType = WindowsRuntime] | Out-Null
[Windows.System.UserProfile.LockScreen, Windows.System.UserProfile, ContentType = WindowsRuntime] | Out-Null

try {
    # 获取 StorageFile 对象
    $storageFile = Wait-WinRTAsyncOperation `
        -AsyncOperation ([Windows.Storage.StorageFile]::GetFileFromPathAsync($fullPath)) `
        -ResultType ([Windows.Storage.StorageFile])

    # 设置为锁屏壁纸
    Wait-WinRTAsyncAction `
        -AsyncAction ([Windows.System.UserProfile.LockScreen]::SetImageFileAsync($storageFile))

    Write-Host "锁屏壁纸已设置为：$fullPath"
}
catch {
    $msg = $_.Exception.Message
    if ($_.Exception.InnerException) {
        $msg += " -> " + $_.Exception.InnerException.Message
    }
    Write-Error "设置锁屏壁纸失败：$msg"
}

---

How It Works

1. Path resolution and validation
   Converts the input path to an absolute path using [System.IO.Path]::GetFullPath() and checks whether the file exists with Test-Path.

2. Format check
   Checks whether the file extension is a common image format and warns if it is not in the list.

3. Load the WinRT helper assembly
   Loads the required assembly with Add-Type -AssemblyName System.Runtime.WindowsRuntime to handle WinRT asynchronous operations.

4. Define async wait functions

   • Wait-WinRTAsyncAction: Waits for an IAsyncAction to complete.
   • Wait-WinRTAsyncOperation: Waits for an IAsyncOperation<T> to complete and returns the result.

5. Call the WinRT API

   • Uses [Windows.Storage.StorageFile]::GetFileFromPathAsync() to obtain a StorageFile object.
   • Calls [Windows.System.UserProfile.LockScreen]::SetImageFileAsync() to set the file as the lock screen wallpaper.

6. Result feedback
   Outputs a success message in green, or detailed error information if the operation fails.

---

Notes

• Save the script with UTF-8 BOM encoding.
• This script only changes the lock screen wallpaper for the current user and does not require administrator privileges.
• Common formats such as .jpg, .png, and .bmp are recommended. Other formats may not be supported by the lock screen API.
• If the image file is locked or corrupted, the operation may fail.
• This script is based on the WinRT API and is only valid on Windows 8 or later (Windows 10/11 recommended).

---

Summary

This script provides a simple and reliable way for users to quickly change the Windows lock screen wallpaper from the command line. It uses the system's native API, avoiding third-party tools or registry modifications, and is suitable for automated deployment or personal use.

Enjoy the pleasure of tinkering!