Uso de una fuente de Azure Artifacts como repositorio privado de PowerShell

Azure DevOps Services

Azure Artifacts proporciona una solución cómoda para compartir scripts de PowerShell. Mediante las fuentes de Azure Artifacts, puede publicar sin problemas los módulos de PowerShell desde la línea de comandos y controlar el acceso a ellos a través de la configuración de fuente. Este artículo le guía a través de la configuración de la fuente de Azure Artifacts como un repositorio privado de PowerShell para almacenar y compartir los módulos de PowerShell.

En este artículo, aprenderá a:

• Creación de un token de acceso personal
• Creación de un módulo de PowerShell
• Creación de un almacén de SecretStore y registro de un repositorio
• Publicación y consumo de paquetes desde una fuente

Requisitos previos

• Cree una organización de Azure DevOps y un proyecto si aún no lo ha hecho.

• Cree una fuente nueva si todavía no tiene una.

• Instale PSResourceGet.

• Instale los módulos SecretManagement y SecretStore .

Nota:

El proveedor de credenciales de Azure Artifacts no se admite con PSResourceGet.

Crear un token de acceso personal

Un token de acceso personal actúa como identidad digital y actúa como una contraseña alternativa para autenticarse con Azure DevOps.

1. Vaya a la organización de Azure DevOps. https://dev.azure.com/<ORGANIZATION_NAME>/

2. Seleccione el icono de configuración de usuario, seleccione Tokens de acceso personal y, a continuación, seleccione Nuevo token.

3. Escriba un nombre para su PAT, establezca una fecha de expiración, seleccione Personalizado definido y, a continuación, seleccione Empaquetado>de lectura, escritura y administración.

4. Seleccione Crear cuando haya terminado y asegúrese de copiar y almacenar el PAT en una ubicación segura.

   

Creación de un módulo de PowerShell

Si no tiene su propio módulo, siga las instrucciones de esta sección para crear un módulo de PowerShell de ejemplo. De lo contrario, vaya al paso siguiente:

1. Cree una carpeta PowerShell-Demo. Vaya a la carpeta y cree un nuevo archivo PowerShell-Demo.psm1.

2. Pegue el siguiente script en el archivo PowerShell-Demo.psm1 :

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

3. Genere el manifiesto del módulo ejecutando el siguiente comando en el directorio PowerShell-Demo :

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

4. Abra el archivo PowerShell-Demo.psd1 y busque la RootModule variable . Esta configuración especifica el archivo de script principal que PowerShell carga cuando se importa el módulo. Reemplace la cadena vacía por la ruta de acceso al archivo PowerShell-Demo.psm1 :

   RootModule = 'PowerShell-Demo.psm1'
   

5. La FunctionsToExport sección especifica qué funciones son accesibles para los usuarios cuando importan el módulo. Incluya la función PowerShell-Demo :

   FunctionsToExport = @('PowerShell-Demo')
   

6. Busque la FileList sección , que enumera los archivos incluidos al empaquetar el módulo. Agregue el archivo que desea empaquetar con el módulo:

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

Registro de un repositorio

1. Ejecute el comando siguiente para crear un objeto de credencial. Reemplace los marcadores de posición por la información correcta.

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

2. Asegúrese de que SecretManagement y SecretStore estén instalados y ejecute el siguiente comando para crear un almacén y agregar un secreto:

   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 comprobar si el almacén y el secreto se crearon correctamente, ejecute el siguiente comando para enumerar todos los secretos:

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

4. Ejecute el siguiente comando para registrar el repositorio de PowerShell. Para encontrar el SourceLocation vínculo, vaya a Artifacts Connect to Feed NuGet.exe (Artefactos>connect to Feed>NuGet.exe), en la sección > Configuración del proyecto url de origen.

   • Fuente con ámbito de proyecto:

     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 con ámbito de organización:

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

   Sugerencia

   Es posible que algunas versiones de PowerShell requieran iniciar una nueva sesión después de ejecutar el Register-PSResourceRepository cmdlet para evitar encontrar la advertencia no se puede resolver el origen del paquete .

5. Para comprobar si el repositorio se registró correctamente, ejecute el siguiente comando para recuperar todos los repositorios registrados para el usuario actual:

   Get-PSResourceRepository
   

Nota:

Si se produce el error: el código de estado de respuesta no indica que se ha realizado correctamente: 404 (no encontrado). Asegúrese de que la dirección URL de origen apunta a nuget/v3/index.json en lugar de nuget/v2.

Publicación de un paquete

Ejecute el siguiente comando para publicar el paquete en la fuente:

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

Ejemplo:

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'

Instalación de un paquete

1. Para confirmar si el módulo está disponible en el repositorio, use el siguiente comando para buscarlo:

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

2. Ejecute el siguiente comando para instalar la versión estable más reciente del módulo:

   Install-PSResource <MODULE_NAME>
   

Sugerencia

Si se produce el error: Excepción que llama a "WriteObject"., inicie una nueva ventana de PowerShell y ejecute Get-SecretInfo. Escriba la contraseña del almacén antes de ejecutar Find-PSResource e Install-PSResource, ya que el período de tiempo de espera de SecretStore puede expirar. El valor predeterminado PasswordTimeout es de 900 segundos, pero puede modificar este valor según sea necesario. Consulte Uso de SecretStore en automatización para obtener más detalles.

En este artículo, aprenderá a:

• Creación de un token de acceso personal
• Creación, empaquetado y publicación de un módulo de PowerShell
• Conexión a una fuente como repositorio de PowerShell
• Registro e instalación de un módulo de PowerShell mediante Azure Pipelines

Requisitos previos

