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

Azure DevOps Services

O Azure Artifacts fornece uma solução conveniente para compartilhar scripts do PowerShell. Usando feeds do Azure Artifacts, você pode publicar perfeitamente seus módulos do PowerShell na linha de comando e controlar o acesso a eles por meio das configurações do feed. Este artigo orienta você na configuração do feed do Azure Artifacts como um repositório privado do PowerShell para armazenar e compartilhar seus módulos do PowerShell.

Neste artigo, você aprenderá a:

• Criar um token de acesso pessoal
• Criar um módulo do PowerShell
• Criar um cofre do SecretStore e registrar um repositório
• Publicar e consumir pacotes de um feed

Pré-requisitos

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

• Crie um novo feed , caso ainda não tenha um.

• Instale o PSResourceGet.

• Instale os módulos SecretManagement e SecretStore .

Observação

Não há suporte para o Provedor de Credenciais do Azure Artifacts com PSResourceGet.

Criar um token de acesso pessoal

Um token de acesso pessoal atua como sua identidade digital e serve como uma senha alternativa para autenticá-lo 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 Personalizado definido e, em seguida, selecione Empacotamento>Ler, gravar e gerenciar.

4. Selecione Criar quando terminar e certifique-se de copiar e armazenar 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, pule 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 RootModule variável. 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 FunctionsToExport seção 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 FileList seção, 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 SourceLocation link navegando até Artifacts>Connect to Feed>NuGet.exe, na URL de origem da seção > Configuração do projeto.

   • 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 Register-PSResourceRepository cmdlet para evitar encontrar o aviso Não é possível resolver a origem do pacote.

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

   Get-PSResourceRepository
   

Observação

Se você encontrar o erro: O código de status da resposta não indica êxito: 404 (Não encontrado)., verifique se o URL de origem aponta para nuget/v3/index.json em vez de nuget/v2.

Publicar um pacote

Execute o seguinte comando para publicar o pacote em seu feed:

Publish-PSResource -Path <PACKAGE_PATH> -Repository <REPOSITORY_NAME> -ApiKey (Get-Secret <SECRET_NAME>) 

Exemplo:

PS C:\AzureDevOps\Demos\PowerShellDemo> Publish-PSResource -Path .\scripts\ -Repository FabrikamFiberFeed -ApiKey (Get-Secret MyNewCredential) -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>
   

Dica

Se você encontrar o erro: Exceção chamando "WriteObject"., inicie uma nova janela do PowerShell e execute Get-SecretInfo. Insira a senha do cofre antes de executar Find-PSResource e Install-PSResource, pois o período de tempo limite do SecretStore pode expirar. O PasswordTimeout padrão é de 900 segundos, mas você pode modificar esse valor conforme necessário. Consulte Usar o SecretStore na automação para obter mais detalhes.

Neste artigo, você aprenderá a:

• Criar um token de acesso pessoal
• Criar, empacotar e publicar um módulo do PowerShell
• Conectar-se a um feed como um repositório do PowerShell
• Registrar e instalar um módulo do PowerShell usando o Azure Pipelines

Pré-requisitos

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

• Crie um novo feed , caso ainda não tenha um.

• Instale o provedor de credenciais do Azure Artifacts.

• Instale o NuGet.

Criar um token de acesso pessoal

Um token de acesso pessoal atua como sua identidade digital e serve como uma senha alternativa para autenticá-lo 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 Personalizado definido e, em seguida, selecione Empacotamento>Ler, gravar e gerenciar.

4. Selecione Criar quando terminar e certifique-se de copiar e armazenar 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, pule 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 RootModule variável. 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 FunctionsToExport seção 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 FileList seção, 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. Certifique-se de usar V2 na 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>"
   

Importante

O número de versão no Manifesto do Módulo (.psd1) deve ser idêntico ao número de versão no arquivo .nuspec .

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 apropriadas.

   $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 SourceLocation link navegando até Artifacts>Connect to Feed>NuGet.exe, na URL de origem da seção > Configuração do projeto.

   • 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 Register-PSRepository cmdlet 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 fonte de pacote para localizar e publicar pacotes.

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

   Get-PSRepository
   

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

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

Observação

Se sua organização usa um firewall ou um servidor proxy, certifique-se de permitir o acesso às URLs e endereços IP do Domínio do Azure Artifacts.

Instalar um pacote do 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 sua definição de pipeline e, em seguida, selecione Editar para modificar seu pipeline.

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. Certifique-se de marcar a caixa de seleção Manter este valor em segredo . Selecione Ok quando terminar.

6. Adicione uma segunda variável para seu userName. Insira um Nome para sua variável e insira seu nomeDousuário 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'

Artigos relacionados

• Fontes upstream
• Configurar permissões
• Excluir e recuperar pacotes