Usar um feed do Azure Artifacts como um repositório privado do PowerShell

Neste artigo, você aprenderá a:

Pré-requisitos

• Crie no Azure DevOps uma organização e um projeto, caso ainda não tenha feito isso.

• Crie um novo feed se você ainda não tiver um.

• Instale o PowerShell 6.0 ou posterior para garantir que você tenha a versão necessária do PowerShellGet necessária para instalar o PSResourceGet.

• Instale o PSResourceGet.

• Instale os módulos SecretManagement e SecretStore.

Criar um token de acesso pessoal

Um token de acesso pessoal atua como sua identidade digital e serve como uma senha alternativa para autenticação com o Azure DevOps.

1. Navegue até sua organização do Azure DevOps https://dev.azure.com/<ORGANIZATION_NAME>/

2. Selecione o ícone de configurações do usuário, selecione Tokens de acesso pessoal e, em seguida, selecione Novo Token.

3. Insira um nome para o seu PAT, defina uma data de Validade, selecione Definido pelo usuário e, em seguida, selecione Pacotes>Ler, gravar & gerenciar.

4. Selecione Criar quando terminar e copie e armazene seu PAT em um local seguro.

   

Criar um módulo do PowerShell

Se você não tiver seu próprio módulo, siga as instruções nesta seção para criar um módulo do PowerShell de exemplo. Caso contrário, vá para a próxima etapa:

1. Crie uma nova pasta PowerShell-Demo. Navegue até sua pasta e crie um novo arquivo PowerShell-Demo.psm1.

2. Cole o seguinte script no arquivo PowerShell-Demo.psm1:

   Function PowerShell-Demo{
       Write-Host "Hello World!"
   }
   

3. Gere o manifesto do módulo executando o seguinte comando no diretório PowerShell-Demo:

   New-ModuleManifest -Path .\PowerShell-Demo.psd1
   

4. Abra o arquivo PowerShell-Demo.psd1 e localize a variável RootModule. Essa configuração especifica o arquivo de script principal que o PowerShell carrega quando o módulo é importado. Substitua a cadeia de caracteres vazia pelo caminho para o arquivo PowerShell-Demo.psm1:

   RootModule = 'PowerShell-Demo.psm1'
   

5. A seção FunctionsToExport especifica quais funções podem ser acessadas pelos usuários quando eles importam seu módulo. Inclua sua função PowerShell-Demo:

   FunctionsToExport = @('PowerShell-Demo')
   

6. Localize a seção FileList, que lista os arquivos incluídos ao empacotar o módulo. Adicione o arquivo que deseja empacotar com seu módulo:

   FileList = @('./PowerShell-Demo.psm1')
   

Registrar um repositório

1. Execute o comando a seguir para criar um objeto de credencial. Substitua os espaços reservados pelas informações corretas.

   $username = "<USER_NAME>"
   $patToken = "<PERSONAL_ACCESS_TOKEN>" | ConvertTo-SecureString -AsPlainText -Force
   
   $credentials = New-Object System.Management.Automation.PSCredential($username, $patToken)
   

2. Certifique-se de que SecretManagement e SecretStore estejam instalados e execute o seguinte comando para criar um cofre e adicionar um segredo:

   Register-SecretVault -Name "MySecretVault" -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
   
   Set-Secret -Name "MyCredential" -Secret $credentials -Vault "MySecretVault"
   
   $CredentialInfo = [Microsoft.PowerShell.PSResourceGet.UtilClasses.PSCredentialInfo]::new('MySecretVault', 'MyCredential')
   

3. Para verificar se o cofre e o segredo foram criados com êxito, execute o seguinte comando para listar todos os seus segredos:

   PS > Get-SecretInfo
   
   Name            Type         VaultName
   ----            ----         ---------
   MyCredential    PSCredential MySecretVault
   
   

4. Execute o comando a seguir para registrar seu repositório do PowerShell. Você pode encontrar o link SourceLocation navegando até Artefatos>Conectar ao Feed>NuGet.exe, na seção Configuração do projeto e > URL de origem.

   • Feed do projeto com escopo:

     Register-PSResourceRepository -Name "PowershellPSResourceRepository" `
         -Uri "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v3/index.json" `
         -Trusted `
         -CredentialInfo $CredentialInfo
     

   • Feed da organização com escopo:

     Register-PSResourceRepository -Name "PowershellPSResourceRepository" `
         -Uri "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v3/index.json" `
         -Trusted `
         -CredentialInfo $CredentialInfo
     

   Dica

   Algumas versões do PowerShell podem exigir o início de uma nova sessão após a execução do cmdlet Register-PSResourceRepository para evitar encontrar o aviso Não é possível resolver a origem do pacote.

5. Para verificar se o repositório foi registrado, execute o seguinte comando para recuperar todos os repositórios registrados para o usuário atual:

   Get-PSResourceRepository
   

Publicar um pacote

