> For the complete documentation index, see [llms.txt](https://documentation.2pintsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.2pintsoftware.com/deployr/automation-and-powershell/deployr-utility-module-reference.md). # DeployR.Utility module reference Reference for the commands in the DeployR.Utility PowerShell module, grouped by task, including the commands added in DeployR 1.4. The `DeployR.Utility` module is used in two places: * **On the DeployR server**, to automate the server: managing content items, task sequences, and step definitions, importing driver packs and cloud operating systems, and creating media. Import it from `C:\Program Files\2Pint Software\DeployR\Client\PSModules\DeployR.Utility` and authenticate with `Connect-DeployR` first. See [Scripting for DeployR Server](/deployr/automation-and-powershell/scripting-for-deployr-server.md). * **Inside a running task sequence**, from **Run PowerShell script** steps and custom step definitions. Use `Import-Module DeployR.Utility`. In a task sequence, the module uses the task sequence's DeployR token automatically. See [Scripting for OSD](/deployr/automation-and-powershell/scripting-for-osd.md). Use PowerShell 7. For full syntax, run `Get-Help ` or `Get-Command -Syntax`. To list everything in the module, run `Get-Command -Module DeployR.Utility`. ## What's new in DeployR 1.4 The module version is now 1.4.0. **New commands** | Command | Summary | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | [Get-DeployRCloudOS, Import-DeployRCloudOS](#get-deployrcloudos-and-import-deployrcloudos) | Find Windows images in the cloud OS catalog and import them as content items. | | [ConvertTo-DeployRFFU](#convertto-deployrffu) | Creates an FFU content item from an operating system (WIM) content item. | | [Get-DeployRDiskSectorSize](#get-deployrdisksectorsize) | Returns the logical sector size of a disk. | | [Invoke-DeployRStreamFFU](#invoke-deployrstreamffu) | Writes an FFU image directly to a disk. | | [Show-DeployRMessageBox](#show-deployrmessagebox) | Shows a message box in the progress UI and returns the button that was clicked. | | [Set-DeployRProgressWindow](#set-deployrprogresswindow) | Minimizes or restores the progress UI. | | [Invoke-DeployRApiRestMethod](#invoke-deployrapirestmethod) | Calls the 2Pint cloud service used for the driver pack and cloud OS catalogs. | **Changed commands** * `Connect-DeployR`: Entra ID browser sign-in uses a random local port instead of port 7285, with PKCE and state validation, and times out after five minutes. * `New-DeployRMedia`: new `SelfUpdating` media type. See [Performing media-based deployments](/deployr/deployment-methods/performing-media-based-deployments.md). * `Get-DeployROemDriverPack`: new `-ListAll` switch. * `Request-DeployRCustomContent`: new `-Hash` parameter to verify the download. * All commands that call the DeployR server now retry transient network failures up to 15 times (previously 3). Some other recent additions, such as `Remove-DeployRMetadata`, `Set-DeployRLogPath`, `Export-DeployRContentItem -ExcludeDeprecated`, the `Boot` media type, and `New-DeployRMedia -TempPath`, were also made available in DeployR 1.3 updates. ## Connecting | Command | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Connect-DeployR` | Authenticates to the DeployR server and saves the token for the other commands. With `-Passcode` or `-Credential`, only that method is used. Otherwise it tries anonymous access, then Windows integrated authentication (if enabled on the server), then Entra ID. Use `-Url` to connect to a server other than the local one. | | `Get-DeployRHost` / `Set-DeployRHost` | Gets or sets the DeployR server URL used by the other commands. On the DeployR server, it is set automatically when the module is imported. | | `Get-DeployRSetting` | Reads a DeployR server setting from the registry. Only works on the DeployR server. | For Entra ID sign-in in a browser, `Connect-DeployR` opens the default browser and waits up to five minutes for the sign-in to finish. When the server is configured for device code flow, it shows a code to enter instead. ## Task sequences, step definitions, and content items | Command | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Get-DeployRMetadata -Type [-Id ]` | Returns items of the given type: `TaskSequence`, `TaskSequenceVersion`, `ContentItem`, `ContentItemVersion`, `StepDefinition`, `StepDefinitionVersion`, or `BootImage`. Results are fetched in pages of `-PageSize` (default 100). | | `Set-DeployRMetadata -Type -Object ` | Saves changes to an item returned by `Get-DeployRMetadata`. | | [`Remove-DeployRMetadata`](#remove-deployrmetadata) | Deletes an item. | | `Get-DeployRTaskSequence`, `Get-DeployRTaskSequenceVersion` | Return task sequences and their versions. | | `Get-DeployRContentItem [-Id] [-Purpose]`, `Get-DeployRContentItemVersion` | Return content items and versions, optionally filtered by purpose: `OperatingSystem`, `Application`, `DriverPack`, `Other`, or `BootImage`. | | `Get-DeployRApplication`, `Get-DeployRApplicationVersion`, `Get-DeployROperatingSystem`, `Get-DeployROperatingSystemVersion`, `Get-DeployRDriverPack`, `Get-DeployRDriverPackVersion` | Shortcuts for content items and versions with a specific purpose. | | `New-DeployRContentItem`, `New-DeployRContentItemVersion` | Create a content item, and a version from a source folder. | | `Add-DeployRContentItemVersion`, `Update-DeployRContentItemContent` | Add a version from a definition object, or replace the files in an existing version. | | `Get-DeployRContentItemVersionContentInfo` | Returns details about the files in a content item version. | | `Export-DeployRTaskSequence`, `Export-DeployRStepDefinition`, `Export-DeployRContentItem` | Export items to a folder, for backup or to move them to another server. `Export-DeployRContentItem -ExcludeDeprecated` leaves out versions marked as deprecated. | | `Import-DeployRTaskSequence`, `Import-DeployRStepDefinition`, `Import-DeployRContentItem` | Import exported items. `Import-DeployRTaskSequence -Clone` creates a copy with a new ID. | For examples, see [Scripting for DeployR Server](/deployr/automation-and-powershell/scripting-for-deployr-server.md), [Step Definitions - Metadata](/deployr/automation-and-powershell/scripting-for-deployr-server/step-definitions-metadata.md), and [Content Items - Metadata](/deployr/automation-and-powershell/scripting-for-deployr-server/content-items-metadata.md). ### Remove-DeployRMetadata ```powershell Remove-DeployRMetadata -Type -Object ``` Deletes the item passed in `-Object` (or from the pipeline). The types are the same as for `Get-DeployRMetadata`. For version types, the object identifies both the parent and the version number, so pass a version object returned by DeployR. ```powershell # Delete all deprecated versions of a content item $ci = Get-DeployRContentItem -Id $id $ci.versions | Where-Object { $_.status -eq "Deprecated" } | Remove-DeployRMetadata -Type ContentItemVersion ``` {% hint style="warning" %} Deleting cannot be undone. Export the item first if you might need it again. {% endhint %} ## Driver packs and cloud operating systems These commands use the 2Pint cloud catalogs (the same ones the **Inject drivers from cloud** and **Apply operating system from cloud** steps use) and require DeployR Enterprise. | Command | Description | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Get-DeployROemDriverPack` | Finds driver packs in the OEM driver pack catalog. Run it with fewer parameters to list the valid values for the next one. `-ListAll` returns the whole catalog. See [Get-DeployROEMDriverPack](/deployr/automation-and-powershell/scripting-for-deployr-server/automating-content-item-creation/get-deployroemdriverpack.md). | | `Import-DeployROEMDriverPack` | Imports driver packs piped from `Get-DeployROemDriverPack` as content items. | | `Get-DeployRDriverPackFiltered` | Returns driver pack content item versions matching `-Manufacturer`, `-Model`, and `-Tags` (wildcards allowed). Inside a task sequence, it uses the list of content items available to the task sequence. | | [`Get-DeployRCloudOS`, `Import-DeployRCloudOS`](#get-deployrcloudos-and-import-deployrcloudos) | Find and import Windows images from the cloud OS catalog. | ### Get-DeployRCloudOS and Import-DeployRCloudOS ```powershell Get-DeployRCloudOS [-OS ] [-OSReleaseId ] [-OSArchitecture ] [-LanguageCode ] [-Edition ] [-DeployRApiUrl ] Import-DeployRCloudOS -InputObject ``` `Get-DeployRCloudOS` searches the catalog. Specify the parameters in order; when one is missing, the command returns the valid values for it. Once all five are given, it returns the matching images. Pipe them to `Import-DeployRCloudOS` to import them as content items. The import runs in the background on the DeployR server. See [Get-DeployRCloudOS](/deployr/automation-and-powershell/scripting-for-deployr-server/automating-content-item-creation/1.4-get-deployrcloudos.md). ## FFU images and disks ### ConvertTo-DeployRFFU ```powershell ConvertTo-DeployRFFU -Id [-Version ] [-Index ] [-SizeBytes ] [-LogicalSectorSize <512|4096>] ``` Creates an FFU image from a WIM in an operating system content item and uploads it as a new content item. Run it on the DeployR server. See [Creating FFU images](/deployr/content-management/creating-ffu-images.md) for requirements and examples. ### Get-DeployRDiskSectorSize ```powershell Get-DeployRDiskSectorSize -DiskNumber [-ToolPath ] ``` Returns the logical sector size of the disk, `512` or `4096`. It uses `Get-Disk` when the Storage module is available; otherwise, as in some Windows PE images, it uses the DeployR StreamFFU tool. The [Detect disk sector size](/deployr/reference/step-definitions/detect-disk-sector-size.md) step uses this command. ### Invoke-DeployRStreamFFU ```powershell Invoke-DeployRStreamFFU -Source -DiskNumber [-NoVerify] [-NoExtend] [-IgnoreCert] [-ToolPath ] ``` Writes an FFU image to a disk, reading it from a file or streaming it from a URL while it is written, so the image does not need to be downloaded first. When the source is on the DeployR server, the task sequence's DeployR token is sent automatically. Progress is shown as a standard PowerShell progress bar. The [Apply FFU](/deployr/reference/step-definitions/apply-ffu.md) step uses this command. | Parameter | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-NoVerify` | Skip the per-chunk hash verification of the image data as it is written. | | `-NoExtend` | Do not extend the partitions and file systems to fill the disk. By default they are extended, as `DISM /Apply-FFU` does, so an image captured from a smaller disk uses the whole target disk. | | `-IgnoreCert` | Do not validate the web server's TLS certificate. | | `-ToolPath` | Path to `TwoPint.DeployR.StreamFFU.dll`. Default: `X:\_2P\Client\TwoPint.DeployR.StreamFFU.dll`. | {% hint style="warning" %} Everything on the target disk is overwritten. {% endhint %} ## Content in a task sequence | Command | Description | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Request-DeployRContent -ContentName -ContentItemId -ContentItemVersion ` | Downloads a content item version for use by the current step and returns the local folder. In a task sequence, it also sets the `_CONTENT-` (and, for single files, `_CONTENTFILE-`) variables. | | `Request-DeployRCustomContent -ContentName -URL [-ContentSize ] [-Hash ]` | Downloads a file from any URL using the DeployR download engine, including BranchCache peering, and returns the local path. | | `Resolve-DeployRVariables ` | Replaces `%VARIABLE%` references in a string with task sequence variable values. `%NAME:5%` uses the leftmost 5 characters, and `%NAME:-5%` the rightmost 5. | | `Select-DeployRTags` | Filters objects by their OS tags (such as release and architecture tags) to those that match the operating system being deployed. | **`Request-DeployRCustomContent -Hash`** (new in 1.4): pass the lowercase hexadecimal SHA256 hash of the file. After downloading, DeployR checks the file against it. If the hash does not match, the download is retried from the beginning, and if it still does not match, the command fails and the file is not added to the BranchCache cache. ```powershell $file = Request-DeployRCustomContent -ContentName "Tool" -ContentFriendlyName "Support tool" ` -URL "https://downloads.contoso.com/tool.zip" -Hash "3f79bb7b435b05321651daefd374cdc681dc06faa65e374e38337b88ca046dea" ``` ## Progress UI and logging These commands only work inside a running task sequence. ### Show-DeployRMessageBox ```powershell Show-DeployRMessageBox [-Message] [[-Title] ] [-Buttons ] [-Icon ] [-DefaultButton <1-3>] [-TimeoutSeconds ] [-VariableName ] ``` Shows a message box in the progress UI and waits for a button to be clicked. Returns the button (`OK`, `Cancel`, `Abort`, `Retry`, `Ignore`, `Yes`, `No`, `TryAgain`, or `Continue`), or `Timeout` if `-TimeoutSeconds` (default `0`, no timeout) runs out. The result is also saved in the task sequence variable named by `-VariableName` (default `MessageBoxResult`). * `-Buttons`: `OK` (default), `OKCancel`, `YesNo`, `YesNoCancel`, `RetryCancel`, `AbortRetryIgnore`, or `CancelTryContinue`. * `-Icon`: `None` (default), `Information`, `Question`, `Warning`, or `Error`. The [Show message box](/deployr/reference/step-definitions/show-message-box.md) step provides the same function without a script. ### Set-DeployRProgressWindow ```powershell Set-DeployRProgressWindow [-State] ``` Minimizes or restores the progress UI, for example so that an installer's own window is not hidden behind it. Message boxes from `Show-DeployRMessageBox` are still shown while it is minimized. ```powershell Set-DeployRProgressWindow Minimized Start-Process -FilePath "setup.exe" -Wait Set-DeployRProgressWindow Restored ``` ### Set-DeployRLogPath ```powershell Set-DeployRLogPath [-Path] ``` Moves the DeployR client logs to the specified folder, creating it if needed. It updates the `_DEPLOYRLOGPATH` task sequence variable and the `_DeployRLogPath` environment variable, and DeployR moves its own log to the new location, which is kept across reboots. The built-in steps that change drive letters, such as **Format disk**, **Clean drive**, and **Apply FFU**, use it to move the logs to `S:\_2P\logs`. See [Log files and custom logging](/deployr/monitoring-and-reporting/log-files-and-custom-logging.md). ## Calling the APIs directly | Command | Description | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `Invoke-DeployRRestMethod -RelativeUri ` | Calls a DeployR server REST API with the current token, for example `/v1/TaskSequence`. | | `Invoke-DeployRWebRequest -RelativeUri [-OutFile ]` | Same, but returns the raw response or saves it to a file. | | `Invoke-DeployRWebService -Url ` | Calls a web service from a task sequence, passing the task sequence variables. | | [`Invoke-DeployRApiRestMethod`](#invoke-deployrapirestmethod) | Calls the 2Pint cloud service. | ### Invoke-DeployRApiRestMethod ```powershell Invoke-DeployRApiRestMethod -RelativeUri [-Method ] [-Body ] [-ContentType ] [-DeployRApiUrl ] ``` Calls the 2Pint cloud service that hosts the driver pack and cloud OS catalogs, with retries for transient failures. The service URL comes from `-DeployRApiUrl`, then the `DEPLOYRAPIURL` task sequence variable, then the default `https://api.service.2pintsoftware.com`. ## Secrets `Get-Secret` and `Set-Secret` come from the Microsoft SecretManagement module that ships with DeployR, using the `DeployR` vault. See [Set-Secret | Get-Secret](/deployr/automation-and-powershell/scripting-for-osd/set-secret-or-get-secret.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://documentation.2pintsoftware.com/deployr/automation-and-powershell/deployr-utility-module-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.