Использование канала Azure Artifacts как частного репозитория PowerShell

Azure DevOps Services

Azure Artifacts предоставляет удобное решение для совместного использования сценариев PowerShell. С помощью веб-каналов Azure Artifacts можно легко публиковать модули PowerShell из командной строки и управлять доступом к ним с помощью параметров веб-канала. В этой статье описано, как настроить веб-канал Azure Artifacts в качестве частного репозитория PowerShell для хранения и совместного использования модулей PowerShell.

В этой статье вы узнаете, как выполнять следующие задачи.

• Создание личного токена доступа
• Создание модуля PowerShell
• Создание хранилища SecretStore и регистрация репозитория
• Публикация и потребление пакетов из канала

Предварительные требования

• Создайте организацию Azure DevOps и проект, если вы еще не сделали этого.

• Создайте новый канал, если у вас еще нет.

• Установите PowerShell 6.0 или более поздней версии, чтобы обеспечить необходимую версию PowerShellGet для установки PSResourceGet.

• Установите PSResourceGet.

• Установите модули SecretManagement и SecretStore.

Примечание.

Поставщик учетных данных Azure Artifacts не поддерживается в PSResourceGet.

Создайте личный токен доступа

Личный маркер доступа выступает в качестве цифрового удостоверения и служит альтернативным паролем для проверки подлинности пользователей в Azure DevOps.

1. Перейдите в организацию Azure DevOps https://dev.azure.com/<ORGANIZATION_NAME>/

2. Щелкните значок параметров пользователя, выберите личные маркеры доступа и выберите новый маркер.

3. Введите имя для PAT, задайте дату окончания срока действия, выберите пользовательский, а затем выберите Упаковка чтение, запись и управление.

4. Нажмите кнопку "Создать " по завершении и убедитесь, что вы копируете и храните PAT в безопасном расположении.

   

Создание модуля PowerShell

Если у вас нет собственного модуля, следуйте инструкциям в этом разделе, чтобы создать пример модуля PowerShell. В противном случае перейдите к следующему шагу:

1. Создайте новую папку PowerShell-Demo. Перейдите в папку и создайте файл PowerShell-Demo.psm1.

2. Вставьте следующий скрипт в файл PowerShell-Demo.psm1 :

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

3. Создайте манифест модуля, выполнив следующую команду в каталоге PowerShell-Demo :

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

4. Откройте файл PowerShell-Demo.psd1 и найдите RootModule переменную. Этот параметр указывает основной файл скрипта, который PowerShell загружает при импорте модуля. Замените пустую строку на путь к файлу PowerShell-Demo.psm1:

   RootModule = 'PowerShell-Demo.psm1'
   

5. В FunctionsToExport разделе указывается, какие функции доступны пользователям при импорте модуля. Включите функцию PowerShell-Demo:

   FunctionsToExport = @('PowerShell-Demo')
   

6. FileList Найдите раздел, в котором перечислены файлы, включенные в упаковку модуля. Добавьте файл, который вы хотите упаковать с помощью модуля:

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

Регистрация репозитория

1. Выполните следующую команду, чтобы создать объект учетных данных. Замените заполнители правильными сведениями.

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

2. Убедитесь, что установлены SecretManagement и SecretStore , а затем выполните следующую команду, чтобы создать хранилище и добавить секрет:

   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. Чтобы проверить, были ли успешно созданы хранилище и секрет, выполните следующую команду, чтобы получить список всех секретов:

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

4. Выполните следующую команду, чтобы зарегистрировать репозиторий PowerShell. Вы можете найти SourceLocation ссылку, перейдя к Artifacts>Подключение к питанию>NuGet.exe в секции Настройка проекта> исходного URL.

   • Лента, охватывающая проект:

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

   • Веб-канал с областью действия организации:

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

   Совет

   Для некоторых версий PowerShell может потребоваться запуск нового сеанса после выполнения командлета Register-PSResourceRepository, чтобы предотвратить возникновение предупреждения Impossible to resolve package source.

5. Чтобы проверить успешность регистрации репозитория, выполните следующую команду, чтобы получить все зарегистрированные репозитории для текущего пользователя:

   Get-PSResourceRepository
   