Execute o comando a seguir para publicar o pacote no feed. Substitua os espaços reservados pelo caminho do pacote, pelo nome do repositório, pelo objeto de credencial criado anteriormente e forneça qualquer cadeia de caracteres para a ApiKey.

Publish-PSResource -Path <PACKAGE_PATH> -Repository <REPOSITORY_NAME> -Credential $credentials -ApiKey <ANY_STRING>

Exemplo:

PS C:\AzureDevOps\Demos\PowerShellDemo> Publish-PSResource -Path .\scripts\ -Repository FabrikamFiberFeed -Credential $credentials -ApiKey az -verbose
VERBOSE: Performing the operation "Publish-PSResource" on target "Publish resource
'C:\AzureDevOps\Demos\PowerShellDemo\scripts\' from the machine".
VERBOSE: The newly created nuspec is:
C:\Users\xxxx\AppData\Local\Temp\xxxxxxxxx\PowerShell-Demo.nuspec
VERBOSE: credential successfully read from vault and set for repository: FabrikamFiberFeed
VERBOSE: Successfully packed the resource into a .nupkg
VERBOSE: Successfully published the resource to
'https://pkgs.dev.azure.com/ramiMSFTDevOps/DemoProject/_packaging/FabrikamFiberFeed/nuget/v3/index.json'
VERBOSE: Deleting temporary directory 'C:\Users\xxxx\AppData\Local\Temp\xxxxxxx'

Instalar um pacote

1. Para confirmar se o módulo está disponível em seu repositório, use o seguinte comando para procurá-lo:

   Find-PSResource -Name <RESOURCE_NAME> -Repository <REPOSITORY_NAME> -verbose
   

2. Execute o seguinte comando para instalar a versão estável mais recente do seu módulo:

   Install-PSResource <MODULE_NAME>
   

Neste artigo, você aprenderá a:

Pré-requisitos

• Crie no Azure DevOps uma organização e um projeto, caso ainda não tenha feito isso.

• Crie um novo feed se você ainda não tiver um.

• Instale o provedor de credenciais do Azure Artifacts.

• Instale o WINDOWS MSBuild usando uma das seguintes opções:

  • Microsoft Visual Studio
  • Ferramentas de build do Visual Studio.
  • SDK do .NET Core.

• Instale o NuGet(.exe) versão 4.8.0.5385 ou posterior.

• Instale o dotnet Runtime versão 8.0.x ou posterior.

• Instale o PowerShell 6.0 ou posterior para garantir que você tenha as versões apropriadas do PowerShellGet e packageManagement .

Criar um token de acesso pessoal

Um token de acesso pessoal atua como sua identidade digital e serve como uma senha alternativa para autenticação com o Azure DevOps.

1. Navegue até sua organização do Azure DevOps https://dev.azure.com/<ORGANIZATION_NAME>/

2. Selecione o ícone de configurações do usuário, selecione Tokens de acesso pessoal e, em seguida, selecione Novo Token.

3. Insira um nome para o seu PAT, defina uma data de Validade, selecione Definido pelo usuário e, em seguida, selecione Pacotes>Ler, gravar & gerenciar.

4. Selecione Criar quando terminar e copie e armazene seu PAT em um local seguro.

   

Criar um módulo do PowerShell

Se você não tiver seu próprio módulo, siga as instruções nesta seção para criar um módulo do PowerShell de exemplo. Caso contrário, vá para a próxima etapa:

1. Crie uma nova pasta Get-Hello. Navegue até sua pasta e crie um novo arquivo Get-Hello.psm1.

2. Cole o seguinte script no arquivo Get-Hello.psm1:

   Function Get-Hello{
       Write-Host "Hello Azure DevOps!"
   }
   

3. Gere o manifesto do módulo executando o seguinte comando no diretório Get-Hello:

   New-ModuleManifest -Path .\Get-Hello.psd1
   

4. Abra o arquivo Get-Hello.psd1 e localize a variável RootModule. Essa configuração especifica o arquivo de script principal que o PowerShell carrega quando o módulo é importado. Substitua a cadeia de caracteres vazia pelo caminho para o arquivo Get-Hello.psm1:

   RootModule = 'Get-Hello.psm1'
   

5. A seção FunctionsToExport especifica quais funções podem ser acessadas pelos usuários quando eles importam seu módulo. Inclua sua função Get-Hello:

   FunctionsToExport = @('Get-Hello')
   

6. Localize a seção FileList, que especifica os arquivos incluídos ao empacotar o módulo. Adicione o arquivo que deseja empacotar com seu módulo:

   FileList = @('./Get-Hello.psm1')
   

Empacotar e publicar um módulo

1. Gere um arquivo nuspec para seu módulo. Esse comando cria um arquivo Get-Hello.nuspec contendo os metadados necessários para empacotar o módulo:

   nuget spec Get-Hello
   

