en-US/PSModuleUpdate-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>Get-PSModuleUpdate</command:name>
      <maml:description>
        <maml:para>Creates a read-only exact-version update plan for an installed PowerShell module.</maml:para>
      </maml:description>
      <command:verb>Get</command:verb>
      <command:noun>PSModuleUpdate</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Inspects a compatible installed module in CurrentUser or AllUsers and one explicitly selected repository.
The target need not be loaded, be the caller, or depend on PSModuleUpdate.
PMU is a standalone shared module; consumers own repository configuration and
the decision about when to check for updates.
Policy defaults to Stable and CurrentUser.
Credentials are used only in memory.

`Policy` accepts only `Channel` (`Stable` or `IncludePrerelease`), `Scope`
(`CurrentUser` or `AllUsers`), `ExpectedRepositoryUri` (`System.Uri` or null),
and `VersionRange` (provider-supported NuGet range string or null). The latter
two default to null. IncludePrerelease includes stable releases as well.
The explicitly selected scope must already contain the matching name and GUID;
PMU never creates a shadow installation or changes scope.

Ordinary resource folders beside numeric version directories do not count as
installed copies. This allows a versioned installation to coexist with resource
folders left by a legacy flat installation, without migrating or selecting the
flat copy. Numeric directories and directories containing the target module's
manifest still undergo manifest and layout validation.

The manifest supplies installed prerelease identity. The `Active*` fields
describe a matching module actually loaded in the session and are null when
the target is unloaded.
`RestartRequired` inspects actual loaded copies; PMU never imports the target
to plan or apply an update. A plan binds one exact
target from one repository and never authorizes a downgrade. Planning does not
write installation locks, staging files, or installation journals.

Choose either `Repository` or `RepositoryUri`, never both. A unique existing
registration for the URI is reused and source-bound; ambiguous registrations
are rejected. An unregistered URI uses an operation-owned temporary
registration. The endpoint, provider API, and trust policy remain bound across
discovery and installation even though temporary transport names change.
Removing or repointing a bound consumer registration never causes alias
selection or fallback to another source.

If the provider does not disclose a package's license-acceptance requirement,
the plan conservatively sets `RequiresLicenseAcceptance` to true. Installation
then requires explicit `-AcceptLicense`; PMU never interprets absent metadata
as permission to accept a license or allow a provider prompt.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Get-PSModuleUpdate</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Module</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">psmoduleinfo</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSModuleInfo</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Repository</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">string</command:parameterValue>
          <dev:type>
            <maml:name>System.String</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Policy</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">hashtable</command:parameterValue>
          <dev:type>
            <maml:name>System.Collections.Hashtable</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Credential</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">pscredential</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSCredential</maml:name>
          </dev:type>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Get-PSModuleUpdate</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Module</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">psmoduleinfo</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSModuleInfo</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>RepositoryUri</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">uri</command:parameterValue>
          <dev:type>
            <maml:name>System.Uri</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Policy</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">hashtable</command:parameterValue>
          <dev:type>
            <maml:name>System.Collections.Hashtable</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Credential</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">pscredential</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSCredential</maml:name>
          </dev:type>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Credential</maml:name>
        <maml:description>
          <maml:para>Optional per-call provider credential.
Supply it again when installing.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.PSCredential</command:parameterValue>
        <dev:type>
          <maml:name>System.Management.Automation.PSCredential</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Module</maml:name>
        <maml:description>
          <maml:para>One compatible installed module reference; no import or PMU dependency is required.
Name and GUID must match its on-disk manifest.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.PSModuleInfo</command:parameterValue>
        <dev:type>
          <maml:name>System.Management.Automation.PSModuleInfo</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Policy</maml:name>
        <maml:description>
          <maml:para>Channel, Scope, ExpectedRepositoryUri (Uri), and VersionRange.
Unknown keys are rejected.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Collections.Hashtable</command:parameterValue>
        <dev:type>
          <maml:name>System.Collections.Hashtable</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Repository</maml:name>
        <maml:description>
          <maml:para>One literal registered PSResourceGet repository name.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>
        <dev:type>
          <maml:name>System.String</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>RepositoryUri</maml:name>
        <maml:description>
          <maml:para>One absolute repository endpoint. Cannot be combined with `Repository`.
