PowerDataOps

2.0.0.64

src/Organization/Get-XrmEnvironmentVariableValue.ps1

<#
    .SYNOPSIS
    Retrieve environment variable value.

    .DESCRIPTION
    Get the current value of a Dataverse environment variable by its schema name.
    When a value record (override) exists, its value is returned, even when it is empty; otherwise the definition default value is returned.

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

    .PARAMETER Name
    Environment variable definition schema name.

    .PARAMETER IfExists
    Return $null when the definition does not exist, instead of raising an error.

    .OUTPUTS
    String. Current environment variable value or default value if no current value is set.

    .EXAMPLE
    $xrmClient = New-XrmClient -ConnectionString $connectionString;
    $value = Get-XrmEnvironmentVariableValue -XrmClient $xrmClient -Name "df_SynchTrackingFunctionUrl";

    .EXAMPLE
    $value = Get-XrmEnvironmentVariableValue -XrmClient $xrmClient -Name "df_OptionalSetting" -IfExists;

    .LINK
    https://github.com/AymericM78/PowerDataOps/blob/main/documentation/commands/Get-XrmEnvironmentVariableValue.md
#>
function Get-XrmEnvironmentVariableValue {
    [CmdletBinding()]
    [OutputType([String])]
    param
    (
        [Parameter(Mandatory = $false, ValueFromPipeline)]
        [Microsoft.PowerPlatform.Dataverse.Client.ServiceClient]
        $XrmClient = $Global:XrmClient,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name,

        [Parameter(Mandatory = $false)]
        [switch]
        $IfExists
    )
    begin {
        $StopWatch = [System.Diagnostics.Stopwatch]::StartNew();
        Trace-XrmFunction -Name $MyInvocation.MyCommand.Name -Stage Start -Parameters ($MyInvocation.MyCommand.Parameters);
    }
    process {
        $variable = Get-XrmEnvironmentVariablesInternal -XrmClient $XrmClient -Name $Name | Select-Object -First 1;
        if (-not $variable) {
            if ($IfExists) {
                return $null;
            }
            throw "Environment variable definition '$Name' not found.";
        }

        # An override exists when a value record exists: it is returned even when empty
        $variable.EffectiveValue;
    }
    end {
        $StopWatch.Stop();
        Trace-XrmFunction -Name $MyInvocation.MyCommand.Name -Stage Stop -StopWatch $StopWatch;
    }
}

Export-ModuleMember -Function Get-XrmEnvironmentVariableValue -Alias *;