AzureCAF.psm1

function Export-CafResourceType {
    <#
    .SYNOPSIS
        Exports the Cloud Adoption Framework naming rules for one or more resource types to a CSV or
        Markdown file.
    .DESCRIPTION
        Writes the ResourceType/Resource/Slug/TerraformResourceType/Scope/length/casing fields from
        Get-CafResourceType to a CSV or Markdown file (format chosen from -Path's extension), as a
        reference table to share outside PowerShell. Accepts the same objects on the pipeline to export
        a filtered subset; defaults to every resource type if nothing is piped in. TerraformResourceType
        is joined with '; ' in the export when a resource type has more than one real azurerm
        equivalent (e.g. a VM's Linux/Windows variants), since neither CSV nor Markdown cells hold a
        list natively.
    .PARAMETER Path
        Where to write the export. Must end in .csv, .md or .markdown.
    .PARAMETER InputObject
        Resource type definitions to export, as returned by Get-CafResourceType. Defaults to every
        resource type the module knows about (equivalent to piping in `Get-CafResourceType`) if nothing is
        supplied.
    .PARAMETER Force
        Overwrite -Path if it already exists.
    .EXAMPLE
        Export-CafResourceType -Path ./resource-types.md
 
        Writes a Markdown table of every resource type the module knows about.
    .EXAMPLE
        Get-CafResourceType -ResourceType *storage* | Export-CafResourceType -Path ./storage-types.csv
 
        Exports just the storage-related resource types to CSV.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
    #>

    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Path,

        [Parameter(ValueFromPipeline)]
        [object[]]
        $InputObject,

        [switch]
        $Force
    )

    begin {
        $Items = [System.Collections.Generic.List[object]]::new()
    }

    process {
        foreach ($Item in $InputObject) {
            $Items.Add($Item)
        }
    }

    end {
        $Extension = [System.IO.Path]::GetExtension($Path).ToLowerInvariant()

        if ($Extension -notin '.csv', '.md', '.markdown') {
            Write-Error "'$Path' must end in .csv, .md or .markdown."
            return
        }

        if ($Items.Count -eq 0) {
            $Items.AddRange(@(Get-CafResourceType))
        }

        if ((Test-Path -Path $Path) -and -not $Force) {
            Write-Error "'$Path' already exists. Specify -Force to overwrite it."
            return
        }

        if (-not $PSCmdlet.ShouldProcess($Path, "Export $($Items.Count) resource type(s)")) {
            return
        }

        $Properties = 'ResourceType', 'Resource', 'Slug', 'TerraformResourceType', 'Scope', 'MinLength', 'MaxLength', 'Lowercase', 'Dashes'

        # TerraformResourceType is a single string for most resource types, but an array for the
        # handful where more than one real azurerm resource applies (e.g. a VM's Linux/Windows
        # variants) - joined here so both export formats get a readable, delimited cell instead of
        # Export-Csv's literal 'System.Object[]' or Markdown's default space-joined interpolation.
        $ExportItems = $Items | Select-Object -Property $Properties | ForEach-Object {
            $_.TerraformResourceType = $_.TerraformResourceType -join '; '
            $_
        }

        if ($Extension -eq '.csv') {
            $ExportItems | Export-Csv -Path $Path -NoTypeInformation
        }
        else {
            $Lines = [System.Collections.Generic.List[string]]::new()
            $Lines.Add("| $($Properties -join ' | ') |")
            $Lines.Add("| $(($Properties | ForEach-Object { '---' }) -join ' | ') |")

            foreach ($Item in $ExportItems) {
                $Cells = foreach ($Property in $Properties) {
                    "$($Item.$Property)".Replace('|', '\|')
                }
                $Lines.Add("| $($Cells -join ' | ') |")
            }

            Set-Content -Path $Path -Value $Lines
        }

        Get-Item -Path $Path
    }
}
function Get-CafRegion {
    <#
    .SYNOPSIS
        Looks up the abbreviation for one or more Azure regions.
    .DESCRIPTION
        Searches the module's bundled regionDefinition.json and returns the abbreviation
        Get-CafResourceName's -Region resolves to (e.g. 'eastus' -> 'eus'), along with its Azure-paired
        region if it has one. A local, offline lookup against static data - not a replacement for
        Get-AzLocation, which reports live region availability from Azure.
 
        Abbreviations aren't officially published by Microsoft for every region, so coverage may lag
        newly-announced ones. PairedRegion is informational only ($null where a region has moved to
        availability zones instead) - -Region doesn't resolve against it.
    .PARAMETER Region
        The ARM region name (e.g. 'eastus'), display name (e.g. 'East US') or CAF slug (e.g. 'eus') to
        search for. The name/display name match as a substring; the slug matches exactly only, since
        partial matching on it would mostly just be ambiguous. If omitted, every region is returned.
    .EXAMPLE
        Get-CafRegion -Region eastus
 
        Returns the 'eus' abbreviation for East US, along with its paired region, 'westus'.
    .EXAMPLE
        Get-CafRegion -Region 'East US'
 
        Looks up the same region by its display name instead of its ARM name.
    .EXAMPLE
        Get-CafRegion -Region eus
 
        Looks up the same region by its slug instead.
    .EXAMPLE
        Get-CafRegion
 
        Lists every region known to the module.
    .LINK
        https://www.jlaundry.nz/2022/azure_region_abbreviations/
    #>

    [CmdletBinding()]
    param(
        [Parameter(Position = 0)]
        [string]
        $Region
    )

    $AllDefinitions = @(Get-CafRegionDefinition)
    $definitions = $AllDefinitions

    if ($Region) {
        $definitions = @($AllDefinitions | Where-Object Slug -EQ $Region)

        if ($definitions.Count -eq 0) {
            $definitions = Select-CafMatch -InputObject $AllDefinitions -Property Region -Value $Region
        }

        if ($definitions.Count -eq 0) {
            $definitions = Select-CafMatch -InputObject $AllDefinitions -Property DisplayName -Value $Region
        }
    }

    $definitions | Select-Object Region, DisplayName, Slug, PairedRegion
}
function Get-CafResourceName {
    <#
    .SYNOPSIS
        Generates an Azure resource name that follows the Cloud Adoption Framework naming convention,
        returning just the name as a string.
    .DESCRIPTION
        A thin wrapper around New-CafResourceName that returns just the generated Name string, for
        callers who don't need the ResourceType/Resource/Slug/InstanceNumber/RandomSuffix that produced
        it - every parameter here behaves exactly as it does there; see its help for the full
        length-budget/trimming/cleaning/-ConventionPath behaviour. Use New-CafResourceName directly
        instead if you need to trace which input produced which name, e.g. when batch-generating.
    .PARAMETER ResourceType
        The ARM resource type to generate a name for, e.g. 'Microsoft.Compute/virtualMachines'. Matches
        as a substring; use -Resource to disambiguate if needed. Tab-completable, and takes precedence
        over -Alias/-Resource if more than one is specified.
    .PARAMETER Alias
        The CAF abbreviation to generate a name for, e.g. 'vmss' - a shorter alternative to
        -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same
        way -Resource does.
    .PARAMETER Resource
        The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias.
        Required alongside either when an ARM type covers more than one kind of resource, e.g.
        'Microsoft.Web/sites' (Web app vs Function app).
    .PARAMETER TerraformResourceType
        The Terraform azurerm resource type to generate a name for, e.g. 'azurerm_storage_account' - a
        fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one
        current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from
        either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType
        to check coverage.
    .PARAMETER Prefix
        One or more strings to prepend to the resource name, in order. Falls back to -ConventionPath's
        value if not specified.
    .PARAMETER Suffix
        One or more strings to append to the resource name, in order. Falls back to -ConventionPath's
        value if not specified.
    .PARAMETER Region
        An Azure region (ARM name, display name or CAF slug, e.g. 'eastus'/'East US'/'eus') to resolve
        and append after any -Suffix. Falls back to -ConventionPath's value if not specified. Use
        Get-CafRegion to look up supported regions.
    .PARAMETER Separator
        The character(s) used to join the prefix/slug/suffix segments. Ignored for resource types that
        don't permit one. Defaults to '-', or to -ConventionPath's value if it specifies one.
    .PARAMETER Casing
        Re-cases every segment of the generated name - -Prefix/-Suffix, the slug and -Region: 'Lower',
        'Upper' or 'Title'. Defaults to 'None', or to -ConventionPath's value. Overridden by a resource
        type that requires an all-lowercase name.
    .PARAMETER InstanceNumber
        An instance number to append, for differentiating otherwise-identical resources (e.g.
        'vm-sql-test-001'). Zero-padded to -InstanceNumberPadding digits. Also accepts -In.
    .PARAMETER InstanceNumberPadding
        Minimum digits to zero-pad -InstanceNumber to (default 3). Falls back to -ConventionPath's
        value if not specified. Also accepts -Inp.
    .PARAMETER Count
        Generates this many names in one call, with sequential instance numbers starting from
        -InstanceNumber (or 1). Each name gets its own random suffix if -RandomSuffixLength is used.
    .PARAMETER RandomSuffixLength
        Appends this many random lowercase alphanumeric characters, for resource types that need a
        globally-unique name. Falls back to -ConventionPath's value if not specified. Also accepts -Rsl.
    .PARAMETER RandomSuffixSeed
        Seeds -RandomSuffixLength's randomness, so the same seed reproduces the same name every time.
        Also accepts -Rss.
    .PARAMETER ConventionPath
        Path to a JSON file of organizational naming-convention defaults (created with
        New-CafNamingConvention) for -Prefix/-Suffix/-Region/-Separator/-Casing/-InstanceNumberPadding/
        -RandomSuffixLength. Anything also specified explicitly takes precedence over the file.
    .PARAMETER NoClean
        Skip stripping characters that aren't valid for the resource type from -Prefix/-Suffix (the
        generated name will then fail validation if any remain).
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Suffix 01
 
        Generates a virtual machine name such as 'contoso-prod-vm-01'.
    .EXAMPLE
        Get-CafResourceName -ResourceType KeyVault -Prefix contoso
 
        -ResourceType matches as a substring, so this is equivalent to specifying the full
        'Microsoft.KeyVault/vaults' ARM type. If a substring matches more than one resource type,
        narrow it down with a longer -ResourceType value and/or -Resource.
    .EXAMPLE
        Get-CafResourceName -Alias vmss -Prefix contoso
 
        If you already know the Cloud Adoption Framework abbreviation, -Alias (or its -Slug alias) is a
        shorter alternative to -ResourceType.
    .EXAMPLE
        Get-CafResourceName -Resource 'Key vault' -Prefix contoso
 
        -Resource alone works too, since every friendly name is unique - a third alternative to
        -ResourceType/-Alias for when you only remember the resource's plain-English name.
    .EXAMPLE
        Get-CafResourceName -TerraformResourceType azurerm_storage_account -Prefix contoso -RandomSuffixLength 6
 
        Generates a storage account name identified by its Terraform resource type instead of its ARM
        type, alias or friendly name - a fourth alternative to -ResourceType/-Alias/-Resource.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Region eastus
 
        Generates 'contoso-prod-vm-eus' - -Region resolves 'eastus' to its CAF-recommended abbreviation
        the same way -ResourceType resolves to its slug, and inserts it after any -Suffix, so -Suffix
        always comes right after the resource type's slug.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix Contoso, Prod -Casing Upper
 
        Generates 'CONTOSO-PROD-VM' - -Casing re-cases every segment, including the resource type's
        own 'vm' slug, without needing to retype -Prefix/-Suffix in a particular case.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -InstanceNumber 1
 
        Generates 'contoso-prod-vm-001' - -InstanceNumber is zero-padded to 3 digits by default, matching
        the Cloud Adoption Framework's own example names such as 'vm-sql-test-001'.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Count 3
 
        Generates 'contoso-prod-vm-001', 'contoso-prod-vm-002' and 'contoso-prod-vm-003' in one call.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6
 
        Generates a storage account name such as 'contosostabcdef', with 6 random characters appended to
        help ensure the globally-unique name doesn't collide with one that already exists.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 -RandomSuffixSeed 42
 
        Generates the same storage account name every time it's run, since the random suffix is seeded.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Web/sites -Resource 'Function app' -Prefix contoso, prod
 
        Generates a function app name. -Resource is required here because 'Microsoft.Web/sites' is also
        used for web apps, which use a different abbreviation.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Web/sites -Alias func -Prefix contoso, prod
 
        Equivalent to the previous example - -Alias disambiguates 'Microsoft.Web/sites' just like
        -Resource does, if you already know the abbreviation rather than the friendly name.
    .EXAMPLE
        Get-CafResourceType -Slug kv | Get-CafResourceName -Prefix contoso -RandomSuffixLength 4
 
        Pipes the resource type definition for the 'kv' (Key Vault) abbreviation straight into
        Get-CafResourceName.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso -ConventionPath ./contoso.json
 
        Uses -Prefix explicitly, but falls back to whatever -Suffix/-Region/-Separator/etc. are saved in
        contoso.json (see New-CafNamingConvention) for anything not specified here.
    .EXAMPLE
        Import-Csv ./resources.csv | Get-CafResourceName
 
        Batch-generates a name for every row of resources.csv, which needs at least a ResourceType or
        Alias column, and may also have Resource/Prefix/Suffix/Separator/InstanceNumber columns.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
    #>

    [CmdletBinding()]
    param(
        [Parameter(Position = 0, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ResourceType,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Slug')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Alias,

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Resource,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Tf')]
        [ValidateNotNullOrEmpty()]
        [string]
        $TerraformResourceType,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string[]]
        $Prefix,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string[]]
        $Suffix,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Region,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Separator = '-',

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateSet('None', 'Lower', 'Upper', 'Title')]
        [string]
        $Casing = 'None',

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('In')]
        [ValidateRange(0, [int]::MaxValue)]
        [int]
        $InstanceNumber,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Inp')]
        [ValidateRange(1, 10)]
        [int]
        $InstanceNumberPadding = 3,

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateRange(1, 1000)]
        [int]
        $Count = 1,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Rsl')]
        [ValidateRange(0, 24)]
        [int]
        $RandomSuffixLength = 0,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Rss')]
        [int]
        $RandomSuffixSeed,

        [string]
        $ConventionPath,

        [Parameter(ValueFromPipelineByPropertyName)]
        [switch]
        $NoClean
    )

    begin {
        # Every parameter above exists only to be bound and forwarded to New-CafResourceName via the
        # proxy-command plumbing below (for CmdletBinding/tab-completion/help purposes), never read
        # directly here - this satisfies PSScriptAnalyzer's PSReviewUnusedParameter rule.
        $null = $ResourceType, $Alias, $Resource, $TerraformResourceType, $Prefix, $Suffix, $Region, $Separator, $Casing, $InstanceNumber,
        $InstanceNumberPadding, $Count, $RandomSuffixLength, $RandomSuffixSeed, $ConventionPath, $NoClean

        # A hand-rolled `New-CafResourceName @PSBoundParameters` here would be unsafe: $PSBoundParameters
        # keeps stale values from a previous pipeline object once a later object lacks that property (a
        # known PowerShell quirk), which would leak e.g. one row's -Suffix into the next row's call. The
        # proxy-command pattern below instead feeds each pipeline object into New-CafResourceName's own
        # pipeline binding, which rebinds correctly per object.
        $WrappedCommand = $ExecutionContext.InvokeCommand.GetCommand('New-CafResourceName', [System.Management.Automation.CommandTypes]::Function)
        $ScriptCmd = { & $WrappedCommand @PSBoundParameters | ForEach-Object Name }
        $SteppablePipeline = $ScriptCmd.GetSteppablePipeline($MyInvocation.CommandOrigin)
        $SteppablePipeline.Begin($PSCmdlet)
    }

    process {
        $SteppablePipeline.Process($_)
    }

    end {
        $SteppablePipeline.End()
    }
}
function Get-CafResourceType {
    <#
    .SYNOPSIS
        Looks up the Cloud Adoption Framework naming rules for one or more Azure resource types.
    .DESCRIPTION
        Searches the module's bundled resourceDefinition.json and returns a resource type's recommended
        CAF abbreviation, naming scope, length limits and casing rules - the same rules Get-CafResourceName
        builds a name against. A local, offline lookup against static data - not a replacement for
        Get-AzResourceProvider, which reports live resource provider availability from Azure.
    .PARAMETER ResourceType
        The ARM resource type to search for, e.g. 'Microsoft.Compute/virtualMachines'. Matches as a
        substring; pass an explicit wildcard pattern (e.g. 'Microsoft.Compute/*') for tighter control.
        If omitted, all resource types are returned (optionally filtered by -Resource/-Alias).
    .PARAMETER Resource
        The friendly resource name to search for, e.g. 'Virtual machine'. Matches as a substring. Useful
        to disambiguate ARM resource types that cover more than one kind of resource.
    .PARAMETER Alias
        The CAF abbreviation to search for, e.g. 'vm'. Matches as a substring, and also accepts -Slug.
    .PARAMETER TerraformResourceType
        The Terraform azurerm resource type to search for, e.g. 'azurerm_storage_account'. Matches as a
        substring against any value on a resource type's TerraformResourceType property - which is
        usually a single string, but an array for the handful of resource types with more than one
        current real azurerm equivalent (e.g. 'azurerm_linux_virtual_machine' and
        'azurerm_windows_virtual_machine' for a virtual machine); either one resolves it. $null for
        resource types Terraform doesn't model distinctly.
    .EXAMPLE
        Get-CafResourceType -ResourceType Microsoft.Compute/virtualMachines
 
        Returns the naming rule for an Azure virtual machine.
    .EXAMPLE
        Get-CafResourceType -ResourceType storageAccount
 
        Finds resource types whose ARM type contains 'storageAccount'.
    .EXAMPLE
        Get-CafResourceType -Alias vm
 
        Finds the resource type(s) that use the 'vm' abbreviation.
    .EXAMPLE
        Get-CafResourceType -TerraformResourceType azurerm_storage_account
 
        Finds the resource type that corresponds to the 'azurerm_storage_account' Terraform resource.
    .EXAMPLE
        Get-CafResourceType
 
        Lists every resource type known to the module.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
    #>

    [CmdletBinding()]
    param(
        [Parameter(Position = 0)]
        [string]
        $ResourceType,

        [string]
        $Resource,

        [Alias('Slug')]
        [string]
        $Alias,

        [Alias('Tf')]
        [string]
        $TerraformResourceType
    )

    $definitions = @(Get-CafResourceDefinition)

    if ($ResourceType) {
        $definitions = Select-CafMatch -InputObject $definitions -Property ResourceType -Value $ResourceType
    }

    if ($Resource) {
        $definitions = Select-CafMatch -InputObject $definitions -Property Resource -Value $Resource
    }

    if ($Alias) {
        $definitions = Select-CafMatch -InputObject $definitions -Property Slug -Value $Alias
    }

    if ($TerraformResourceType) {
        $definitions = Select-CafMatch -InputObject $definitions -Property TerraformResourceType -Value $TerraformResourceType
    }

    $definitions | Select-Object ResourceType, Resource, Slug, TerraformResourceType, Scope, MinLength, MaxLength, Lowercase, Dashes
}
function New-CafNamingConvention {
    <#
    .SYNOPSIS
        Saves a reusable set of Get-CafResourceName defaults to a JSON file, so your organization's
        naming convention doesn't need to be retyped on every call.
    .DESCRIPTION
        Writes a small JSON file that Get-CafResourceName's -ConventionPath reads defaults from for
        -Prefix, -Suffix, -Region, -Separator, -Casing, -InstanceNumberPadding and -RandomSuffixLength.
        Anything also passed explicitly to Get-CafResourceName still takes precedence over the file.
 
        -RandomSuffixSeed deliberately isn't included: a shared seed would make the "random" suffix
        identical for everyone using the file, defeating the uniqueness -RandomSuffixLength exists for -
        it only makes sense passed directly, per call.
    .PARAMETER Path
        Where to save the convention file, e.g. './contoso.json'.
    .PARAMETER Prefix
        One or more strings to use as the default -Prefix, e.g. a company name or environment.
    .PARAMETER Suffix
        One or more strings to use as the default -Suffix.
    .PARAMETER Region
        An Azure region (ARM name, display name or slug) to use as the default -Region - resolved and
        stored as its ARM name, so an unrecognized value is caught here rather than on every later call.
    .PARAMETER Separator
        The default -Separator. Omit to leave this to Get-CafResourceName's own default ('-').
    .PARAMETER Casing
        The default -Casing ('None', 'Lower', 'Upper' or 'Title'). Omit to leave this to
        Get-CafResourceName's own default ('None').
    .PARAMETER InstanceNumberPadding
        The default -InstanceNumberPadding. Omit to leave this to Get-CafResourceName's own default (3).
        Also accepts -Inp as an alias.
    .PARAMETER RandomSuffixLength
        The default -RandomSuffixLength. Omit to leave this to Get-CafResourceName's own default (0, i.e.
        no random suffix unless a call asks for one explicitly). Also accepts -Rsl as an alias.
    .PARAMETER Force
        Overwrite -Path if it already exists.
    .EXAMPLE
        New-CafNamingConvention -Path ./contoso.json -Prefix contoso, prod -Region eastus -Separator '-' -InstanceNumberPadding 2
 
        Saves a convention so that Get-CafResourceName -ConventionPath ./contoso.json applies that
        prefix, region, separator and padding by default.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -ConventionPath ./contoso.json -InstanceNumber 1
 
        Uses the saved convention, overriding only -InstanceNumber for this particular call.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming#choose-naming-components
    #>

    [CmdletBinding(SupportsShouldProcess)]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]
        $Path,

        [string[]]
        $Prefix,

        [string[]]
        $Suffix,

        [string]
        $Region,

        [string]
        $Separator,

        [ValidateSet('None', 'Lower', 'Upper', 'Title')]
        [string]
        $Casing,

        [Alias('Inp')]
        [ValidateRange(1, 10)]
        [int]
        $InstanceNumberPadding,

        [Alias('Rsl')]
        [ValidateRange(0, 24)]
        [int]
        $RandomSuffixLength,

        [switch]
        $Force
    )

    if ((Test-Path -Path $Path) -and -not $Force) {
        Write-Error "'$Path' already exists. Specify -Force to overwrite it."
        return
    }

    $Convention = [ordered]@{}

    if ($PSBoundParameters.ContainsKey('Prefix')) { $Convention.Prefix = $Prefix }
    if ($PSBoundParameters.ContainsKey('Suffix')) { $Convention.Suffix = $Suffix }

    if ($PSBoundParameters.ContainsKey('Region')) {
        $RegionDefinition = Resolve-CafRegion -Region $Region

        if (-not $RegionDefinition) {
            return
        }

        $Convention.Region = $RegionDefinition.Region
    }

    if ($PSBoundParameters.ContainsKey('Separator')) { $Convention.Separator = $Separator }
    if ($PSBoundParameters.ContainsKey('Casing')) { $Convention.Casing = $Casing }
    if ($PSBoundParameters.ContainsKey('InstanceNumberPadding')) { $Convention.InstanceNumberPadding = $InstanceNumberPadding }
    if ($PSBoundParameters.ContainsKey('RandomSuffixLength')) { $Convention.RandomSuffixLength = $RandomSuffixLength }

    if ($Convention.Count -eq 0) {
        Write-Error 'Specify at least one of -Prefix, -Suffix, -Region, -Separator, -Casing, -InstanceNumberPadding or -RandomSuffixLength.'
        return
    }

    if ($PSCmdlet.ShouldProcess($Path, 'Create naming convention file')) {
        $Convention | ConvertTo-Json | Set-Content -Path $Path
        Get-Item -Path $Path
    }
}
function New-CafResourceName {
    <#
    .SYNOPSIS
        Generates an Azure resource name that follows the Cloud Adoption Framework naming convention,
        returning the full result as an object.
    .DESCRIPTION
        Builds a resource name from an optional prefix, the CAF-recommended abbreviation for the given
        Azure resource type, and an optional suffix - trimmed, cleaned and cased to fit that resource
        type's length limit, allowed characters and casing rules.
 
        Returns an object with Name, ResourceType, Resource, Slug, TerraformResourceType, InstanceNumber
        and RandomSuffix properties - use Get-CafResourceName instead for just the name as a plain
        string. Accepts
        pipeline input by property name, so a list of resource specs (e.g. from a CSV) can be batch-
        generated in one call - see the pipeline example below. Use Get-CafResourceType to discover the
        accepted ResourceType/Resource values, and -Verbose to see the length-budget reasoning behind a
        result.
    .PARAMETER ResourceType
        The ARM resource type to generate a name for, e.g. 'Microsoft.Compute/virtualMachines'. Matches
        as a substring; use -Resource to disambiguate if needed. Tab-completable, and takes precedence
        over -Alias/-Resource if more than one is specified.
    .PARAMETER Alias
        The CAF abbreviation to generate a name for, e.g. 'vmss' - a shorter alternative to
        -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same
        way -Resource does.
    .PARAMETER Resource
        The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias.
        Required alongside either when an ARM type covers more than one kind of resource, e.g.
        'Microsoft.Web/sites' (Web app vs Function app).
    .PARAMETER TerraformResourceType
        The Terraform azurerm resource type to generate a name for, e.g. 'azurerm_storage_account' - a
        fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one
        current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from
        either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType
        to check coverage.
    .PARAMETER Prefix
        One or more strings to prepend to the resource name, in order. Falls back to -ConventionPath's
        value if not specified.
    .PARAMETER Suffix
        One or more strings to append to the resource name, in order. Falls back to -ConventionPath's
        value if not specified.
    .PARAMETER Region
        An Azure region (ARM name, display name or CAF slug, e.g. 'eastus'/'East US'/'eus') to resolve
        and append after any -Suffix. Falls back to -ConventionPath's value if not specified. Use
        Get-CafRegion to look up supported regions.
    .PARAMETER Separator
        The character(s) used to join the prefix/slug/suffix segments. Ignored for resource types that
        don't permit one. Defaults to '-', or to -ConventionPath's value if it specifies one.
    .PARAMETER Casing
        Re-cases every segment of the generated name - -Prefix/-Suffix, the slug and -Region: 'Lower',
        'Upper' or 'Title'. Defaults to 'None', or to -ConventionPath's value. Overridden by a resource
        type that requires an all-lowercase name. Doesn't affect the returned object's Slug property,
        which always reports the canonical CAF abbreviation.
    .PARAMETER InstanceNumber
        An instance number to append, for differentiating otherwise-identical resources (e.g.
        'vm-sql-test-001'). Zero-padded to -InstanceNumberPadding digits. Also accepts -In.
    .PARAMETER InstanceNumberPadding
        Minimum digits to zero-pad -InstanceNumber to (default 3). Falls back to -ConventionPath's
        value if not specified. Also accepts -Inp.
    .PARAMETER Count
        Generates this many names in one call, with sequential instance numbers starting from
        -InstanceNumber (or 1). Each name gets its own random suffix if -RandomSuffixLength is used.
    .PARAMETER RandomSuffixLength
        Appends this many random lowercase alphanumeric characters, for resource types that need a
        globally-unique name. Falls back to -ConventionPath's value if not specified. Also accepts -Rsl.
    .PARAMETER RandomSuffixSeed
        Seeds -RandomSuffixLength's randomness, so the same seed reproduces the same name every time.
        Also accepts -Rss.
    .PARAMETER ConventionPath
        Path to a JSON file of organizational naming-convention defaults (created with
        New-CafNamingConvention) for -Prefix/-Suffix/-Region/-Separator/-Casing/-InstanceNumberPadding/
        -RandomSuffixLength. Anything also specified explicitly takes precedence over the file.
    .PARAMETER NoClean
        Skip stripping characters that aren't valid for the resource type from -Prefix/-Suffix (the
        generated name will then fail validation if any remain).
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Suffix 01
 
        Generates a virtual machine name such as 'contoso-prod-vm-01', returned as an object with Name,
        ResourceType, Resource, Slug, TerraformResourceType, InstanceNumber and RandomSuffix properties.
    .EXAMPLE
        New-CafResourceName -ResourceType KeyVault -Prefix contoso
 
        -ResourceType matches as a substring, so this is equivalent to specifying the full
        'Microsoft.KeyVault/vaults' ARM type. If a substring matches more than one resource type,
        narrow it down with a longer -ResourceType value and/or -Resource.
    .EXAMPLE
        New-CafResourceName -Alias vmss -Prefix contoso
 
        If you already know the Cloud Adoption Framework abbreviation, -Alias (or its -Slug alias) is a
        shorter alternative to -ResourceType.
    .EXAMPLE
        New-CafResourceName -Resource 'Key vault' -Prefix contoso
 
        -Resource alone works too, since every friendly name is unique - a third alternative to
        -ResourceType/-Alias for when you only remember the resource's plain-English name.
    .EXAMPLE
        New-CafResourceName -TerraformResourceType azurerm_storage_account -Prefix contoso -RandomSuffixLength 6
 
        Generates a storage account name identified by its Terraform resource type instead of its ARM
        type, alias or friendly name - a fourth alternative to -ResourceType/-Alias/-Resource.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Region eastus
 
        Generates 'contoso-prod-vm-eus' - -Region resolves 'eastus' to its CAF-recommended abbreviation
        the same way -ResourceType resolves to its slug, and inserts it after any -Suffix, so -Suffix
        always comes right after the resource type's slug.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix Contoso, Prod -Casing Upper
 
        Generates 'CONTOSO-PROD-VM' - -Casing re-cases every segment, including the resource type's
        own 'vm' slug, without needing to retype -Prefix/-Suffix in a particular case. The returned
        Slug property still reports the canonical 'vm', regardless of -Casing.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -InstanceNumber 1
 
        Generates 'contoso-prod-vm-001' - -InstanceNumber is zero-padded to 3 digits by default, matching
        the Cloud Adoption Framework's own example names such as 'vm-sql-test-001'.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Count 3
 
        Generates 'contoso-prod-vm-001', 'contoso-prod-vm-002' and 'contoso-prod-vm-003' in one call.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6
 
        Generates a storage account name such as 'contosostabcdef', with 6 random characters appended to
        help ensure the globally-unique name doesn't collide with one that already exists.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 -RandomSuffixSeed 42
 
        Generates the same storage account name every time it's run, since the random suffix is seeded.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Web/sites -Resource 'Function app' -Prefix contoso, prod
 
        Generates a function app name. -Resource is required here because 'Microsoft.Web/sites' is also
        used for web apps, which use a different abbreviation.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Web/sites -Alias func -Prefix contoso, prod
 
        Equivalent to the previous example - -Alias disambiguates 'Microsoft.Web/sites' just like
        -Resource does, if you already know the abbreviation rather than the friendly name.
    .EXAMPLE
        Get-CafResourceType -Slug kv | New-CafResourceName -Prefix contoso -RandomSuffixLength 4
 
        Pipes the resource type definition for the 'kv' (Key Vault) abbreviation straight into
        New-CafResourceName.
    .EXAMPLE
        New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso -ConventionPath ./contoso.json
 
        Uses -Prefix explicitly, but falls back to whatever -Suffix/-Region/-Separator/etc. are saved in
        contoso.json (see New-CafNamingConvention) for anything not specified here.
    .EXAMPLE
        Import-Csv ./resources.csv | New-CafResourceName | Export-Csv ./generated-names.csv
 
        Batch-generates a name for every row of resources.csv, which needs at least a ResourceType,
        Alias or TerraformResourceType column, and may also have Resource/Prefix/Suffix/Separator/
        InstanceNumber columns. The ResourceType/Resource/Slug/TerraformResourceType/InstanceNumber/
        RandomSuffix that produced each name is kept alongside it, rather than returning bare strings
        that lose track of which input row (or which -Count
        iteration) each one came from.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
    #>

    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure in-memory name generator - the New verb reflects that it returns a new result object (as opposed to Get-CafResourceName''s plain string), not that it changes any external state.')]
    [CmdletBinding()]
    param(
        [Parameter(Position = 0, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ResourceType,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Slug')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Alias,

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Resource,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Tf')]
        [ValidateNotNullOrEmpty()]
        [string]
        $TerraformResourceType,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string[]]
        $Prefix,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string[]]
        $Suffix,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Region,

        [Parameter(ValueFromPipelineByPropertyName)]
        [string]
        $Separator = '-',

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateSet('None', 'Lower', 'Upper', 'Title')]
        [string]
        $Casing = 'None',

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('In')]
        [ValidateRange(0, [int]::MaxValue)]
        [int]
        $InstanceNumber,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Inp')]
        [ValidateRange(1, 10)]
        [int]
        $InstanceNumberPadding = 3,

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateRange(1, 1000)]
        [int]
        $Count = 1,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Rsl')]
        [ValidateRange(0, 24)]
        [int]
        $RandomSuffixLength = 0,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Rss')]
        [int]
        $RandomSuffixSeed,

        [string]
        $ConventionPath,

        [Parameter(ValueFromPipelineByPropertyName)]
        [switch]
        $NoClean
    )

    begin {
        function Get-CleanString {
            param (
                [string[]]$InputObject,
                [string]$Pattern
            )

            foreach ($Str in $InputObject) {
                $Str -replace $Pattern, ''
            }
        }

        function Get-CasedString {
            param (
                [string[]]$InputObject,
                [string]$Casing
            )

            foreach ($Str in $InputObject) {
                switch ($Casing) {
                    'Lower' { $Str.ToLower() }
                    'Upper' { $Str.ToUpper() }
                    # Lowercased first so an all-caps segment (e.g. 'NYC') isn't left alone as a
                    # presumed acronym - .NET's ToTitleCase skips re-casing words that are already
                    # all-uppercase.
                    'Title' { (Get-Culture).TextInfo.ToTitleCase($Str.ToLower()) }
                    default { $Str }
                }
            }
        }

        $Convention = $null
        if ($ConventionPath) {
            if (-not (Test-Path -Path $ConventionPath -PathType Leaf)) {
                $PSCmdlet.ThrowTerminatingError(
                    [System.Management.Automation.ErrorRecord]::new(
                        [System.IO.FileNotFoundException]::new("Naming convention file not found: '$ConventionPath'."),
                        'ConventionFileNotFound',
                        [System.Management.Automation.ErrorCategory]::ObjectNotFound,
                        $ConventionPath
                    )
                )
            }

            try {
                $Convention = Get-Content -Path $ConventionPath -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
                Write-Verbose "Loaded naming convention from '$ConventionPath'."
            }
            catch {
                $PSCmdlet.ThrowTerminatingError($_)
            }
        }
    }

    process {
        if (-not $ResourceType -and -not $Alias -and -not $Resource -and -not $TerraformResourceType) {
            Write-Error 'Specify -ResourceType, -Alias, -Resource or -TerraformResourceType to identify the resource type.'
            return
        }

        $definition = Resolve-CafResourceDefinition -ResourceType $ResourceType -Alias $Alias -Resource $Resource -TerraformResourceType $TerraformResourceType

        if (-not $definition) {
            return
        }

        Write-Verbose "Resolved to $($definition.ResourceType) [$($definition.Resource)] (slug '$($definition.Slug)', max length $($definition.MaxLength), dashes $($definition.Dashes), lowercase $($definition.Lowercase))."

        $EffectivePrefix = if ($PSBoundParameters.ContainsKey('Prefix')) { $Prefix } else { $Convention.Prefix }
        $EffectiveSuffix = if ($PSBoundParameters.ContainsKey('Suffix')) { $Suffix } else { $Convention.Suffix }

        $EffectiveRegion = if ($PSBoundParameters.ContainsKey('Region')) { $Region } else { $Convention.Region }

        if ($EffectiveRegion) {
            $RegionDefinition = Resolve-CafRegion -Region $EffectiveRegion

            if (-not $RegionDefinition) {
                return
            }

            Write-Verbose "Resolved region '$EffectiveRegion' to '$($RegionDefinition.Region)' (slug '$($RegionDefinition.Slug)')."
            $EffectiveRegionSlug = $RegionDefinition.Slug
        }

        $EffectiveSeparator = if ($PSBoundParameters.ContainsKey('Separator')) { $Separator } elseif ($null -ne $Convention.Separator) { $Convention.Separator } else { $Separator }
        $EffectiveCasing = if ($PSBoundParameters.ContainsKey('Casing')) { $Casing } elseif ($Convention.Casing) { $Convention.Casing } else { $Casing }
        $EffectiveInstanceNumberPadding = if ($PSBoundParameters.ContainsKey('InstanceNumberPadding')) { $InstanceNumberPadding } elseif ($Convention.InstanceNumberPadding) { $Convention.InstanceNumberPadding } else { $InstanceNumberPadding }
        $EffectiveRandomSuffixLength = if ($PSBoundParameters.ContainsKey('RandomSuffixLength')) { $RandomSuffixLength } elseif ($null -ne $Convention.RandomSuffixLength) { $Convention.RandomSuffixLength } else { $RandomSuffixLength }

        if ($EffectiveInstanceNumberPadding -lt 1 -or $EffectiveInstanceNumberPadding -gt 10) {
            Write-Error "InstanceNumberPadding from the naming convention must be between 1 and 10, but was $EffectiveInstanceNumberPadding."
            return
        }

        if ($EffectiveRandomSuffixLength -lt 0 -or $EffectiveRandomSuffixLength -gt 24) {
            Write-Error "RandomSuffixLength from the naming convention must be between 0 and 24, but was $EffectiveRandomSuffixLength."
            return
        }

        if ($EffectiveCasing -notin 'None', 'Lower', 'Upper', 'Title') {
            Write-Error "Casing from the naming convention must be one of 'None', 'Lower', 'Upper' or 'Title', but was '$EffectiveCasing'."
            return
        }

        if ($NoClean) {
            $CleanPrefix = $EffectivePrefix
            $CleanSuffix = $EffectiveSuffix
            $CleanRegionSlug = $EffectiveRegionSlug
        }
        else {
            $CleanPrefix = Get-CleanString -InputObject $EffectivePrefix -Pattern $definition.InvalidCharsRegex
            $CleanSuffix = Get-CleanString -InputObject $EffectiveSuffix -Pattern $definition.InvalidCharsRegex
            $CleanRegionSlug = Get-CleanString -InputObject $EffectiveRegionSlug -Pattern $definition.InvalidCharsRegex
        }

        # $CasedSlug is kept separate from $definition.Slug (used as-is for the returned Slug property
        # and in error/verbose messages) so casing only affects the composed Name, not the canonical
        # CAF abbreviation callers can use to cross-reference Get-CafResourceType.
        $CasedSlug = $definition.Slug

        if ($EffectiveCasing -ne 'None') {
            $CleanPrefix = Get-CasedString -InputObject $CleanPrefix -Casing $EffectiveCasing
            $CleanSuffix = Get-CasedString -InputObject $CleanSuffix -Casing $EffectiveCasing
            $CleanRegionSlug = Get-CasedString -InputObject $CleanRegionSlug -Casing $EffectiveCasing
            $CasedSlug = Get-CasedString -InputObject $CasedSlug -Casing $EffectiveCasing
        }

        $ActualSeparator = if ($definition.Dashes) { $EffectiveSeparator } else { '' }

        $HasInstanceNumber = $PSBoundParameters.ContainsKey('InstanceNumber') -or $Count -gt 1
        $StartInstanceNumber = if ($PSBoundParameters.ContainsKey('InstanceNumber')) { $InstanceNumber } else { 1 }
        $EndInstanceNumber = $StartInstanceNumber + $Count - 1

        # Reserve space based on the longest instance number in the sequence, so the trimmed base name
        # (prefix/slug/region/suffix) is the same length for every generated name, not just the first one.
        $InstanceSegment = if ($HasInstanceNumber) { $EndInstanceNumber.ToString().PadLeft($EffectiveInstanceNumberPadding, '0') } else { $null }

        $reservedLength = 0
        $reservedDescriptions = @()

        if ($InstanceSegment) {
            $reservedLength += $InstanceSegment.Length + $ActualSeparator.Length
            $reservedDescriptions += 'the instance number'
        }

        if ($EffectiveRandomSuffixLength -gt 0) {
            $reservedLength += $EffectiveRandomSuffixLength + $ActualSeparator.Length
            $reservedDescriptions += 'the random suffix'
        }

        $mainBudget = $definition.MaxLength - $reservedLength

        if ($reservedDescriptions.Count -gt 0) {
            Write-Verbose "Reserving $reservedLength character(s) for $($reservedDescriptions -join ' and '); $mainBudget of $($definition.MaxLength) remain for the prefix/slug/region/suffix."
        }
        else {
            Write-Verbose "No reserved segments; the full $mainBudget character limit is available for the prefix/slug/region/suffix."
        }

        if ($mainBudget -lt $definition.Slug.Length) {
            Write-Error "Not enough room within the $($definition.MaxLength) character limit for $($definition.ResourceType): '$($definition.Slug)' needs $($definition.Slug.Length) characters, but only $mainBudget are available after reserving space for $($reservedDescriptions -join ' and ')."
            return
        }

        $resourceArr = @($CleanPrefix) + @($CasedSlug) + @($CleanSuffix) + @($CleanRegionSlug) | Where-Object { $_ }

        $resourceName = $resourceArr -join $ActualSeparator
        Write-Verbose "Joined '$($resourceArr -join "', '")' with separator '$ActualSeparator' -> '$resourceName' ($($resourceName.Length) characters)."

        if ($resourceName.Length -gt $mainBudget) {
            $beforeTrimLength = $resourceName.Length
            $resourceName = $resourceName.Substring(0, $mainBudget)
            $reservedNote = if ($reservedDescriptions.Count -gt 0) { " (after reserving space for $($reservedDescriptions -join ' and '))" } else { '' }
            Write-Warning "Resource name has been trimmed to $mainBudget characters due to the $($definition.MaxLength) character max length restriction$reservedNote."
            Write-Verbose "Trimmed from $beforeTrimLength to $mainBudget characters -> '$resourceName'."
        }

        # A single shared Random, created once per pipeline item rather than per generated name, so a
        # -RandomSuffixSeed produces a reproducible sequence of distinct suffixes across the whole -Count batch.
        $Random = if ($EffectiveRandomSuffixLength -gt 0) {
            if ($PSBoundParameters.ContainsKey('RandomSuffixSeed')) { [System.Random]::new($RandomSuffixSeed) } else { [System.Random]::new() }
        }
        else {
            $null
        }
        $CharPool = 'abcdefghijklmnopqrstuvwxyz0123456789'

        for ($InstanceCounter = $StartInstanceNumber; $InstanceCounter -le $EndInstanceNumber; $InstanceCounter++) {
            $FinalName = $resourceName

            if ($HasInstanceNumber) {
                $CurrentInstanceSegment = $InstanceCounter.ToString().PadLeft($EffectiveInstanceNumberPadding, '0')
                $FinalName = $FinalName + $ActualSeparator + $CurrentInstanceSegment
                Write-Verbose "Appended instance segment '$CurrentInstanceSegment' -> '$FinalName'."
            }

            if ($EffectiveRandomSuffixLength -gt 0) {
                # Always lowercase alphanumeric, even for resource types that allow uppercase - the
                # random suffix exists for uniqueness, not communication, and 36^RandomSuffixLength is
                # already far more entropy than a uniqueness suffix needs.
                $RandomSuffix = -join (1..$EffectiveRandomSuffixLength | ForEach-Object { $CharPool[$Random.Next($CharPool.Length)] })
                $FinalName = $FinalName + $ActualSeparator + $RandomSuffix
                Write-Verbose "Appended random suffix '$RandomSuffix' -> '$FinalName'."
            }

            if ($definition.Lowercase -and $FinalName -cmatch '[A-Z]') {
                $FinalName = $FinalName.ToLower()
                Write-Warning 'Resource name has been converted to lower case due to naming requirement.'
                Write-Verbose "Converted to lowercase -> '$FinalName'."
            }

            if ($FinalName -notmatch $definition.ValidationRegex) {
                Write-Error "The generated name '$FinalName' is not valid for $($definition.ResourceType) (pattern: $($definition.ValidationRegex))."
            }
            else {
                Write-Verbose "Final result: '$FinalName'."
                [pscustomobject]@{
                    Name                  = $FinalName
                    ResourceType          = $definition.ResourceType
                    Resource              = $definition.Resource
                    Slug                  = $definition.Slug
                    TerraformResourceType = $definition.TerraformResourceType
                    InstanceNumber        = if ($HasInstanceNumber) { $InstanceCounter } else { $null }
                    RandomSuffix          = if ($EffectiveRandomSuffixLength -gt 0) { $RandomSuffix } else { $null }
                }
            }
        }
    }
}
function Test-CafResourceName {
    <#
    .SYNOPSIS
        Tests whether a name complies with the Cloud Adoption Framework naming rules for an Azure
        resource type.
    .DESCRIPTION
        Checks a resource name against the same rules Get-CafResourceName enforces when building one:
        minimum/maximum length, required casing, whether a dash is allowed, and the overall set of
        valid characters. Returns an object with each rule's pass/fail, a plain-English Reason when
        invalid, and an overall IsValid - or just true/false with -Quiet.
 
        IsValid is the authoritative result; the per-rule fields are a diagnostic breakdown that can't
        always add up to it perfectly (e.g. a character disallowed only as the *first* character is
        flagged by -ValidCharacters wherever it appears, even if IsValid is still true). Treat IsValid
        as the source of truth.
    .PARAMETER Name
        The resource name to test, e.g. 'contoso-prod-vm-001'.
    .PARAMETER ResourceType
        The ARM resource type to test the name against, e.g. 'Microsoft.Compute/virtualMachines'.
        Matches as a substring; takes precedence over -Alias/-Resource if more than one is specified.
    .PARAMETER Alias
        The CAF abbreviation to test the name against, e.g. 'vmss' - a shorter alternative to
        -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same
        way -Resource does.
    .PARAMETER Resource
        The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias.
        Required alongside either when an ARM type covers more than one kind of resource, e.g.
        'Microsoft.Web/sites' (Web app vs Function app).
    .PARAMETER TerraformResourceType
        The Terraform azurerm resource type to test the name against, e.g. 'azurerm_storage_account' -
        a fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one
        current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from
        either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType
        to check coverage.
    .PARAMETER Quiet
        Return only an overall $true/$false instead of the full breakdown object.
    .EXAMPLE
        Test-CafResourceName -Name 'contoso-prod-vm-001' -ResourceType Microsoft.Compute/virtualMachines
 
        Returns an object showing which naming rules the name passes or fails, and an overall IsValid.
    .EXAMPLE
        (Test-CafResourceName -Name 'CONTOSO' -ResourceType Microsoft.Storage/storageAccounts).Reason
 
        Returns 'Name must be all lowercase for this resource type.' - Reason explains an invalid
        result in plain English; it's $null when IsValid is $true.
    .EXAMPLE
        Test-CafResourceName -Name 'Contoso_VM!' -Alias vm -Quiet
 
        Returns $false - the name is uppercase, contains an underscore and an exclamation mark, none of
        which are valid for a virtual machine name.
    .EXAMPLE
        Test-CafResourceName -Name 'contoso-kv' -Resource 'Key vault'
 
        -Resource alone works too, since every friendly name is unique - a third alternative to
        -ResourceType/-Alias for when you only remember the resource's plain-English name.
    .EXAMPLE
        Test-CafResourceName -Name 'contoso-st' -TerraformResourceType azurerm_storage_account
 
        Tests a name identified by its Terraform resource type instead of its ARM type, alias or
        friendly name - a fourth alternative to -ResourceType/-Alias/-Resource.
    .EXAMPLE
        Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 |
            Test-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Quiet
 
        Round-trips a name generated by Get-CafResourceName back through Test-CafResourceName.
    .LINK
        https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Name,

        [Parameter(Position = 1, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $ResourceType,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Slug')]
        [ValidateNotNullOrEmpty()]
        [string]
        $Alias,

        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string]
        $Resource,

        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('Tf')]
        [ValidateNotNullOrEmpty()]
        [string]
        $TerraformResourceType,

        [switch]
        $Quiet
    )

    process {
        if (-not $ResourceType -and -not $Alias -and -not $Resource -and -not $TerraformResourceType) {
            Write-Error 'Specify -ResourceType, -Alias, -Resource or -TerraformResourceType to identify the resource type.'
            return
        }

        $definition = Resolve-CafResourceDefinition -ResourceType $ResourceType -Alias $Alias -Resource $Resource -TerraformResourceType $TerraformResourceType

        if (-not $definition) {
            return
        }

        $MinLength = $Name.Length -ge $definition.MinLength
        $MaxLength = $Name.Length -le $definition.MaxLength
        $Casing = -not ($definition.Lowercase -and $Name -cmatch '[A-Z]')
        $Dashes = $definition.Dashes -or $Name -cnotmatch '-'
        $ValidCharacters = $Name -cnotmatch $definition.InvalidCharsRegex
        $IsValid = $Name -cmatch $definition.ValidationRegex

        if ($Quiet) {
            return $IsValid
        }

        $Reasons = [System.Collections.Generic.List[string]]::new()

        if ($IsValid) {
            # Even if every breakdown field is individually true, IsValid is the authoritative check -
            # there's nothing to explain when it passed, regardless of what the breakdown says.
        }
        else {
            if (-not $MinLength) {
                $Reasons.Add("Name is $($Name.Length) character$(if ($Name.Length -ne 1) { 's' }), which is shorter than the $($definition.MinLength) character minimum.")
            }

            if (-not $MaxLength) {
                $Reasons.Add("Name is $($Name.Length) characters, which exceeds the $($definition.MaxLength) character maximum by $($Name.Length - $definition.MaxLength).")
            }

            if (-not $Casing) {
                $Reasons.Add('Name must be all lowercase for this resource type.')
            }

            if (-not $Dashes) {
                $Reasons.Add("Name contains a dash ('-'), which this resource type does not allow.")
            }

            if (-not $ValidCharacters) {
                $Reasons.Add('Name contains characters that are not allowed for this resource type.')
            }

            if ($Reasons.Count -eq 0) {
                # None of the simple per-rule checks explain it - some resource types have additional
                # positional rules (e.g. must start/end with a letter) that aren't broken out above.
                $Reasons.Add("Name does not match the required pattern for this resource type (pattern: $($definition.ValidationRegex)).")
            }
        }

        [pscustomobject]@{
            Name                  = $Name
            ResourceType          = $definition.ResourceType
            Resource              = $definition.Resource
            TerraformResourceType = $definition.TerraformResourceType
            IsValid               = $IsValid
            Reason                = if ($Reasons.Count -gt 0) { $Reasons -join ' ' } else { $null }
            MinLength             = $MinLength
            MaxLength             = $MaxLength
            Casing                = $Casing
            Dashes                = $Dashes
            ValidCharacters       = $ValidCharacters
        }
    }
}
# The JSON data files live alongside this one (Private/) so $PSScriptRoot finds them correctly in both
# layouts this file runs in: dot-sourced here in dev mode ($PSScriptRoot = this Private folder), and
# inlined into the combined/staged .psm1 (see Build/Tasks/CombineFunctionsAndStage.ps1), where the
# build copies these same two files to the staged module's root - $PSScriptRoot there resolves to that
# root too, since the combined file *is* the module's root script at that point.
$Script:ResourceDefinitionPath = Join-Path $PSScriptRoot 'resourceDefinition.json'
$Script:RegionDefinitionPath = Join-Path $PSScriptRoot 'regionDefinition.json'