PMU reuses a unique existing registration or creates a temporary owned
registration; ambiguous consumer registrations are rejected.
Credentials, query strings, and fragments must not be embedded in the URI.
One absolute repository endpoint.
Cannot be combined with `Repository`.
PMU reuses a unique existing registration or creates a temporary owned
registration; ambiguous consumer registrations are rejected.
Credentials, query strings, and fragments must not be embedded in the URI.
One absolute repository endpoint.
Cannot be combined with `Repository`.
PMU reuses a unique existing registration or creates a temporary owned
registration; ambiguous consumer registrations are rejected.
Credentials, query strings, and fragments must not be embedded in the URI.
One absolute repository endpoint.
Cannot be combined with `Repository`.
PMU reuses a unique existing registration or creates a temporary owned
registration; ambiguous consumer registrations are rejected.
Credentials, query strings, and fragments must not be embedded in the URI.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Uri</command:parameterValue>
        <dev:type>
          <maml:name>System.Uri</maml:name>
        </dev:type>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>PSModuleUpdate.UpdatePlan</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A live schema-1, data-only plan with active and selected-scope installation
identity, repository snapshot, exact target, policy, disposition, and
prerequisites. It contains no credential and is not a durable authorization token.

`ModuleName` and `ModuleGuid` identify the target. `Scope` and `DestinationRoot`
identify the selected installation scope and its Modules root.
`InstalledManifestPath` is the selected existing manifest **file**;
`InstalledVersion` is its complete version. `TargetVersion` is the exact semantic
target, `TargetNumericVersion` is its numeric directory version, and
`TargetInstalledPath` is the exact target **directory**.

`ObservedInstalledVersions` contains validated discovered copies from both
supported scopes, with `Scope`, `Root`, `ManifestPath`, `Guid`, `FullVersion`,
`NumericVersion`, and `Prerelease`. Planning must first succeed in an explicitly
selected scope with an existing installation. The CurrentUser default is not
automatic scope inference from the supplied reference.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>Requires PowerShell 7.4 or later and the qualified PSResourceGet 1.2.0 baseline.
Missing provider setup, unavailable packages, authentication failures, unsafe
paths, and identity mismatches are terminating structured PMU errors, not
UpToDate results. Credentials must be supplied independently to installation.
They must also be supplied independently to `Get-PSModuleUpdateTargetManifest`
when candidate metadata inspection is needed. Inspection does not alter this
plan or cause ordinary planning to stage/download packages.

When no eligible package exists in the explicitly selected repository,
discovery terminates with the stable error ID `PMU.PackageNotFound` and returns
no update plan. This includes the provider's structured `PackageNotFound`
failure. PMU does not query another feed or substitute another version.
Other discovery, authentication and permission failures retain their distinct
PMU errors; raw provider diagnostics are withheld to protect credentials.

PSResourceGet 1.2.0 Find/Save/Install expose repository names, not a direct URI
parameter. PMU serializes its own registration changes with a per-user
exclusive-handle lock and uses collision-resistant names plus flushed nonsecret
ownership receipts. It never overwrites a registration, changes global trust,
or stores credentials in registration metadata. Cleanup validates exact
ownership and configuration; it never removes registrations by prefix alone.
These safeguards do not establish a transaction with non-cooperating registry
writers. Termination between registration and durable provider-API binding can
require manual intervention; cleanup fails closed rather than guessing.
On macOS the provider store is under the actual LocalApplicationData
`PSResourceGet/PSResourceRepository.xml`; changing HOME alone does not isolate it.

One generic PSResourceGet adapter is used for compatible registered feeds.
PSGallery, NuGet.org, Azure Artifacts, and Nexus do not have vendor-specific
branches. External-feed behavior requires separate qualification; protocol
compatibility is not a live-validation claim.