2. Execute o seguinte comando para empacotar seu módulo:

   nuget pack Get-Hello.nuspec
   

3. Execute o comando a seguir para adicionar o URL de origem do feed. Use V2 no URL de origem do feed, pois não há suporte para o NuGet V3.

   • Feed da organização com escopo:

     nuget sources Add -Name "<FEED_NAME>" -Source "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v2" -username "<USER_NAME>" -password "<PERSONAL_ACCESS_TOKEN>"
     

   • Feed do projeto com escopo:

     nuget sources Add -Name "<FEED_NAME>" -Source "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v2" -username "<USER_NAME>" -password "<PERSONAL_ACCESS_TOKEN>"
     

4. Publique o pacote em seu feed:

   nuget push -Source "<FEED_NAME>" -ApiKey "<ANY_STRING>" "<PACKAGE_PATH>"
   

Conectar-se a um feed como um repositório do PowerShell

Esta seção orienta você na autenticação com um feed como um repositório do PowerShell e no consumo de um módulo hospedado em seu feed:

1. Em uma janela de prompt do PowerShell, execute o comando a seguir para configurar suas credenciais. Substitua os espaços reservados pelas informações adequadas.

   $patToken = "<PERSONAL_ACCESS_TOKEN>" | ConvertTo-SecureString -AsPlainText -Force
   
   $credsAzureDevopsServices = New-Object System.Management.Automation.PSCredential("<USER_NAME>", $patToken)
   

2. Registre seu repositório do PowerShell. Você pode encontrar o link SourceLocation navegando até Artefatos>Conectar ao Feed>NuGet.exe, na seção Configuração do projeto e > URL de origem.

   • Feed do projeto com escopo:

     Register-PSRepository -Name <REPOSITORY_NAME> -SourceLocation "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v2" -PublishLocation "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices
     

   • Feed da organização com escopo:

     Register-PSRepository -Name <REPOSITORY_NAME> -SourceLocation "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v2" -PublishLocation "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v2" -InstallationPolicy Trusted -Credential $credsAzureDevopsServices
     

   Dica

   Algumas versões do PowerShell podem exigir o início de uma nova sessão após a execução do cmdlet Register-PSRepository para evitar encontrar o aviso Não é possível resolver a origem do pacote.

3. Registre a origem do pacote:

   • Feed do projeto com escopo:

     Register-PackageSource -Name <REPOSITORY_NAME> -Location "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices
     

   • Feed da organização com escopo:

     Register-PackageSource -Name <REPOSITORY_NAME> -Location "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v2" -ProviderName NuGet -Trusted -SkipValidate -Credential $credsAzureDevopsServices 
     

   Observação

   • Register-PSRepository: usado para registrar um repositório do PowerShell para localizar e instalar módulos.
     
   • Register-PackageSource: usado para registrar uma origem de pacote para localizar e publicar pacotes.

4. Para verificar se o repositório foi registrado, execute o seguinte comando para recuperar todos os repositórios registrados para o usuário atual:

   Get-PSRepository
   

5. Execute o seguinte comando para instalar o módulo Get-Hello.

   Install-Module -Name <PACKAGE_NAME> -Repository <REPOSITORY_NAME>
   

Instalar um pacote do seu pipeline

Este exemplo orienta você na autenticação com um feed do Azure Artifacts e na instalação de um módulo do PowerShell do pipeline. Para usar seu token de acesso pessoal, adicione-o como uma variável de pipeline, conforme mostrado abaixo:

1. Entre na sua organização do Azure DevOps e navegue até seu projeto.

2. Selecione Pipelines,selecione a definição do pipeline e, em seguida, selecione Editar para modificá-lo.

3. Selecione Variáveis no canto superior direito e, em seguida, selecione Nova variável.

4. Insira um Nome para sua variável e cole seu token de acesso pessoal na caixa de texto Valor.

5. Marque a caixa de seleção Manter este valor em segredo. Quando terminar, selecione OK.

6. Adicione uma segunda variável para seu userName. Insira um Nome para sua variável e insira seu userName na caixa de texto Valor.

7. Selecione Salvar ao terminar.

trigger:
- main

pool:
  vmImage: 'Windows-latest'

variables:
  PackageFeedEndpoint: 'https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v2' ## For organization scoped feeds use'https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/nuget/v2'

steps:
- powershell: |
    $pat = ConvertTo-SecureString ${env:pat_token} -AsPlainText -Force
    $credential = New-Object System.Management.Automation.PSCredential("${env:userName}", $pat)
    Register-PSRepository -Name <REPOSITORY_NAME> -SourceLocation "$(PackageFeedEndpoint)" -InstallationPolicy Trusted -Credential $credential
  displayName: 'Register PSRepository'
  env:
    pat_token: $patToken
    userName: $userName

- powershell: |
    nuget install <PACKAGE_NAME> -Source "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/nuget/v3/index.json"
  displayName: 'Install module'