# Registered here (rather than via the [ArgumentCompleter(...)] attribute on each parameter) because an
# attribute scriptblock isn't bound to this module's session state, so it can't see private functions
# like Get-CafResourceDefinition - it would silently fail and PowerShell would fall back to file
# completion. A scriptblock defined directly in a module file (dot-sourced here, inlined in the
# combined/staged build) doesn't have that problem.
$ResourceTypeCompleter = {
    param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters)
    $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters
    # Substring match, same as the cmdlets' own -ResourceType/-Alias partial matching, so what
    # tab-completes is consistent with what actually resolves.
    $Pattern = Get-CafWildcardPattern -Value $WordToComplete
    (Get-CafResourceDefinition).ResourceType |
        Select-Object -Unique |
        Where-Object { $_ -like $Pattern } |
        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
}

$SlugCompleter = {
    param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters)
    $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters
    $Pattern = Get-CafWildcardPattern -Value $WordToComplete
    (Get-CafResourceDefinition).Slug |
        Select-Object -Unique |
        Where-Object { $_ -like $Pattern } |
        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
}

$TerraformResourceTypeCompleter = {
    param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters)
    $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters
    # Substring match, same as the cmdlets' own -TerraformResourceType partial matching. Many entries
    # have no Terraform equivalent ($null), so those are filtered out before completing. Piping an
    # array-valued property (the handful of entries with more than one real azurerm equivalent, e.g.
    # a VM's Linux/Windows variants) flattens it automatically, so each name is still offered on its
    # own rather than as one combined completion.
    $Pattern = Get-CafWildcardPattern -Value $WordToComplete
    (Get-CafResourceDefinition).TerraformResourceType |
        Where-Object { $_ } |
        Select-Object -Unique |
        Where-Object { $_ -like $Pattern } |
        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
}