If the original installation vanished, a module reference from its surviving
PMU backup can reach recovery only when the backup matches a validated
unfinished journal, scope, root, GUID, and complete version. Approval is still
required for repair, and recovery invalidates the old plan. If neither a valid
installation nor backup identity survives, manual recovery is required.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Get-PSModuleUpdate -Module (Get-Module ExampleModule) -Repository PSGallery
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Creates a stable CurrentUser update plan without changing installed files.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
Get-PSModuleUpdate -Module $installed -RepositoryUri ([uri]'https://api.nuget.org/v3/index.json')
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>`$installed` is a compatible installed `PSModuleInfo`, not necessarily loaded.
An existing unique registration is reused; otherwise PMU temporarily registers
the endpoint for transport and cleans up its owned registration.
General NuGet packages without a valid PowerShell module manifest are rejected.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$plan = Get-PSModuleUpdate -Module $installed -RepositoryUri $privateRepositoryUri -Credential $credential
$plan | Install-PSModuleUpdate -Credential $credential -AcceptLicense -TrustRepository
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>The caller supplies the private endpoint and credential independently to each
command. PMU does not read an environment token, store credentials, or modify
an existing registration.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <maml:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>about_Modules</maml:linkText>
        <maml:uri>https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_modules</maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Get-PSModuleUpdateTargetManifest</command:name>
      <maml:description>
        <maml:para>Downloads and safely reads the exact target manifest of one live update plan.</maml:para>
      </maml:description>
      <command:verb>Get</command:verb>
      <command:noun>PSModuleUpdateTargetManifest</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Inspects only the bound repository and exact planned candidate in an owned temporary
workspace.
Does not install, import, or execute the target.
Binds the manifest internally
to the unmodified live plan; installation rejects a differing staged manifest.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Get-PSModuleUpdateTargetManifest</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Plan</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
          <dev:type>
            <maml:name>System.Object</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>Credential</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">pscredential</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSCredential</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>TrustRepository</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>AcceptLicense</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>AcceptLicense</maml:name>
        <maml:description>
          <maml:para>Explicit acceptance of declared or undisclosed package license requirements.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
        <maml:name>Credential</maml:name>
        <maml:description>
          <maml:para>Optional per-call provider credential.
Never retained; supply it again to installation.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.PSCredential</command:parameterValue>
        <dev:type>
          <maml:name>System.Management.Automation.PSCredential</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="0" aliases="none">
        <maml:name>Plan</maml:name>
        <maml:description>
          <maml:para>An unmodified live plan from Get-PSModuleUpdate in this same module instance.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Object</command:parameterValue>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>TrustRepository</maml:name>
        <maml:description>
          <maml:para>Explicit operation-scoped approval of an untrusted repository.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>An unmodified live `PSModuleUpdate.UpdatePlan` from this same module instance.
Cloned, deserialized, edited, and other-instance plans are rejected.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>PSModuleUpdate.TargetManifest</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A data-only object with `Manifest` (the safely imported manifest hashtable,
including GUID, ModuleVersion, and complete PrivateData), `ModuleName`,
`ModuleGuid`, `Version` (the exact semantic target identity, including prerelease),
and sanitized `RepositoryUri`.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>Only the exact planned version and bound endpoint are queried. Inspection uses
the same native acquisition and package validation adapters as installation,
in an operation-owned temporary workspace under CurrentUser PMU data. It does
not import the target, execute its RootModule or scripts, mutate installed
files, or interpret consumer-specific PrivateData.

The public plan remains unchanged. PMU privately binds the inspected manifest
bytes to the original live plan. Installation compares its newly staged
manifest before installed-file mutation and terminates with
`PMU.TargetManifestChanged` if the content differs, even if name, GUID and version
still match. Editing this result cannot change that binding. Reinspection of
changed content requires a fresh plan; changes to whitespace alone also require
fresh approval. Plans that have not been inspected retain their existing behavior.

Repository trust and license acceptance have the same opt-in meanings as
installation. Inspection does not transfer consent or retain credentials.
Owned transport registrations and the inspection workspace are cleaned on
success and failure; unsafe cleanup fails closed. Planning and installation
`-WhatIf` remain acquisition-free.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$target = $plan | Get-PSModuleUpdateTargetManifest -TrustRepository -AcceptLicense
$target.Manifest.PrivateData
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Inspect the candidate metadata before independently approving installation with
`Install-PSModuleUpdate`. Credentials and consent must be supplied again to that
separate operation.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <maml:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>about_Modules</maml:linkText>
        <maml:uri>https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_modules</maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Install-PSModuleUpdate</command:name>
      <maml:description>
        <maml:para>Applies one live exact-version module update plan.</maml:para>
      </maml:description>
      <command:verb>Install</command:verb>
      <command:noun>PSModuleUpdate</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Revalidates and stages the exact package without importing it.
