Az.Tools.Migration

1.0.0

Functions/Public/New-AzUpgradeModulePlan.ps1

                                function New-AzUpgradeModulePlan

{

    <#

    .SYNOPSIS

        Generates a new upgrade plan for migrating to the Az PowerShell module.

    .DESCRIPTION

        Generates a new upgrade plan for migrating to the Az PowerShell module. The upgrade plan details the specific file/offset points that require changes when moving from AzureRM commands to Az commands.

    .PARAMETER FromAzureRmVersion

        Specifies the AzureRM module version used in your existing PowerShell scripts(s) or modules.

    .PARAMETER ToAzVersion

        Specifies the Az module version to upgrade to. Currently, only Az version 5.2.0 is supported.

    .PARAMETER FilePath

        Specifies the path to a single PowerShell file.

    .PARAMETER DirectoryPath

        Specifies the path to a folder where PowerShell scripts or modules reside.

    .PARAMETER AzureRmCmdReference

        Specifies the AzureRM command references output from the Find-AzUpgradeCommandReference cmdlet.

    .PARAMETER AzureRmModuleSpec

        Specifies an optional parameter to provide a pre-loaded AzureRM module spec, returned from Get-AzUpgradeCmdletSpec.

    .PARAMETER AzModuleSpec

        Specifies an optional parameter to provide a pre-loaded Az module spec, returned from Get-AzUpgradeCmdletSpec.

    .PARAMETER AzAliasMappingSpec

        Specifies an optional parameter to provide a pre-loaded Az cmdlet alias mapping table, returned from Get-AzUpgradeAliasSpec.

    .EXAMPLE

        The following example generates a new Az module upgrade plan for the script file 'C:\Scripts\my-azure-script.ps1'.

        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 5.2.0 -FilePath 'C:\Scripts\my-azure-script.ps1'

    .EXAMPLE

        The following example generates a new Az module upgrade plan for the script and module files located under C:\Scripts.

        New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion 5.2.0 -DirectoryPath 'C:\Scripts'

    .EXAMPLE

        The following example generates a new Az module upgrade plan for the script and module files under C:\Scripts.

        $references = Find-AzUpgradeCommandReference -DirectoryPath 'C:\Scripts' -AzureRmVersion '6.13.1'

        New-AzUpgradeModulePlan -ToAzVersion 5.2.0 -AzureRmCmdReference $references

    .EXAMPLE

        The following example generates a new Az module upgrade plan for the script and module files under several directories.

        Module specs are pre-loaded here to avoid re-loading the spec each time a plan is generated.

        # pre-load specifications

        $armSpec = Get-AzUpgradeCmdletSpec -ModuleName "AzureRM" -ModuleVersion "6.13.1"

        $azSpec = Get-AzUpgradeCmdletSpec -ModuleName "Az" -ModuleVersion "5.2.0"

        $azAliases = Get-AzUpgradeAliasSpec -ModuleVersion "5.2.0"

        # execute a batch of module upgrades

        $plan1 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts1' -FromAzureRmVersion '6.13.1' -ToAzVersion '5.2.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases

        $plan2 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts2' -FromAzureRmVersion '6.13.1' -ToAzVersion '5.2.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases

        $plan3 = New-AzUpgradeModulePlan -DirectoryPath 'C:\Scripts3' -FromAzureRmVersion '6.13.1' -ToAzVersion '5.2.0' -AzureRmModuleSpec $armSpec -AzModuleSpec $azSpec -AzAliasMappingSpec $azAliases

    #>

    [CmdletBinding()]

    Param

    (

        [Parameter(

            Mandatory=$true,

            ParameterSetName="FromReferences",

            HelpMessage='Specify the AzureRM command references collection output from the Find-AzUpgradeCommandReference cmdlet.')]

        [CommandReference[]]

        $AzureRmCmdReference,

        [Parameter(

            Mandatory=$true,

            ParameterSetName="FromNewSearchByFile",

            HelpMessage='Specify the Az module version to upgrade to.')]

        [Parameter(

            Mandatory=$true,

            ParameterSetName="FromNewSearchByDirectory",

            HelpMessage='Specify the Az module version to upgrade to.')]

        [System.String]

        [ValidateSet('6.13.1')]

        $FromAzureRmVersion,

        [Parameter(

            Mandatory=$true,

            ParameterSetName="FromNewSearchByFile",

            HelpMessage="Specify the path to a single PowerShell file.")]

        [System.String]

        [ValidateNotNullOrEmpty()]

        $FilePath,

        [Parameter(

            Mandatory=$true,

            ParameterSetName="FromNewSearchByDirectory",

            HelpMessage="Specify the path to the folder where PowerShell scripts or modules reside.")]

        [System.String]

        [ValidateNotNullOrEmpty()]

        $DirectoryPath,

        [Parameter(

            Mandatory=$true,

            HelpMessage='Specify the Az module version to upgrade to.')]

        [System.String]

        [ValidateSet('5.2.0')]

        $ToAzVersion,

        [Parameter(Mandatory=$false)]

        [System.Collections.Generic.Dictionary[System.String, CommandDefinition]]

        $AzureRmModuleSpec,

        [Parameter(Mandatory=$false)]

        [System.Collections.Generic.Dictionary[System.String, CommandDefinition]]

        $AzModuleSpec,

        [Parameter(Mandatory=$false)]

        [System.Collections.Generic.Dictionary[System.String, System.String]]

        $AzAliasMappingSpec

    )

    Process

    {

        $cmdStarted = Get-Date

        # if an existing set of command references was not provided

        # then call the Find cmdlet to search for those references.

        if ($PSCmdlet.ParameterSetName -eq 'FromNewSearchByFile')

        {

            if ($PSBoundParameters.ContainsKey('AzureRmModuleSpec'))

            {

                Write-Verbose -Message "Searching for commands to upgrade, by file, with pre-loaded module spec."

                $AzureRmCmdReference = Find-AzUpgradeCommandReference -FilePath $FilePath -AzureRmModuleSpec $AzureRmModuleSpec

            }

            else

            {

                Write-Verbose -Message "Searching for commands to upgrade, by file."

                $AzureRmCmdReference = Find-AzUpgradeCommandReference -FilePath $FilePath -AzureRmVersion $FromAzureRmVersion

            }

        }

        elseif ($PSCmdlet.ParameterSetName -eq 'FromNewSearchByDirectory')

        {

            if ($PSBoundParameters.ContainsKey('AzureRmModuleSpec'))

            {

                Write-Verbose -Message "Searching for commands to upgrade, by directory, with pre-loaded module spec."

                $AzureRmCmdReference = Find-AzUpgradeCommandReference -DirectoryPath $DirectoryPath -AzureRmModuleSpec $AzureRmModuleSpec

            }

            else

            {

                Write-Verbose -Message "Searching for commands to upgrade, by directory."

                $AzureRmCmdReference = Find-AzUpgradeCommandReference -DirectoryPath $DirectoryPath -AzureRmVersion $FromAzureRmVersion

            }

        }

        # we can't generate an upgrade plan without some cmdlet references, so quit early here if required.

        if ($AzureRmCmdReference -eq $null -or $AzureRmCmdReference.Count -eq 0)

        {

            Write-Verbose -Message "No AzureRm command references were found. No upgrade plan will be generated."

            return

        }

        else

        {

            Write-Verbose -Message "$($AzureRmCmdReference.Count) AzureRm command reference(s) were found. Upgrade plan will be generated."

        }

        if ($PSBoundParameters.ContainsKey('AzModuleSpec') -eq $false)

        {

            Write-Verbose -Message "Importing cmdlet spec for Az $ToAzVersion"

            $AzModuleSpec = Get-AzUpgradeCmdletSpec -ModuleName "Az" -ModuleVersion $ToAzVersion

        }

        else

        {

            Write-Verbose -Message "Az module spec was provided at runtime, skipping module spec import."

        }

        if ($PSBoundParameters.ContainsKey('AzAliasMappingSpec') -eq $false)

        {

            Write-Verbose -Message "Importing alias mapping spec for Az $ToAzVersion"

            $AzAliasMappingSpec = Get-AzUpgradeAliasSpec -ModuleVersion $ToAzVersion

        }

        else

        {

            Write-Verbose -Message "Az alias mapping spec was provided at runtime, skipping alias spec import."

        }

        $defaultParamNames = @("Debug", "ErrorAction", "ErrorVariable", "InformationAction", "InformationVariable", "OutVariable", "OutBuffer", "PipelineVariable", "Verbose", "WarningAction", "WarningVariable", "WhatIf", "Confirm")

        # synchronous results output instead of async. the reason for this is that

        # we need to sort the object results before returning them to the caller.

        $planSteps = New-Object -TypeName 'System.Collections.Generic.List[UpgradePlan]'

        $planWarningSteps = New-Object -TypeName 'System.Collections.Generic.List[UpgradePlan]'

        $planErrorSteps = New-Object -TypeName 'System.Collections.Generic.List[UpgradePlan]'

        foreach ($rmCmdlet in $AzureRmCmdReference)

        {

            Write-Verbose -Message "Checking upgrade potential for instance of $($rmCmdlet.CommandName)"

            if ($AzAliasMappingSpec.ContainsKey($rmCmdlet.CommandName) -eq $false)

            {

                $errorResult = New-Object -TypeName UpgradePlan

                $errorResult.UpgradeType = [UpgradeStepType]::Cmdlet

                $errorResult.SourceCommand = $rmCmdlet

                $errorResult.FullPath = $rmCmdlet.FullPath

                $errorResult.StartOffset = $rmCmdlet.StartOffset

                $errorResult.Location = $rmCmdlet.Location

                $errorResult.Original = $rmCmdlet.CommandName

                $errorResult.PlanResultReason = "No matching upgrade alias found. Command cannot be automatically upgraded."

                $errorResult.PlanResult = [PlanResultReasonCode]::ErrorNoUpgradeAlias

                $errorResult.PlanSeverity = [DiagnosticSeverity]::Error

                $planErrorSteps.Add($errorResult)

                continue

            }

            $resolvedCommandName = $AzAliasMappingSpec[$rmCmdlet.CommandName]

            if ($AzModuleSpec.ContainsKey($resolvedCommandName) -eq $false)

            {

                $errorResult = New-Object -TypeName UpgradePlan

                $errorResult.UpgradeType = [UpgradeStepType]::Cmdlet

                $errorResult.SourceCommand = $rmCmdlet

                $errorResult.FullPath = $rmCmdlet.FullPath

                $errorResult.StartOffset = $rmCmdlet.StartOffset

                $errorResult.Location = $rmCmdlet.Location

                $errorResult.Original = $rmCmdlet.CommandName

                $errorResult.PlanResultReason = "No Az cmdlet spec found for $resolvedCommandName. Command cannot be automatically upgraded."

                $errorResult.PlanResult = [PlanResultReasonCode]::ErrorNoModuleSpecMatch

                $errorResult.PlanSeverity = [DiagnosticSeverity]::Error

                $planErrorSteps.Add($errorResult)

                continue

            }

            $cmdletUpgrade = New-Object -TypeName UpgradePlan

            $cmdletUpgrade.Original = $rmCmdlet.CommandName

            $cmdletUpgrade.Replacement = $resolvedCommandName

            $cmdletUpgrade.UpgradeType = [UpgradeStepType]::Cmdlet

            $cmdletUpgrade.SourceCommand = $rmCmdlet

            $cmdletUpgrade.FullPath = $rmCmdlet.FullPath

            $cmdletUpgrade.StartOffset = $rmCmdlet.StartOffset

            $cmdletUpgrade.Location = $rmCmdlet.Location

            $cmdletUpgrade.PlanResultReason = "Command can be automatically upgraded."

            $cmdletUpgrade.PlanResult = [PlanResultReasonCode]::ReadyToUpgrade

            $cmdletUpgrade.PlanSeverity = [DiagnosticSeverity]::Information

            $planSteps.Add($cmdletUpgrade)

            # check if parameters need to be updated

            if ($rmCmdlet.Parameters.Count -gt 0)

            {

                $resolvedAzCommand = $AzModuleSpec[$resolvedCommandName]

                foreach ($rmParam in $rmCmdlet.Parameters)

                {

                    if ($defaultParamNames -contains $rmParam.Name)

                    {

                        # direct match to a built-in default parameter

                        # no changes required.

                        continue

                    }

                    $matchedDirectName = $resolvedAzCommand.Parameters | Where-Object -FilterScript { $_.Name -eq $rmParam.Name }

                    if ($matchedDirectName -ne $null)

                    {

                        # direct match to the upgraded cmdlet's parameter name.

                        # no changes required.

                        continue

                    }

                    $matchedAliasName = $resolvedAzCommand.Parameters | Where-Object -FilterScript { $_.Aliases -contains $rmParam.Name }

                    if ($matchedAliasName -ne $null)

                    {

                        # alias match to the upgraded cmdlet's parameter name.

                        # we should add an upgrade step to swap to use the non-aliased name.

                        $paramUpgrade = New-Object -TypeName UpgradePlan

                        $paramUpgrade.Original = $rmParam.Name

                        $paramUpgrade.Replacement = $matchedAliasName.Name

                        $paramUpgrade.UpgradeType = [UpgradeStepType]::CmdletParameter

                        $paramUpgrade.SourceCommand = $rmCmdlet

                        $paramUpgrade.FullPath = $rmCmdlet.FullPath

                        $paramUpgrade.StartOffset = $rmParam.StartOffset

                        $paramUpgrade.SourceCommandParameter = $rmParam

                        $paramUpgrade.Location = $rmParam.Location

                        $paramUpgrade.PlanResultReason = "Command parameter can be automatically upgraded."

                        $paramUpgrade.PlanResult = [PlanResultReasonCode]::ReadyToUpgrade

                        $paramUpgrade.PlanSeverity = [DiagnosticSeverity]::Information

                        $planSteps.Add($paramUpgrade)

                        continue

                    }

                    # no direct match and no alias match?

                    # this could mean a breaking change that requires manual adjustments

                    $paramError = New-Object -TypeName UpgradePlan

                    $paramError.Original = $rmParam.Name

                    $paramError.UpgradeType = [UpgradeStepType]::CmdletParameter

                    $paramError.SourceCommand = $rmCmdlet

                    $paramError.FullPath = $rmCmdlet.FullPath

                    $paramError.StartOffset = $rmParam.StartOffset

                    $paramError.SourceCommandParameter = $rmParam

                    $paramError.Location = $rmParam.Location

                    $paramError.PlanResultReason = "Parameter was not found in $resolvedCommandName or its aliases."

                    $paramError.PlanResult = [PlanResultReasonCode]::ErrorParameterNotFound

                    $paramError.PlanSeverity = [DiagnosticSeverity]::Error

                    $planErrorSteps.Add($paramError)

                }

            }

        }

        # send metrics, if enabled (and while the collections are still seperated)

        Send-MetricsIfDataCollectionEnabled -Operation Plan `

            -ParameterSetName $PSCmdlet.ParameterSetName `

            -Duration ((Get-Date) - $cmdStarted) `

            -Properties ([PSCustomObject]@{

                ToAzureModuleName = "Az"

                ToAzureModuleVersion = $ToAzVersion

                UpgradeStepsCount = $planSteps.Count

                PlanWarnings = $planWarningSteps

                PlanErrors = $planErrorSteps

            })

        # join the collections into one output result.

        $planSteps.AddRange($planWarningSteps)

        $planSteps.AddRange($planErrorSteps)

        # sort the upgrade steps to by file, then offset descending.

        # the reason for this is updates must be made in descending offset order

        # otherwise file positions will change for subsequent swaps.

        $filter1 = @{ Expression = 'FullPath'; Ascending = $true }

        $filter2 = @{ Expression = 'StartOffset'; Descending = $true }

        $planSteps = $planSteps | Sort-Object -Property $filter1, $filter2

        # now that we have a sorted collection, add in the step order number

        # for extra clarity in the upgrade plan.

        for ([int]$i = 0; $i -lt $planSteps.Count; $i++)

        {

            $planSteps[$i].Order = ($i + 1)

        }

        Write-Output -InputObject $planSteps

    }

}

# SIG # Begin signature block

# MIIjkgYJKoZIhvcNAQcCoIIjgzCCI38CAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCA9V/n5h2IH9ijF

# nb4vtZ5TE2LjQjbEzUlxA8GEzf2CKaCCDYEwggX/MIID56ADAgECAhMzAAABh3IX

# chVZQMcJAAAAAAGHMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYTAlVTMRMwEQYD

# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25p

# bmcgUENBIDIwMTEwHhcNMjAwMzA0MTgzOTQ3WhcNMjEwMzAzMTgzOTQ3WjB0MQsw

# CQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9u

# ZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYDVQQDExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB

# AQDOt8kLc7P3T7MKIhouYHewMFmnq8Ayu7FOhZCQabVwBp2VS4WyB2Qe4TQBT8aB

# znANDEPjHKNdPT8Xz5cNali6XHefS8i/WXtF0vSsP8NEv6mBHuA2p1fw2wB/F0dH

# sJ3GfZ5c0sPJjklsiYqPw59xJ54kM91IOgiO2OUzjNAljPibjCWfH7UzQ1TPHc4d

# weils8GEIrbBRb7IWwiObL12jWT4Yh71NQgvJ9Fn6+UhD9x2uk3dLj84vwt1NuFQ

# itKJxIV0fVsRNR3abQVOLqpDugbr0SzNL6o8xzOHL5OXiGGwg6ekiXA1/2XXY7yV

# Fc39tledDtZjSjNbex1zzwSXAgMBAAGjggF+MIIBejAfBgNVHSUEGDAWBgorBgEE

# AYI3TAgBBggrBgEFBQcDAzAdBgNVHQ4EFgQUhov4ZyO96axkJdMjpzu2zVXOJcsw

# UAYDVR0RBEkwR6RFMEMxKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVyYXRpb25zIFB1

# ZXJ0byBSaWNvMRYwFAYDVQQFEw0yMzAwMTIrNDU4Mzg1MB8GA1UdIwQYMBaAFEhu

# ZOVQBdOCqhc3NyK1bajKdQKVMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA6Ly93d3cu

# bWljcm9zb2Z0LmNvbS9wa2lvcHMvY3JsL01pY0NvZFNpZ1BDQTIwMTFfMjAxMS0w

# Ny0wOC5jcmwwYQYIKwYBBQUHAQEEVTBTMFEGCCsGAQUFBzAChkVodHRwOi8vd3d3

# Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NlcnRzL01pY0NvZFNpZ1BDQTIwMTFfMjAx

# MS0wNy0wOC5jcnQwDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAgEAixmy

# S6E6vprWD9KFNIB9G5zyMuIjZAOuUJ1EK/Vlg6Fb3ZHXjjUwATKIcXbFuFC6Wr4K

# NrU4DY/sBVqmab5AC/je3bpUpjtxpEyqUqtPc30wEg/rO9vmKmqKoLPT37svc2NV

# BmGNl+85qO4fV/w7Cx7J0Bbqk19KcRNdjt6eKoTnTPHBHlVHQIHZpMxacbFOAkJr

# qAVkYZdz7ikNXTxV+GRb36tC4ByMNxE2DF7vFdvaiZP0CVZ5ByJ2gAhXMdK9+usx

# zVk913qKde1OAuWdv+rndqkAIm8fUlRnr4saSCg7cIbUwCCf116wUJ7EuJDg0vHe

# yhnCeHnBbyH3RZkHEi2ofmfgnFISJZDdMAeVZGVOh20Jp50XBzqokpPzeZ6zc1/g

# yILNyiVgE+RPkjnUQshd1f1PMgn3tns2Cz7bJiVUaqEO3n9qRFgy5JuLae6UweGf

# AeOo3dgLZxikKzYs3hDMaEtJq8IP71cX7QXe6lnMmXU/Hdfz2p897Zd+kU+vZvKI

# 3cwLfuVQgK2RZ2z+Kc3K3dRPz2rXycK5XCuRZmvGab/WbrZiC7wJQapgBodltMI5

# GMdFrBg9IeF7/rP4EqVQXeKtevTlZXjpuNhhjuR+2DMt/dWufjXpiW91bo3aH6Ea

# jOALXmoxgltCp1K7hrS6gmsvj94cLRf50QQ4U8Qwggd6MIIFYqADAgECAgphDpDS

# AAAAAAADMA0GCSqGSIb3DQEBCwUAMIGIMQswCQYDVQQGEwJVUzETMBEGA1UECBMK

# V2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0

# IENvcnBvcmF0aW9uMTIwMAYDVQQDEylNaWNyb3NvZnQgUm9vdCBDZXJ0aWZpY2F0

# ZSBBdXRob3JpdHkgMjAxMTAeFw0xMTA3MDgyMDU5MDlaFw0yNjA3MDgyMTA5MDla

# MH4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdS

# ZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMT

# H01pY3Jvc29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMTEwggIiMA0GCSqGSIb3DQEB

# AQUAA4ICDwAwggIKAoICAQCr8PpyEBwurdhuqoIQTTS68rZYIZ9CGypr6VpQqrgG

# OBoESbp/wwwe3TdrxhLYC/A4wpkGsMg51QEUMULTiQ15ZId+lGAkbK+eSZzpaF7S

# 35tTsgosw6/ZqSuuegmv15ZZymAaBelmdugyUiYSL+erCFDPs0S3XdjELgN1q2jz

# y23zOlyhFvRGuuA4ZKxuZDV4pqBjDy3TQJP4494HDdVceaVJKecNvqATd76UPe/7

# 4ytaEB9NViiienLgEjq3SV7Y7e1DkYPZe7J7hhvZPrGMXeiJT4Qa8qEvWeSQOy2u

# M1jFtz7+MtOzAz2xsq+SOH7SnYAs9U5WkSE1JcM5bmR/U7qcD60ZI4TL9LoDho33

# X/DQUr+MlIe8wCF0JV8YKLbMJyg4JZg5SjbPfLGSrhwjp6lm7GEfauEoSZ1fiOIl

# XdMhSz5SxLVXPyQD8NF6Wy/VI+NwXQ9RRnez+ADhvKwCgl/bwBWzvRvUVUvnOaEP

# 6SNJvBi4RHxF5MHDcnrgcuck379GmcXvwhxX24ON7E1JMKerjt/sW5+v/N2wZuLB

# l4F77dbtS+dJKacTKKanfWeA5opieF+yL4TXV5xcv3coKPHtbcMojyyPQDdPweGF

# RInECUzF1KVDL3SV9274eCBYLBNdYJWaPk8zhNqwiBfenk70lrC8RqBsmNLg1oiM

# CwIDAQABo4IB7TCCAekwEAYJKwYBBAGCNxUBBAMCAQAwHQYDVR0OBBYEFEhuZOVQ

# BdOCqhc3NyK1bajKdQKVMBkGCSsGAQQBgjcUAgQMHgoAUwB1AGIAQwBBMAsGA1Ud

# DwQEAwIBhjAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFHItOgIxkEO5FAVO

# 4eqnxzHRI4k0MFoGA1UdHwRTMFEwT6BNoEuGSWh0dHA6Ly9jcmwubWljcm9zb2Z0

# LmNvbS9wa2kvY3JsL3Byb2R1Y3RzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcmwwXgYIKwYBBQUHAQEEUjBQME4GCCsGAQUFBzAChkJodHRwOi8vd3d3Lm1p

# Y3Jvc29mdC5jb20vcGtpL2NlcnRzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcnQwgZ8GA1UdIASBlzCBlDCBkQYJKwYBBAGCNy4DMIGDMD8GCCsGAQUFBwIB

# FjNodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2RvY3MvcHJpbWFyeWNw

# cy5odG0wQAYIKwYBBQUHAgIwNB4yIB0ATABlAGcAYQBsAF8AcABvAGwAaQBjAHkA

# XwBzAHQAYQB0AGUAbQBlAG4AdAAuIB0wDQYJKoZIhvcNAQELBQADggIBAGfyhqWY

# 4FR5Gi7T2HRnIpsLlhHhY5KZQpZ90nkMkMFlXy4sPvjDctFtg/6+P+gKyju/R6mj

# 82nbY78iNaWXXWWEkH2LRlBV2AySfNIaSxzzPEKLUtCw/WvjPgcuKZvmPRul1LUd

# d5Q54ulkyUQ9eHoj8xN9ppB0g430yyYCRirCihC7pKkFDJvtaPpoLpWgKj8qa1hJ

# Yx8JaW5amJbkg/TAj/NGK978O9C9Ne9uJa7lryft0N3zDq+ZKJeYTQ49C/IIidYf

# wzIY4vDFLc5bnrRJOQrGCsLGra7lstnbFYhRRVg4MnEnGn+x9Cf43iw6IGmYslmJ

# aG5vp7d0w0AFBqYBKig+gj8TTWYLwLNN9eGPfxxvFX1Fp3blQCplo8NdUmKGwx1j

# NpeG39rz+PIWoZon4c2ll9DuXWNB41sHnIc+BncG0QaxdR8UvmFhtfDcxhsEvt9B

# xw4o7t5lL+yX9qFcltgA1qFGvVnzl6UJS0gQmYAf0AApxbGbpT9Fdx41xtKiop96

# eiL6SJUfq/tHI4D1nvi/a7dLl+LrdXga7Oo3mXkYS//WsyNodeav+vyL6wuA6mk7

# r/ww7QRMjt/fdW1jkT3RnVZOT7+AVyKheBEyIXrvQQqxP/uozKRdwaGIm1dxVk5I

# RcBCyZt2WwqASGv9eZ/BvW1taslScxMNelDNMYIVZzCCFWMCAQEwgZUwfjELMAkG

# A1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQx

# HjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEoMCYGA1UEAxMfTWljcm9z

# b2Z0IENvZGUgU2lnbmluZyBQQ0EgMjAxMQITMwAAAYdyF3IVWUDHCQAAAAABhzAN

# BglghkgBZQMEAgEFAKCBrjAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAcBgor

# BgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAvBgkqhkiG9w0BCQQxIgQgPe8adHpp

# Iud3x22zPgRlsGLHejtQ1k4tbMW1CWn3DLUwQgYKKwYBBAGCNwIBDDE0MDKgFIAS

# AE0AaQBjAHIAbwBzAG8AZgB0oRqAGGh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbTAN

# BgkqhkiG9w0BAQEFAASCAQBsIcGYOu8zCvB4kxQgbxZD5W2Txc7GteMJRm9MJZIZ

# jquiIp4Ixai61Sr/fET1DQd7q7sEFw2wRPMYAejzQgJjrotFMNpPDtb5EGFkMHX+

# tsDpyOM6ilHIP3vjJaEVgO3CiwLH1xrnAVjr1ACV3yTDRL+t9yi+3kujGnUtVWDy

# F91DKmC4qsBtb6Pxx1XAk/etvWNv2+ouW2QfTzofAhahgO2iC77050cvdXwMzoF6

# Ar7g19WwtnIVpXI2Q/yOD3tO7qzHoQcKQRmOqacjP77v9l/AEBiq3jpEVNk+hKVI

# YOj9d+nhQX7zTn073AOkwb0CZkVDSqUpHPSOyu8HzipXoYIS8TCCEu0GCisGAQQB

# gjcDAwExghLdMIIS2QYJKoZIhvcNAQcCoIISyjCCEsYCAQMxDzANBglghkgBZQME

# AgEFADCCAVUGCyqGSIb3DQEJEAEEoIIBRASCAUAwggE8AgEBBgorBgEEAYRZCgMB

# MDEwDQYJYIZIAWUDBAIBBQAEIBY7qK5mcH3PsVYlNiZH9qV5ewSM81Et1VZ46fy4

# QIp0AgZf25ctXtIYEzIwMjAxMjI1MDcxMTM2LjQxNVowBIACAfSggdSkgdEwgc4x

# CzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRt

# b25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKTAnBgNVBAsTIE1p

# Y3Jvc29mdCBPcGVyYXRpb25zIFB1ZXJ0byBSaWNvMSYwJAYDVQQLEx1UaGFsZXMg

# VFNTIEVTTjpGODdBLUUzNzQtRDdCOTElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUt

# U3RhbXAgU2VydmljZaCCDkQwggT1MIID3aADAgECAhMzAAABL7GnF3lWlBeHAAAA

# AAEvMA0GCSqGSIb3DQEBCwUAMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNo

# aW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29y

# cG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEw

# MB4XDTE5MTIxOTAxMTUwNloXDTIxMDMxNzAxMTUwNlowgc4xCzAJBgNVBAYTAlVT

# MRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQK

# ExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVy

# YXRpb25zIFB1ZXJ0byBSaWNvMSYwJAYDVQQLEx1UaGFsZXMgVFNTIEVTTjpGODdB

# LUUzNzQtRDdCOTElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUtU3RhbXAgU2Vydmlj

# ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKh8VkvVIwXD8sn0zT2n

# EdyEZ9UNHY7ACbOZA4obAHvD1hauw9K1Z2lRWG+m8Ars9l35GoMXdPgshM3hZKQW

# fhrLnF9/GDZoilhc2LhMqNPXs06rAJ8YODB6i0Cg1CFCYnyOYvywXKY3xGJN09Dg

# PXWfczEm2P/a3rmrXMrK5EFc3ahxrC51c+UuAMKV9xJyzJVLShPwPBJl+CjdMDPJ

# f24DZXIYec3gCN2xean1DFCI0gaqJprMeL4Om1KY2AZMIgBPEkoY1N7AI5e7ybkI

# L8+Mz3inijb4rDTkXk86ztUwy4bdc1MyKe2j2odT+QIDA2+M8cMTIGlKn7EyD2NN

# XU8CAwEAAaOCARswggEXMB0GA1UdDgQWBBSml/VRpBNFkAMDiqcoqWi85j/qljAf

# BgNVHSMEGDAWgBTVYzpcijGQ80N7fEYbxTNoWoVtVTBWBgNVHR8ETzBNMEugSaBH

# hkVodHRwOi8vY3JsLm1pY3Jvc29mdC5jb20vcGtpL2NybC9wcm9kdWN0cy9NaWNU

# aW1TdGFQQ0FfMjAxMC0wNy0wMS5jcmwwWgYIKwYBBQUHAQEETjBMMEoGCCsGAQUF

# BzAChj5odHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpL2NlcnRzL01pY1RpbVN0

# YVBDQV8yMDEwLTA3LTAxLmNydDAMBgNVHRMBAf8EAjAAMBMGA1UdJQQMMAoGCCsG

# AQUFBwMIMA0GCSqGSIb3DQEBCwUAA4IBAQB4q6ilv2SlGvJD/7dbfoIKZBO2i6YA

# wckw57TpCrt2+SAx2dcF7JvRMCPhLCSgqjyNcJRs40cEXPbLdzZMJHzcv73AF7L6

# mWZXg2aBjG1Sc5qM4jjE/nwIX+C6/odm5/asU4JIlFCuUZjzqdir18HkRVQve2Hw

# V0lCXHQs+V3m9DyyA9b6LSIk3GOFZu7F11Wyx/5dVXisPPTPwh9JXfMD9W173M1+

# ZZycmO03lUc4G1FilgpxWNdgWn/DO9ZhoW5yN6+BUddnJ4cCcCjcg8sB5rktPP8p

# VZAQ7aUqkAeqo+FuCkAUAdJRESCpR5wgSPtVvFPMjONE36DbKtfzkfiHMIIGcTCC

# BFmgAwIBAgIKYQmBKgAAAAAAAjANBgkqhkiG9w0BAQsFADCBiDELMAkGA1UEBhMC

# VVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNV

# BAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEyMDAGA1UEAxMpTWljcm9zb2Z0IFJv

# b3QgQ2VydGlmaWNhdGUgQXV0aG9yaXR5IDIwMTAwHhcNMTAwNzAxMjEzNjU1WhcN

# MjUwNzAxMjE0NjU1WjB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv

# bjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0

# aW9uMSYwJAYDVQQDEx1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAxMDCCASIw

# DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKkdDbx3EYo6IOz8E5f1+n9plGt0

# VBDVpQoAgoX77XxoSyxfxcPlYcJ2tz5mK1vwFVMnBDEfQRsalR3OCROOfGEwWbEw

# RA/xYIiEVEMM1024OAizQt2TrNZzMFcmgqNFDdDq9UeBzb8kYDJYYEbyWEeGMoQe

# dGFnkV+BVLHPk0ySwcSmXdFhE24oxhr5hoC732H8RsEnHSRnEnIaIYqvS2SJUGKx

# Xf13Hz3wV3WsvYpCTUBR0Q+cBj5nf/VmwAOWRH7v0Ev9buWayrGo8noqCjHw2k4G

# kbaICDXoeByw6ZnNPOcvRLqn9NxkvaQBwSAJk3jN/LzAyURdXhacAQVPIk0CAwEA

# AaOCAeYwggHiMBAGCSsGAQQBgjcVAQQDAgEAMB0GA1UdDgQWBBTVYzpcijGQ80N7

# fEYbxTNoWoVtVTAZBgkrBgEEAYI3FAIEDB4KAFMAdQBiAEMAQTALBgNVHQ8EBAMC

# AYYwDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBTV9lbLj+iiXGJo0T2UkFvX

# zpoYxDBWBgNVHR8ETzBNMEugSaBHhkVodHRwOi8vY3JsLm1pY3Jvc29mdC5jb20v

# cGtpL2NybC9wcm9kdWN0cy9NaWNSb29DZXJBdXRfMjAxMC0wNi0yMy5jcmwwWgYI

# KwYBBQUHAQEETjBMMEoGCCsGAQUFBzAChj5odHRwOi8vd3d3Lm1pY3Jvc29mdC5j

# b20vcGtpL2NlcnRzL01pY1Jvb0NlckF1dF8yMDEwLTA2LTIzLmNydDCBoAYDVR0g

# AQH/BIGVMIGSMIGPBgkrBgEEAYI3LgMwgYEwPQYIKwYBBQUHAgEWMWh0dHA6Ly93

# d3cubWljcm9zb2Z0LmNvbS9QS0kvZG9jcy9DUFMvZGVmYXVsdC5odG0wQAYIKwYB

# BQUHAgIwNB4yIB0ATABlAGcAYQBsAF8AUABvAGwAaQBjAHkAXwBTAHQAYQB0AGUA

# bQBlAG4AdAAuIB0wDQYJKoZIhvcNAQELBQADggIBAAfmiFEN4sbgmD+BcQM9naOh

# IW+z66bM9TG+zwXiqf76V20ZMLPCxWbJat/15/B4vceoniXj+bzta1RXCCtRgkQS

# +7lTjMz0YBKKdsxAQEGb3FwX/1z5Xhc1mCRWS3TvQhDIr79/xn/yN31aPxzymXlK

# kVIArzgPF/UveYFl2am1a+THzvbKegBvSzBEJCI8z+0DpZaPWSm8tv0E4XCfMkon

# /VWvL/625Y4zu2JfmttXQOnxzplmkIz/amJ/3cVKC5Em4jnsGUpxY517IW3DnKOi

# PPp/fZZqkHimbdLhnPkd/DjYlPTGpQqWhqS9nhquBEKDuLWAmyI4ILUl5WTs9/S/

# fmNZJQ96LjlXdqJxqgaKD4kWumGnEcua2A5HmoDF0M2n0O99g/DhO3EJ3110mCII

# YdqwUB5vvfHhAN/nMQekkzr3ZUd46PioSKv33nJ+YWtvd6mBy6cJrDm77MbL2IK0

# cs0d9LiFAR6A+xuJKlQ5slvayA1VmXqHczsI5pgt6o3gMy4SKfXAL1QnIffIrE7a

# KLixqduWsqdCosnPGUFN4Ib5KpqjEWYw07t0MkvfY3v1mYovG8chr1m1rtxEPJdQ

# cdeh0sVV42neV8HR3jDA/czmTfsNv11P6Z0eGTgvvM9YBS7vDaBQNdrvCScc1bN+

# NR4Iuto229Nfj950iEkSoYIC0jCCAjsCAQEwgfyhgdSkgdEwgc4xCzAJBgNVBAYT

# AlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYD

# VQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKTAnBgNVBAsTIE1pY3Jvc29mdCBP

# cGVyYXRpb25zIFB1ZXJ0byBSaWNvMSYwJAYDVQQLEx1UaGFsZXMgVFNTIEVTTjpG

# ODdBLUUzNzQtRDdCOTElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUtU3RhbXAgU2Vy

# dmljZaIjCgEBMAcGBSsOAwIaAxUAM/CZCUpclQ9qfr/r3y9osIIPSmSggYMwgYCk

# fjB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMH

# UmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSYwJAYDVQQD

# Ex1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAxMDANBgkqhkiG9w0BAQUFAAIF

# AOOP+LAwIhgPMjAyMDEyMjUwOTM1NDRaGA8yMDIwMTIyNjA5MzU0NFowdzA9Bgor

# BgEEAYRZCgQBMS8wLTAKAgUA44/4sAIBADAKAgEAAgIlGQIB/zAHAgEAAgIQ9zAK

# AgUA45FKMAIBADA2BgorBgEEAYRZCgQCMSgwJjAMBgorBgEEAYRZCgMCoAowCAIB

# AAIDB6EgoQowCAIBAAIDAYagMA0GCSqGSIb3DQEBBQUAA4GBALpNKy7Ly2bKPTUg

# XyQIvnfOTUb1cbVbHhFS8eLT8stuc3nJL3SK4wERcArTR8++rmer+m6HwlxA4BhX

# N0wN/OuXVTGczPy+9QqPraZUVOcVlbs9MOqClJdMCSRH4MNsFR5urHVWtLXJVa0Y

# POgNAoLzrd66Hf1AuueobhSsXQswMYIDDTCCAwkCAQEwgZMwfDELMAkGA1UEBhMC

# VVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNV

# BAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRp

# bWUtU3RhbXAgUENBIDIwMTACEzMAAAEvsacXeVaUF4cAAAAAAS8wDQYJYIZIAWUD

# BAIBBQCgggFKMBoGCSqGSIb3DQEJAzENBgsqhkiG9w0BCRABBDAvBgkqhkiG9w0B

# CQQxIgQgpRU+WSYZtbFgS1xf9sZaOxXwQintDWojo/wImSHRocAwgfoGCyqGSIb3

# DQEJEAIvMYHqMIHnMIHkMIG9BCBC5RecGZvugnvVXg80zlrGv1uV35LNk+H9dBj3

# ChFPvTCBmDCBgKR+MHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9u

# MRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRp

# b24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwAhMzAAAB

# L7GnF3lWlBeHAAAAAAEvMCIEIEycxyGcDIFkMVwJtt+owNjGeMEdksUsO9Vp339F

# P7TFMA0GCSqGSIb3DQEBCwUABIIBAGBnQGVWZl8R3M6UYgCRRySUv/gZDKqOgzbP

# LCWv46FlQxy43Ufh9m67GrD3sCSPaqTsGIvJyisa8lrqZ4i0HOt6sXWzHlomdWSU

# mhALxmcI0OpKvgkZT22SKt1+qjHzeTdwY4olRRQKWcjQZKaJQXTaWn6hSwHWGydB

# IjfMWXKVv7pQONnIxjIryZtWe5FNUXGUgEybQoGAAaasB9UQ8CjaTw7FYpLABUWK

# FbTrFvyqy3c0FNjlPtVcGj95Wq3XBslLLZ9dr90Aje8LJKNGF0gcX6I7q+I2FRp2

# 8Sj7He5pvcndRAh6Idw1SqoMRyBIwlBKJs5Q3n8wkHsiMEfUC+A=

# SIG # End signature block