$ResourceCompleter = {
    param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters)
    $null = $CommandName, $ParameterName, $CommandAst

    $Definitions = @(Get-CafResourceDefinition)

    # Narrow to whichever resource type the caller has already typed, if any, so -Resource only
    # offers the friendly names that actually apply to it (e.g. just 'Web app'/'Function app' once
    # -ResourceType Microsoft.Web/sites is on the line), rather than every friendly name there is.
    # $FakeBoundParameters is always keyed by the canonical parameter name, even if the caller typed
    # the -Slug alias instead of -Alias, so there's no separate case to handle for that.
    if ($FakeBoundParameters.ResourceType) {
        $Definitions = Select-CafMatch -InputObject $Definitions -Property ResourceType -Value $FakeBoundParameters.ResourceType
    }
    elseif ($FakeBoundParameters.Alias) {
        $Definitions = Select-CafMatch -InputObject $Definitions -Property Slug -Value $FakeBoundParameters.Alias
    }
    elseif ($FakeBoundParameters.TerraformResourceType) {
        $Definitions = Select-CafMatch -InputObject $Definitions -Property TerraformResourceType -Value $FakeBoundParameters.TerraformResourceType
    }

    $Pattern = Get-CafWildcardPattern -Value $WordToComplete
    $Definitions.Resource |
        Select-Object -Unique |
        Where-Object { $_ -like $Pattern } |
        Sort-Object |
        ForEach-Object {
            # Friendly names routinely contain spaces/parentheses (e.g. 'Managed disk (OS)'), so the
            # completion text needs quoting to stay a single valid token once it's inserted.
            $Quoted = "'" + $_.Replace("'", "''") + "'"
            [System.Management.Automation.CompletionResult]::new($Quoted, $_, 'ParameterValue', $_)
        }
}