Same-base replacement uses
a verified backup, durable journal, exclusive OS handle lock, and best-effort rollback.
Only provider-generated root PSGetModuleInfo.xml is excluded from SHA256 tree comparison.
No module is hot reloaded.
Interrupted operations require safe recovery and a fresh plan.
The target is the compatible installed module bound by the plan, not
necessarily the caller or a loaded module. No dependency on PMU is required.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Install-PSModuleUpdate</maml:name>
        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Update</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
          <dev:type>
            <maml:name>System.Object</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Credential</maml:name>
          <maml:description />
          <command:parameterValue required="true" variableLength="false">pscredential</command:parameterValue>
          <dev:type>
            <maml:name>System.Management.Automation.PSCredential</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>AcceptLicense</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>TrustRepository</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>ReplaceUnmanagedInstallation</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>WhatIf</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none">
          <maml:name>Confirm</maml:name>
          <maml:description />
          <dev:type>
            <maml:name>System.Management.Automation.SwitchParameter</maml:name>
          </dev:type>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>AcceptLicense</maml:name>
        <maml:description>
          <maml:para>Explicitly accepts provider package license requirements for this operation.
Also required when the provider does not disclose whether acceptance is</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="cf">
        <maml:name>Confirm</maml:name>
        <maml:description>
          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Credential</maml:name>
        <maml:description>
          <maml:para>Per-call provider credential; never persisted.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Management.Automation.PSCredential</command:parameterValue>
        <dev:type>
          <maml:name>System.Management.Automation.PSCredential</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>ReplaceUnmanagedInstallation</maml:name>
        <maml:description>
          <maml:para>Explicitly allows replacing the selected manually copied installation only when
its root PSGetModuleInfo.xml is absent. Defaults to off. Present-but-unreadable or
mismatching metadata still fails. Uses native Install-Module for the exact planned
target, with Force only when its target directory collides. Existing identity,
repository, scope, backup, journal, tree verification and rollback checks remain.
This consent is per call and independent of AcceptLicense and TrustRepository.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>TrustRepository</maml:name>
        <maml:description>
          <maml:para>Allows this operation against an untrusted repository without changing its registration.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="Named" aliases="none">
        <maml:name>Update</maml:name>
        <maml:description>
          <maml:para>An unmodified live PSModuleUpdate.UpdatePlan from this module instance; pipeline by value.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Object</command:parameterValue>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="wi">
        <maml:name>WhatIf</maml:name>
        <maml:description>
          <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>
        </maml:description>
        <dev:type>
          <maml:name>System.Management.Automation.SwitchParameter</maml:name>
        </dev:type>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>An unmodified live `PSModuleUpdate.UpdatePlan` from this module instance.
Pipeline binding is by value only; serialized and manufactured plans are rejected.</maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>PSModuleUpdate.UpdateResult</maml:name>
        </dev:type>
        <maml:description>
          <maml:para>A schema-1 result reporting Outcome, ActiveVersion, InstalledVersion,
TargetVersion, verification, dependency observations, recovery, and restart
requirements independently. Outcomes are Installed, AlreadyInstalled, Cancelled,
and WhatIf. Provider success alone never produces Installed.</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>An optional prior `Get-PSModuleUpdateTargetManifest` call privately binds the
inspected manifest to this same live plan. Staging compares the complete
manifest content before installed-file mutation and rejects a difference with
`PMU.TargetManifestChanged`, including same-version republishing. Obtain a fresh
plan and inspect again before approving different content. Editing the returned
manifest hashtable cannot change that binding. Without prior inspection,
installation retains its existing behavior; `-WhatIf` does not stage/download.