Примечание.

Если возникла ошибка: код состояния ответа не указывает на успех: 404 (Не найдено)., убедитесь, что исходный URL-адрес указывает на nuget/v3/index.json вместо nuget/v2.

Публикация пакета

Выполните следующую команду, чтобы опубликовать пакет в вашей ленте. Замените заполнители путем указания пути к пакету, имени репозитория, созданным вами ранее объектом учетных данных и укажите любую строку для ApiKey.

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

Пример:

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'

Установка пакета

1. Чтобы убедиться, что модуль доступен в репозитории, используйте следующую команду для поиска:

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

2. Выполните следующую команду, чтобы установить последнюю стабильную версию модуля:

   Install-PSResource <MODULE_NAME>
   

Совет

Если возникнет ошибка: Исключение при вызове "WriteObject"., откройте новое окно PowerShell и выполните Get-SecretInfo. Введите пароль хранилища перед запуском Find-PSResource и Install-PSResource, так как срок ожидания SecretStore может истекать. Значение PasswordTimeout по умолчанию составляет 900 секунд, но это значение можно изменить по мере необходимости. Дополнительные сведения см. в статье "Использование SecretStore в службе автоматизации ".

В этой статье вы узнаете, как выполнять следующие задачи.

• Создание личного токена доступа
• Создание, упаковка и публикация модуля PowerShell
• Подключитесь к каналу как к репозиторию PowerShell
• Регистрация и установка модуля PowerShell с помощью Azure Pipelines

Предварительные требования

• Создайте организацию Azure DevOps и проект, если вы еще не сделали этого.

• Создайте новый канал, если у вас еще нет.

• Установите Azure Artifacts Credential Provider.

• Установите Windows MSBuild с помощью одного из следующих параметров:

  • Microsoft Visual Studio
  • Инструменты сборки для Visual Studio.
  • SDK для .NET Core.

• Установите NuGet(.exe) версии 4.8.0.5385 или более позднюю.

• Установите dotnet runtime версии 8.0.x или более поздней.

• Установите PowerShell 6.0 или более поздней версии, чтобы обеспечить наличие соответствующих версий PowerShellGet и PackageManagement.

Создайте личный токен доступа

Личный маркер доступа выступает в качестве цифрового удостоверения и служит альтернативным паролем для проверки подлинности пользователей в Azure DevOps.

1. Перейдите в организацию Azure DevOps https://dev.azure.com/<ORGANIZATION_NAME>/

2. Щелкните значок параметров пользователя, выберите личные маркеры доступа и выберите новый маркер.

3. Введите имя для PAT, задайте дату окончания срока действия, выберите пользовательский, а затем выберите Упаковка чтение, запись и управление.

4. Нажмите кнопку "Создать " по завершении и убедитесь, что вы копируете и храните PAT в безопасном расположении.

   

Создание модуля PowerShell

Если у вас нет собственного модуля, следуйте инструкциям в этом разделе, чтобы создать пример модуля PowerShell. В противном случае перейдите к следующему шагу:

1. Создайте новую папку Get-Hello. Перейдите в папку и создайте файл Get-Hello.psm1.

2. Вставьте следующий скрипт в файл Get-Hello.psm1 :

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

3. Создайте манифест модуля, выполнив следующую команду в каталоге Get-Hello :

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

4. Откройте файл Get-Hello.psd1 и найдите RootModule переменную. Этот параметр указывает основной файл скрипта, который PowerShell загружает при импорте модуля. Замените пустую строку, указав путь к файлу Get-Hello.psm1

   RootModule = 'Get-Hello.psm1'
   

5. В FunctionsToExport разделе указывается, какие функции доступны пользователям при импорте модуля. Включите функцию Get-Hello:

   FunctionsToExport = @('Get-Hello')
   

6. FileList Найдите раздел, который указывает файлы, включенные при упаковке модуля. Добавьте файл, который вы хотите упаковать с помощью модуля:

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

Упаковка и публикация модуля

1. Создайте nuspec-файл для модуля. Эта команда создает файл Get-Hello.nuspec , содержащий необходимые метаданные для упаковки модуля:

   nuget spec Get-Hello
   