• Cree una organización de Azure DevOps y un proyecto si aún no lo ha hecho.

• Cree una fuente nueva si todavía no tiene una.

• Instale el proveedor de credenciales de Azure Artifacts.

• Instale NuGet.

Crear un token de acceso personal

Un token de acceso personal actúa como identidad digital y actúa como una contraseña alternativa para autenticarse con Azure DevOps.

1. Vaya a la organización de Azure DevOps. https://dev.azure.com/<ORGANIZATION_NAME>/

2. Seleccione el icono de configuración de usuario, seleccione Tokens de acceso personal y, a continuación, seleccione Nuevo token.

3. Escriba un nombre para su PAT, establezca una fecha de expiración, seleccione Personalizado definido y, a continuación, seleccione Empaquetado>de lectura, escritura y administración.

4. Seleccione Crear cuando haya terminado y asegúrese de copiar y almacenar el PAT en una ubicación segura.

   

Creación de un módulo de PowerShell

Si no tiene su propio módulo, siga las instrucciones de esta sección para crear un módulo de PowerShell de ejemplo. De lo contrario, vaya al paso siguiente:

1. Cree una nueva carpeta Get-Hello. Vaya a la carpeta y cree un nuevo archivo Get-Hello.psm1.

2. Pegue el siguiente script en el archivo Get-Hello.psm1 :

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

3. Genere el manifiesto del módulo ejecutando el comando siguiente en el directorio Get-Hello :

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

4. Abra el archivo Get-Hello.psd1 y busque la RootModule variable . Esta configuración especifica el archivo de script principal que PowerShell carga cuando se importa el módulo. Reemplace la cadena vacía por la ruta de acceso al archivo Get-Hello.psm1 :

   RootModule = 'Get-Hello.psm1'
   

5. La FunctionsToExport sección especifica qué funciones son accesibles para los usuarios cuando importan el módulo. Incluya la función Get-Hello :

   FunctionsToExport = @('Get-Hello')
   

6. Busque la FileList sección , que especifica los archivos incluidos al empaquetar el módulo. Agregue el archivo que desea empaquetar con el módulo:

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

Empaquetar y publicar un módulo

1. Genere un archivo nuspec para el módulo. Este comando crea un archivo Get-Hello.nuspec que contiene los metadatos necesarios para empaquetar el módulo:

   nuget spec Get-Hello
   

2. Ejecute el siguiente comando para empaquetar el módulo:

   nuget pack Get-Hello.nuspec
   

3. Ejecute el siguiente comando para agregar la dirección URL del origen de la fuente. Asegúrese de usar V2 en la dirección URL del origen de la fuente, ya que No se admite NuGet V3.

   • Feed con ámbito de organización:

     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>"
     

   • Fuente con ámbito de proyecto:

     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 el paquete en la fuente:

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

Importante

El número de versión del manifiesto del módulo (.psd1) debe ser idéntico al número de versión del archivo .nuspec .

Conexión a una fuente como repositorio de PowerShell

Esta sección le guía a través de la autenticación con una fuente como repositorio de PowerShell y el consumo de un módulo hospedado en la fuente:

1. En una ventana del símbolo del sistema de PowerShell, ejecute el siguiente comando para configurar las credenciales. Reemplace los marcadores de posición por la información adecuada.

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

2. Registre el repositorio de PowerShell. Para encontrar el SourceLocation vínculo, vaya a Artifacts Connect to Feed NuGet.exe (Artefactos>connect to Feed>NuGet.exe), en la sección > Configuración del proyecto url de origen.

   • Fuente con ámbito de proyecto:

     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 con ámbito de organización:

     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
     

   Sugerencia

   Es posible que algunas versiones de PowerShell requieran iniciar una nueva sesión después de ejecutar el Register-PSRepository cmdlet para evitar encontrar la advertencia no se puede resolver el origen del paquete .

3. Registre el origen del paquete:

   • Fuente con ámbito de proyecto:

     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 con ámbito de organización:

     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: se usa para registrar un repositorio de PowerShell para buscar e instalar módulos.
     
   • Register-PackageSource: se usa para registrar un origen de paquete para buscar y publicar paquetes.

4. Para comprobar si el repositorio se registró correctamente, ejecute el siguiente comando para recuperar todos los repositorios registrados para el usuario actual:

   Get-PSRepository
   

5. Ejecute el siguiente comando para instalar el módulo Get-Hello .

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

Nota:

Si su organización usa un firewall o un servidor proxy, asegúrese de permitir el acceso a direcciones IP y direcciones URL de dominio de Azure Artifacts.

Instalación de un paquete desde la canalización

En este ejemplo se explica cómo autenticarse con una fuente de Azure Artifacts e instalar un módulo de PowerShell desde la canalización. Para usar el token de acceso personal, agréguelo como una variable de canalización, como se muestra a continuación:

1. Inicie sesión en su organización de Azure DevOps y vaya a su proyecto.

2. Seleccione Canalizaciones, seleccione la definición de canalización y, a continuación, seleccione Editar para modificar la canalización.

3. Seleccione Variables en la esquina superior derecha y, a continuación, seleccione Nueva variable.

4. Escriba un nombre para la variable y pegue el token de acceso personal en el cuadro de texto Valor .

5. Asegúrese de activar la casilla Mantener este secreto de valor. Seleccione Aceptar cuando haya terminado.

6. Agregue una segunda variable para userName. Escriba un nombre para la variable y, a continuación, escriba userName en el cuadro de texto Valor .

7. Cuando haya terminado, haga clic en 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'

Artículos relacionados

• Orígenes ascendentes
• Configuración de permisos
• Eliminación y recuperación de paquetes