After `VerificationStatus` is `Verified`, `InstalledPath` is the exact installed
target **directory**. `ModuleName`, `ModuleGuid`, `Scope`, `InstalledVersion`,
and `TargetVersion` identify its verified module, selected scope, observed
version and approved target. Construct the exact manifest path with
`Join-Path $result.InstalledPath "$($result.ModuleName).psd1"`.
There is no `InstalledManifestPath` property on installation results.

Credentials must be supplied again for each operation. Missing required
credentials and provider authentication failures use `PMU.AuthenticationFailed`;
repository trust and license opt-ins remain separate prerequisites.

Planning and WhatIf never perform recovery writes. After native approval, an
exclusive OS handle lock covers revalidation, staging, backup, replacement,
verification, rollback, and journal completion. Lock acquisition is bounded.
The exact target and selected CurrentUser or AllUsers scope never change.
AllUsers permission failures do not cause elevation or CurrentUser fallback.
The bound endpoint, API version, and trust state are revalidated before staging
and again before installation. Bound consumer registrations cannot be
repointed or silently replaced by aliases. An initially unregistered URI uses a
fresh operation-owned temporary registration after approval, with checked
cleanup. `-WhatIf` never creates one. Existing registrations are never modified.

Same-numeric-version prerelease progression uses exact native Save-Module staging.
Managed originals use Update-Module. ReplaceUnmanagedInstallation permits native
Install-Module only when the selected original lacks root PSGetModuleInfo.xml.
Without this opt-in, missing metadata still raises PMU.UnsupportedInstallation;
unreadable or mismatching existing metadata remains an error with the switch.
Planning needs no opt-in. WhatIf does not mutate files or acquire packages.
Native Force is used only for an unmanaged target-directory collision after GUID
validation and a verified backup. An already installed target still requires its
native metadata; the opt-in waives requirements only for the old installation.
Backups are outside Modules. Journals use flushed temporary files and atomic
file replacement; PMU does not claim atomic installation or guaranteed
power-loss recovery. Interrupted state and journal paths are untrusted and
validated before repair. Recovery that restores prior files requires a fresh
plan. A complete target is recognized only after complete-tree verification.

TrustRepository is operation-scoped and never changes repository trust.
AcceptLicense is independent of confirmation and trust. Missing or malformed
provider license metadata conservatively requires explicit acceptance.
Prerequisites are checked before quiet provider staging and installation, and
checked again under the mutation lock. Direct credentials are never persisted
or retained for later calls.

PMU does not import staged code or reload a consumer. RestartRequired includes
replacement of loaded files even when version text is unchanged. When a newer
target is installed while an older module remains loaded, restart is needed to
use the target.

Stable error identifiers include PMU.InvalidPlan, PMU.PlanStale,
PMU.RepositoryChanged, PMU.InstalledStateChanged, PMU.PermissionDenied,
PMU.LockTimeout, PMU.VerificationFailed, PMU.RecoveryRequired,
PMU.RecoveryFailed, and PMU.RollbackFailed. Preserve recovery evidence if repair
cannot be verified. A surviving verified PMU backup may supply the module
identity only when it matches a validated unfinished journal. Recovery requires
a fresh plan even if a complete interrupted target was already installed.

Windows, Linux, PowerShell 7.4, real AllUsers writes, and later provider versions
require separate qualification. Private stable installation has live
artifact-specific evidence; private prerelease progression remains NOT TESTED
unless an authorized live progression is recorded.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$plan | Install-PSModuleUpdate -WhatIf
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Revalidates read-only without locking, staging, installing, or repairing recovery state.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$plan | Install-PSModuleUpdate -AcceptLicense -TrustRepository
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Requests native confirmation before applying the exact approved target and scope.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>```powershell
$plan | Install-PSModuleUpdate -ReplaceUnmanagedInstallation
```</maml:para>
          <maml:para>&#x80;</maml:para>
          <maml:para>Explicitly replaces a manually copied installation without root PSGetModuleInfo.xml.
The exact planned target, repository and selected scope remain unchanged.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <maml:uri />
      </maml:navigationLink>
      <maml:navigationLink>
        <maml:linkText>about_Modules</maml:linkText>
        <maml:uri>https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_modules</maml:uri>
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>