Edit‑RegistryKeySecurityDescriptor

SYNOPSIS

Edits selected registry key descriptor sections in one bounded scope.

SYNTAX

Edit-RegistryKeySecurityDescriptor [-Path] <Object[]> [-Sections <WindowsSecurityDescriptorSection>]
 [-ScriptBlock] <ScriptBlock> [-ArgumentList <Object[]>] [-RegistryView <WindowsRegistryView>]
 [-RequireUnchanged] [-ThrottleLimit <Int32>] [-PassThru] [-WhatIf]
 [-Confirm] [<CommonParameters>]

DESCRIPTION

Reads one detached security descriptor per canonical registry target, invokes a caller script block with that descriptor and optional arguments, then persists the originally selected sections at most once. Callback output is suppressed; use PassThru for the edited descriptor. A callback error or unloaded-section expansion prevents persistence.

EXAMPLES

EXAMPLE 1

Edit-RegistryKeySecurityDescriptor -Path HKCU:\Software -Sections Access {
    param($descriptor)
    $descriptor | Add-RegistryKeyAccessRule `
        -Account 'CONTOSO\Analysts' `
        -AccessRights ReadKey | Out-Null
}

Reads and writes the Software key DACL once while staging the rule.

PARAMETERS

-ArgumentList

Supplies additional positional arguments after the descriptor.

Type: Object[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

Returns the edited descriptor after persistence without rereading it.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Path

One or more local registry key paths or RegistryKey pipeline objects.

Type: Object[]
Parameter Sets: (All)
Aliases: PSPath

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-RegistryView

Selects the default, 32-bit, or 64-bit registry view explicitly.

Type: WindowsRegistryView
Parameter Sets: (All)
Aliases:
Accepted values: Default, Registry32, Registry64

Required: False
Position: Named
Default value: Default
Accept pipeline input: False
Accept wildcard characters: False

-RequireUnchanged

Rejects the write when the selected sections changed between this scope's read and its persist step. The default is last-writer-wins.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-ScriptBlock

Receives the detached descriptor as its first positional argument. Mutations made through descriptor-aware commands remain in memory until this scope persists them.

Type: ScriptBlock
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Sections

Selects the descriptor sections loaded and eligible for persistence.

Type: WindowsSecurityDescriptorSection
Parameter Sets: (All)
Aliases:
Accepted values: Owner, Group, Access, Audit, All

Required: False
Position: Named
Default value: Access
Accept pipeline input: False
Accept wildcard characters: False

-ThrottleLimit

Accepted for target-array command consistency. Caller script blocks are intentionally dispatched sequentially to preserve runspace affinity; values greater than one do not parallelize this command.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: [Math]::Max(1, [Math]::Min(8, [Environment]::ProcessorCount))
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

Microsoft.Win32.RegistryKey

OUTPUTS

None

WindowsAccessControl.RegistryKeySecurityDescriptor

NOTES

RELATED LINKS