$RegionCompleter = {
    param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters)
    $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters
    # Matches against the ARM region name, its display name or its slug, same fields Resolve-CafRegion
    # accepts, so typing 'east', 'East US' or 'eus' all offer a completion - but always completes to the
    # ARM name, since that's the unambiguous value every other Azure PowerShell -Location parameter
    # expects.
    $Pattern = Get-CafWildcardPattern -Value $WordToComplete
    (Get-CafRegionDefinition) |
        Where-Object { $_.Region -like $Pattern -or $_.DisplayName -like $Pattern -or $_.Slug -like $Pattern } |
        Sort-Object -Property Region -Unique |
        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_.Region, "$($_.Region) ($($_.DisplayName))", 'ParameterValue', $_.DisplayName) }
}

Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'ResourceType' -ScriptBlock $ResourceTypeCompleter
Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'Alias' -ScriptBlock $SlugCompleter
Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'Resource' -ScriptBlock $ResourceCompleter
Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'TerraformResourceType' -ScriptBlock $TerraformResourceTypeCompleter
Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Get-CafRegion' -ParameterName 'Region' -ScriptBlock $RegionCompleter
function Get-CafRegionDefinition {
    <#
    .SYNOPSIS
        Returns the cached set of Azure region abbreviation definitions.
    .DESCRIPTION
        Loads regionDefinition.json from the module root the first time it's needed and caches it for
        the lifetime of the module session, so repeated calls to Get-CafResourceName/Get-CafRegion don't
        re-read and re-parse the file from disk every time.
    .EXAMPLE
        Get-CafRegionDefinition
    #>

    [CmdletBinding()]
    param()

    if (-not $Script:CafRegionDefinitions) {
        $Script:CafRegionDefinitions = Get-Content -Path $Script:RegionDefinitionPath -Raw | ConvertFrom-Json
    }

    $Script:CafRegionDefinitions
}
function Get-CafResourceDefinition {
    <#
    .SYNOPSIS
        Returns the cached set of CAF resource naming definitions.
    .DESCRIPTION
        Loads resourceDefinition.json from the module root the first time it's needed and caches it for
        the lifetime of the module session, so repeated calls to Get-CafResourceName/Get-CafResourceType don't
        re-read and re-parse the file from disk every time.
    .EXAMPLE
        Get-CafResourceDefinition
    #>

    [CmdletBinding()]
    param()

    if (-not $Script:CafResourceDefinitions) {
        $Script:CafResourceDefinitions = Get-Content -Path $Script:ResourceDefinitionPath -Raw | ConvertFrom-Json
    }

    $Script:CafResourceDefinitions
}
function Get-CafWildcardPattern {
    <#
    .SYNOPSIS
        Turns a plain string into a partial ('contains') wildcard pattern.
    .DESCRIPTION
        Used by Get-CafResourceName/Get-CafResourceType so that -ResourceType and -Resource match as a
        substring by default (e.g. 'virtualMachines' matches 'Microsoft.Compute/virtualMachines'),
        while still respecting an explicit wildcard pattern (e.g. '*storageAccount*' or 'disk?') if the
        caller already supplied one, rather than wrapping it a second time.
    .EXAMPLE
        Get-CafWildcardPattern -Value 'virtualMachines'
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [AllowEmptyString()]
        [string]
        $Value
    )

    if ($Value -match '[*?\[\]]') {
        $Value
    }
    else {
        "*$Value*"
    }
}
function Resolve-CafRegion {
    <#
    .SYNOPSIS
        Resolves a -Region value to exactly one regionDefinition.json entry.
    .DESCRIPTION
        Shared resolution logic for Get-CafResourceName and Get-CafRegion, so both cmdlets identify a
        region the same way and report identical errors for an unknown/ambiguous value.
 
        Checks for an exact (case-insensitive) match against the ARM region name (e.g. 'eastus'), its
        display name (e.g. 'East US') or its CAF slug (e.g. 'eus') first - checking all three up front,
        rather than one at a time, matters for a short value like a slug: 'ae' (Australia East's slug)
        is also a substring of several other regions' ARM names (e.g. 'canadaeast', 'israelcentral'), so
        falling through to a substring search would make it ambiguous instead of resolving it.
 
        Only once no exact match exists does it fall back to a substring ('contains') search, same as
        -ResourceType/-Resource elsewhere in the module - against the ARM region name first, then the
        display name. The slug isn't included in that substring fallback: it's short enough that partial
        matching on it would mostly just produce ambiguous results, and a caller who doesn't already know
        the exact slug should be matching on the region name/display name instead.
 
        Writes a non-terminating error and returns nothing if the value doesn't resolve to exactly one
        entry - callers should check for a $null/empty result and return without continuing.
    .EXAMPLE
        Resolve-CafRegion -Region 'eastus'
    .EXAMPLE
        Resolve-CafRegion -Region 'East US'
    .EXAMPLE
        Resolve-CafRegion -Region 'eus'
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]
        $Region
    )

    $definitions = @(Get-CafRegionDefinition)

    $candidates = @($definitions | Where-Object { $_.Region -eq $Region -or $_.DisplayName -eq $Region -or $_.Slug -eq $Region })

    if ($candidates.Count -eq 0) {
        $candidates = Select-CafMatch -InputObject $definitions -Property Region -Value $Region

        if ($candidates.Count -eq 0) {
            $candidates = Select-CafMatch -InputObject $definitions -Property DisplayName -Value $Region
        }
    }

    if ($candidates.Count -eq 0) {
        Write-Error "No Azure region matches '$Region'. Use Get-CafRegion to search for a supported region."
        return
    }

    if ($candidates.Count -gt 1) {
        $options = ($candidates | ForEach-Object { "$($_.Region) [$($_.DisplayName)]" }) -join "', '"
        Write-Error "'$Region' matches more than one Azure region. Narrow it down with the ARM region name: '$options'."
        return
    }

    $candidates[0]
}
function Resolve-CafResourceDefinition {
    <#
    .SYNOPSIS
        Resolves a -ResourceType, -Alias or -Resource value to exactly one resourceDefinition.json
        entry.
    .DESCRIPTION
        Shared resolution logic for Get-CafResourceName and Test-CafResourceName, so all three cmdlets
        identify a resource type the same way and report identical errors for an unknown/ambiguous
        value. Writes a non-terminating error and returns nothing if the value doesn't resolve to
        exactly one entry - callers should check for a $null/empty result and return without
        continuing.
 
        -ResourceType takes priority as the primary identifier if given, then -Alias, then
        -TerraformResourceType, with -Resource and (when -ResourceType/-Alias is primary)
        -TerraformResourceType all narrowing *within* whichever of those matched (for the handful of
        types used by more than one kind of resource). When none of -ResourceType/-Alias/
        -TerraformResourceType is given, -Resource is used as the primary identifier instead - every
        "Resource" friendly name in resourceDefinition.json happens to be globally unique today, so this
        only fails if that ever stops being true upstream.
 
        Callers don't need to guard against more than one of -ResourceType/-Alias/-Resource being
        supplied - e.g. piping Get-CafResourceType's output through by property name binds ResourceType,
        Resource and (via its Slug alias) Alias all at once, since they're all present on that object
        and all describe the same entry: narrowing by -Alias/-Resource after an already-unambiguous
        -ResourceType match is a no-op in that case, since the pipelined values already agree with it.
        Precedence just needs to be deterministic for that case, not an error - it's not a conflict
        unless the caller explicitly typed contradictory values, in which case -Alias/-Resource narrowing
        a -ResourceType match down to zero candidates reports that clearly rather than silently ignoring
        it.
    .EXAMPLE
        Resolve-CafResourceDefinition -ResourceType 'Microsoft.Compute/virtualMachines'
    .EXAMPLE
        Resolve-CafResourceDefinition -Alias 'afd' -Resource 'classic'
    .EXAMPLE
        Resolve-CafResourceDefinition -ResourceType 'Microsoft.Web/sites' -Alias 'func'
    .EXAMPLE
        Resolve-CafResourceDefinition -Resource 'Key vault'
    .EXAMPLE
        Resolve-CafResourceDefinition -TerraformResourceType 'azurerm_storage_account'
    #>

    [CmdletBinding()]
    param(
        [string]
        $ResourceType,

        [string]
        $Alias,

        [string]
        $Resource,

        [string]
        $TerraformResourceType
    )

    $ResourceIsPrimary = -not $ResourceType -and -not $Alias -and -not $TerraformResourceType

    if ($ResourceType) {
        $identifier = "'$ResourceType'"
        $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property ResourceType -Value $ResourceType
    }
    elseif ($Alias) {
        $identifier = "alias '$Alias'"
        $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property Slug -Value $Alias
    }
    elseif ($TerraformResourceType) {
        $identifier = "terraform resource type '$TerraformResourceType'"
        $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property TerraformResourceType -Value $TerraformResourceType
    }
    else {
        $identifier = "resource '$Resource'"
        $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property Resource -Value $Resource
    }

    if ($candidates.Count -eq 0) {
        Write-Error "No resource type matches $identifier. Use Get-CafResourceType to search for a supported resource type."
        return
    }

    if ($Alias -and $ResourceType) {
        $allCandidates = $candidates
        $candidates = Select-CafMatch -InputObject $candidates -Property Slug -Value $Alias

        if ($candidates.Count -eq 0) {
            $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '"
            Write-Error "'$Alias' doesn't match any resource for $identifier. Available: '$options'."
            return
        }
    }

    if ($TerraformResourceType -and ($ResourceType -or $Alias)) {
        $allCandidates = $candidates
        $candidates = Select-CafMatch -InputObject $candidates -Property TerraformResourceType -Value $TerraformResourceType

        if ($candidates.Count -eq 0) {
            $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '"
            Write-Error "'$TerraformResourceType' doesn't match any resource for $identifier. Available: '$options'."
            return
        }
    }

    if ($Resource -and -not $ResourceIsPrimary) {
        $allCandidates = $candidates
        $candidates = Select-CafMatch -InputObject $candidates -Property Resource -Value $Resource

        if ($candidates.Count -eq 0) {
            $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '"
            Write-Error "'$Resource' doesn't match any resource for $identifier. Available: '$options'."
            return
        }
    }

    if ($candidates.Count -gt 1) {
        $options = ($candidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '"
        $suggestion = if ($ResourceIsPrimary) { '-ResourceType' } else { '-Resource' }
        Write-Error "$identifier matches more than one resource type. Narrow it down with $suggestion`: '$options'."
        return
    }

    $candidates[0]
}
function Select-CafMatch {
    <#
    .SYNOPSIS
        Filters a collection to the items whose property exactly matches a value, falling back to a
        partial ('contains') match only when nothing matches exactly.
    .DESCRIPTION
        Used by Get-CafResourceName/Get-CafResourceType to make -ResourceType/-Resource match as a substring
        for convenience, without that breaking exact lookups: partial matching alone is ambiguous for
        values like 'Microsoft.Compute/virtualMachines', since (case-insensitively) it's also a
        substring of 'Microsoft.Compute/virtualMachineScaleSets'. Checking for an exact match first means
        a fully-qualified value always resolves to itself, and the substring fallback only kicks in when
        there was no exact match to begin with.
    .EXAMPLE
        Select-CafMatch -InputObject $definitions -Property ResourceType -Value 'Microsoft.Compute/virtualMachines'
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [object[]]
        $InputObject,

        [Parameter(Mandatory)]
        [string]
        $Property,

        [Parameter(Mandatory)]
        [string]
        $Value
    )

    $exact = @($InputObject | Where-Object { $_.$Property -eq $Value })
    if ($exact.Count -gt 0) {
        return $exact
    }

    $pattern = Get-CafWildcardPattern -Value $Value
    @($InputObject | Where-Object { $_.$Property -like $pattern })
}