2. Выполните следующую команду, чтобы упаковать модуль:

   nuget pack Get-Hello.nuspec
   

3. Выполните следующую команду, чтобы добавить URL-адрес источника веб-канала. Убедитесь, что вы используете версию 2 в URL-адресе источника веб-канала, так как NuGet версии 3 не поддерживается.

   • Веб-канал с областью действия организации:

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

   • Лента, охватывающая проект:

     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. Опубликуйте пакет в ленте.

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

Внимание

Номер версии в манифесте модуля (PSD1) должен совпадать с номером версии в nuspec-файле .

Подключитесь к каналу как к репозиторию PowerShell

Этот раздел поможет вам пройти авторизацию с вашим фидом как с репозиторием PowerShell и использовать модуль, размещенный в вашем фиде:

1. В окне командной строки PowerShell выполните следующую команду, чтобы настроить учетные данные. Замените заполнители соответствующими сведениями.

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

2. Зарегистрируйте репозиторий PowerShell. Вы можете найти SourceLocation ссылку, перейдя к Artifacts>Подключение к питанию>NuGet.exe в секции Настройка проекта> исходного URL.

   • Лента, охватывающая проект:

     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
     

   • Веб-канал с областью действия организации:

     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
     

   Совет

   Для некоторых версий PowerShell может потребоваться запуск нового сеанса после выполнения командлета Register-PSRepository, чтобы предотвратить возникновение предупреждения Impossible to resolve package source.

3. Зарегистрируйте источник пакета:

   • Лента, охватывающая проект:

     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
     

   • Веб-канал с областью действия организации:

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

   Примечание.

   • Register-PSRepository: используется для регистрации репозитория PowerShell для поиска и установки модулей.
     
   • Register-PackageSource: используется для регистрации источника пакета для поиска и публикации пакетов.

4. Чтобы проверить успешность регистрации репозитория, выполните следующую команду, чтобы получить все зарегистрированные репозитории для текущего пользователя:

   Get-PSRepository
   

5. Выполните следующую команду, чтобы установить модуль Get-Hello .

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

Примечание.

Если в вашей организации используется брандмауэр или прокси-сервер, убедитесь, что вы разрешаете доступ к URL-адресам домена и IP-адресам домена Azure Artifacts.

Установка пакета из конвейера

В этом примере показано, как выполнить аутентификацию с помощью канала артефактов Azure и установку модуля PowerShell из вашего конвейера. Чтобы использовать личный маркер доступа, добавьте его в качестве переменной конвейера, как показано ниже:

1. Войдите в организацию Azure DevOps и перейдите к проекту.

2. Выберите конвейеры, выберите определение конвейера и нажмите кнопку "Изменить ", чтобы изменить конвейер.

3. Выберите переменные в правом верхнем углу и нажмите кнопку "Создать переменную".

4. Введите имя переменной и вставьте личный маркер доступа в текстовое поле "Значение".

5. Убедитесь, что установите флажок «Сохранить это значение в секрете». Нажмите кнопку "ОК " после завершения.

6. Добавьте вторую переменную для имени пользователя. Введите имя переменной, а затем введите имя пользователя в текстовое поле "Значение".

7. Выберите Сохранить, когда вы закончите.

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'

Для корпоративных развертываний и повышения уровня безопасности, независимых от именованных учетных записей пользователей, SYSTEM_ACCESSTOKEN можно использовать для доступа к фиду артефактов Azure. Имя пользователя не требуется в этом контексте и может быть любой произвольной строкой для выполнения требований к параметру.

steps:
  - powershell: |
      $token = $env:SYSTEM_ACCESSTOKEN | ConvertTo-SecureString -AsPlainText -Force
      $credential = New-Object System.Management.Automation.PSCredential('ArbitraryPipelineUser', $token)
      Register-PSRepository -Name <REPOSITORY_NAME> -SourceLocation "$(PackageFeedEndpoint)" -InstallationPolicy Trusted -Credential $credential
    displayName: 'Register PSRepository'
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Связанные статьи

• Входящие источники
• Настройка разрешений
• Удаление и восстановление пакетов