Usar um feed de Artefatos do Azure como um repositório privado do PowerShell

Serviços de DevOps do Azure

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

Neste artigo, vai aprender a:

• Criar um token de acesso pessoal
• Criar um módulo do PowerShell
• Criar um cofre 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, se ainda não o fez.

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

• Instale o PSResourceGet.

• Instale os módulos SecretManagement e SecretStore .

Nota

O Provedor de Credenciais de Artefatos do Azure não é suportado 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 pessoais e, em seguida, selecione Novo token.

3. Introduza um nome para o seu PAT, defina uma Data de validade, selecione Personalizado definido e, em seguida, selecione Leitura de embalagem>, escrever e gerir.

4. Selecione Criar quando terminar e certifique-se de que copia e armazena o PAT num 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 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 em seu 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 são acessíveis aos 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 ficheiro que pretende empacotar com o seu módulo:

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

Registrar um repositório

1. Execute o seguinte comando 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 estão instalados e, em seguida, 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 seguinte comando para registrar seu repositório do PowerShell. Você pode encontrar o SourceLocation link navegando até Artifacts>Connect to Feed>NuGet.exe, na seção URL de origem da configuração > do projeto.

   • Feed com escopo do projeto:

     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 com escopo da organização:

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

   Gorjeta

   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
   

Nota

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

Publicar um pacote

Execute o seguinte comando para publicar o pacote no 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 módulo:

   Install-PSResource <MODULE_NAME>
   

Gorjeta

Se você encontrar o erro: Exceção chamando "WriteObject"., inicie uma nova janela do PowerShell e execute Get-SecretInfo. Introduza a palavra-passe do cofre antes de executar Find-PSResource e Install-PSResource, uma vez que o período de tempo limite do SecretStore pode expirar. O padrão PasswordTimeout é 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, vai 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, se ainda não o fez.

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

• Instale o Provedor de Credenciais de Artefatos do Azure.

• 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 pessoais e, em seguida, selecione Novo token.

3. Introduza um nome para o seu PAT, defina uma Data de validade, selecione Personalizado definido e, em seguida, selecione Leitura de embalagem>, escrever e gerir.

4. Selecione Criar quando terminar e certifique-se de que copia e armazena o PAT num 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 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 são acessíveis aos usuários quando eles importam seu módulo. Inclua sua função Get-Hello:

   FunctionsToExport = @('Get-Hello')
   

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

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

Empacotar e publicar um módulo

1. Gere um arquivo nuspec para o seu módulo. Este 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 o módulo:

   nuget pack Get-Hello.nuspec
   

3. Execute o seguinte comando para adicionar o URL de origem do feed. Certifique-se de usar a V2 no URL de origem do feed, pois o NuGet V3 não é suportado.

   • Feed com escopo da organização:

     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 com escopo do projeto:

     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 no seu feed:

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

Importante

O número da versão no manifesto do módulo (.psd1) deve ser idêntico ao número da versão no arquivo .nuspec .

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

Esta seção o orienta 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 seguinte comando 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 seção URL de origem da configuração > do projeto.

   • Feed com escopo do projeto:

     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 com escopo da organização:

     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
     

   Gorjeta

   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. Registe a origem do seu pacote:

   • Feed com escopo do projeto:

     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 com escopo da organização:

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

   Nota

   • 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 seguinte comando para instalar o módulo Get-Hello.

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

Nota

Se a sua organização utilizar uma firewall ou um servidor proxy, certifique-se de que permite o acesso a URLs de Domínio de Artefactos do Azure e endereços IP.

Instalar um pacote a partir do seu pipeline

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

1. Entre em 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. Introduza um Nome para a variável e, em seguida, cole o seu token de acesso pessoal na caixa de texto Valor .

5. Certifique-se de marcar a caixa de seleção Manter este valor secreto. Selecione Ok quando terminar.

6. Adicione uma segunda variável para seu userName. Introduza um Nome para a variável e, em seguida, introduza o seu Nome de utilizador na caixa de texto Valor.

7. Quando terminar, selecione Guardar.

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 a montante
• Configurar permissões
• Excluir e recuperar pacotes