PowerDataOps

2.0.0.49

src/Solutions/Customization/Commands/Set-XrmCommand.ps1

<#
    .SYNOPSIS
    Update a command bar button in Microsoft Dataverse.

    .DESCRIPTION
    Update an existing appaction record (command bar button).

    .PARAMETER XrmClient
    Xrm connector initialized to target instance. Use latest one by default. (Dataverse ServiceClient)

    .PARAMETER CommandReference
    EntityReference of the appaction to update.

    .PARAMETER Name
    Updated command display name.

    .PARAMETER Labels
    Hashtable of language code to display name. Alternative to -Name. The stored 'name' is resolved from -LanguageCode (fallback: lowest language code). -Name takes precedence if both are provided. Note: the button text shown to users is -ButtonLabelText.

    .PARAMETER LanguageCode
    Language code used to pick the stored 'name' from -Labels. Default: 1033.

    .PARAMETER ButtonLabelText
    Updated button label text.

    .PARAMETER TooltipTitle
    Updated tooltip title text.

    .PARAMETER Hidden
    Updated hidden state.

    .PARAMETER SolutionUniqueName
    Unmanaged solution unique name. When provided, the updated command is automatically added to this solution.

    .OUTPUTS
    Microsoft.Xrm.Sdk.EntityReference. Reference to the updated appaction record.

    .EXAMPLE
    Set-XrmCommand -CommandReference $cmdRef -ButtonLabelText "Approve Request";
    Set-XrmCommand -CommandReference $cmdRef -ButtonLabelText "Approve Request" -SolutionUniqueName "MySolution";
#>
function Set-XrmCommand {
    [CmdletBinding()]
    [OutputType([Microsoft.Xrm.Sdk.EntityReference])]
    param
    (
        [Parameter(Mandatory = $false, ValueFromPipeline)]
        [Microsoft.PowerPlatform.Dataverse.Client.ServiceClient]
        $XrmClient = $Global:XrmClient,

        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [Microsoft.Xrm.Sdk.EntityReference]
        $CommandReference,

        [Parameter(Mandatory = $false)]
        [string]
        $Name,

        [Parameter(Mandatory = $false)]
        [Hashtable]
        $Labels,

        [Parameter(Mandatory = $false)]
        [int]
        $LanguageCode = 1033,

        [Parameter(Mandatory = $false)]
        [string]
        $ButtonLabelText,

        [Parameter(Mandatory = $false)]
        [string]
        $TooltipTitle,

        [Parameter(Mandatory = $false)]
        [bool]
        $Hidden,

        [Parameter(Mandatory = $false)]
        [string]
        $SolutionUniqueName
    )
    begin {
        $StopWatch = [System.Diagnostics.Stopwatch]::StartNew();
        Trace-XrmFunction -Name $MyInvocation.MyCommand.Name -Stage Start -Parameters ($MyInvocation.MyCommand.Parameters);
    }
    process {
        $record = New-XrmEntity -LogicalName "appaction" -Id $CommandReference.Id;

        if ($PSBoundParameters.ContainsKey('Name')) {
            $record.Attributes["name"] = $Name;
        }
        elseif ($PSBoundParameters.ContainsKey('Labels')) {
            $record.Attributes["name"] = Get-XrmLabelText -Labels $Labels -LanguageCode $LanguageCode;
        }
        if ($PSBoundParameters.ContainsKey('ButtonLabelText')) {
            $record.Attributes["buttonlabeltext"] = $ButtonLabelText;
        }
        if ($PSBoundParameters.ContainsKey('TooltipTitle')) {
            $record.Attributes["tooltiptitle"] = $TooltipTitle;
        }
        if ($PSBoundParameters.ContainsKey('Hidden')) {
            $record.Attributes["hidden"] = $Hidden;
        }

        Update-XrmRecord -XrmClient $XrmClient -Record $record;

        if ($PSBoundParameters.ContainsKey('SolutionUniqueName')) {
            Add-XrmSolutionComponent -XrmClient $XrmClient -SolutionUniqueName $SolutionUniqueName -ComponentId $CommandReference.Id -ComponentType 300 -DoNotIncludeSubcomponents $false | Out-Null;
        }

        $CommandReference;
    }
    end {
        $StopWatch.Stop();
        Trace-XrmFunction -Name $MyInvocation.MyCommand.Name -Stage Stop -StopWatch $StopWatch;
    }
}

Export-ModuleMember -Function Set-XrmCommand -Alias *;