Trabalhar com repositórios privados do PowerShellGetWorking with Private PowerShellGet Repositories

O módulo PowerShellGet dá suporte a repositórios diferentes da Galeria do PowerShell.The PowerShellGet module support repositories other than the PowerShell Gallery. Esses cmdlets proporcionam os cenários a seguir:These cmdlets enable the following scenarios:

  • Dar suporte a um conjunto de módulos do PowerShell confiável e validado previamente para uso em seu ambienteSupport a trusted, pre-validated set of PowerShell modules for use in your environment
  • Testar um pipeline de CI/CD que compila os módulos ou scripts do PowerShellTesting a CI/CD pipeline that builds PowerShell modules or scripts
  • Fornecer módulos e scripts do PowerShell para sistemas que não podem acessar a InternetDeliver PowerShell scripts and modules to systems that can't access the internet
  • Oferecer scripts e módulos do PowerShell disponíveis apenas para sua organizaçãoDeliver PowerShell scripts and modules only available to your organization

Este artigo descreve como configurar um repositório local do PowerShell.This article describes how to set up a local PowerShell repository. O artigo também aborda o módulo OfflinePowerShellGetDeploy disponível na Galeria do PowerShell.The article also covers the OfflinePowerShellGetDeploy module available from the PowerShell Gallery. Esse módulo contém cmdlets para instalar a versão mais recente do PowerShellGet no seu repositório local.This module contains cmdlets to install the latest version of PowerShellGet into your local repository.

Tipos de repositório localLocal repository types

Há duas maneiras de criar um PSRepository local: Servidor do NuGet ou compartilhamento de arquivos.There are two ways to create a local PSRepository: NuGet server or file share. Cada tipo tem vantagens e desvantagens:Each type has advantages and disadvantages:

Servidor do NuGetNuGet Server

VantagensAdvantages DesvantagensDisadvantages
Imita a funcionalidade da PowerShellGalleryClosely mimics PowerShellGallery functionality Aplicativo de várias camadas requer planejamento de operações e suporteMulti-tier app requires operations planning & support
O NuGet integra-se ao Visual Studio e a outras ferramentasNuGet integrates with Visual Studio, other tools É necessário realizar o gerenciamento de contas do NuGet e do modelo de autenticaçãoAuthentication model and NuGet accounts management needed
O NuGet dá suporte a metadados em pacotes .NupkgNuGet supports metadata in .Nupkg packages A publicação requer manutenção e gerenciamento da chave de APIPublishing requires API Key management & maintenance
Fornece pesquisa, administração de pacote, etc.Provides search, package administration, etc.

Comp. de ArquivosFile Share

VantagensAdvantages DesvantagensDisadvantages
Fácil de configurar, fazer backup e manutençãoEasy to set up, back up, and maintain Os metadados usados pelo PowerShellGet não estão disponíveisMetadata used by PowerShellGet isn't available
Modelo de segurança simples: permissões de usuário no compartilhamentoSimple security model - user permissions on the share Nenhuma interface do usuário além do compartilhamento de arquivo básicoNo UI beyond basic file share
Não há restrições, como substituir itens existentesNo constraints such as replacing existing items Segurança limitada e sem gravação de quem atualiza o quêLimited security and no recording of who updates what

O PowerShellGet funciona com qualquer tipo e dá suporte à localização de versões e à instalação de dependências.PowerShellGet works with either type and supports locating versions and dependency installation. No entanto, alguns recursos que funcionam com a Galeria do PowerShell não estão disponíveis para servidores NuGet básicos ou compartilhamentos de arquivos.However, some features that work for the PowerShell Gallery aren't available for base NuGet servers or file shares.

  • Tudo é um pacote, não há diferenciação de scripts, módulos, recursos DSC ou recursos de função.Everything is a package - no differentiation of scripts, modules, DSC resources, or role capabilities.
  • Os servidores de compartilhamento de arquivos não podem ver os metadados do pacote, incluindo as marcas.File share servers can't see package metadata, including tags.

Criando um repositório localCreating a local repository

O artigo a seguir lista as etapas para configurar seu próprio servidor do NuGet.The following article lists the steps for setting up your own NuGet Server.

Siga as etapas até o ponto de adição de pacotes.Follow the steps up to the point of adding packages. As etapas para publicar um pacote são abordadas posteriormente neste artigo.The steps for publishing a package are covered later in this article.

Para um repositório com base em compartilhamento de arquivo, verifique se os usuários têm permissões para acessar o compartilhamento de arquivos.For a file share-based repository, make sure that your users have permissions to access the file share.

Registrando um repositório localRegistering a local repository

Antes de poder usar um repositório, ele deve ser registrado usando o comando Register-PSRepository.Before a repository can be used, it must be registered using the Register-PSRepository command. Nos exemplos a seguir, InstallationPolicy é definido como Confiável, supondo que você confie no seu próprio repositório.In the examples below, the InstallationPolicy is set to Trusted, on the assumption that you trust your own repository.

# Register a NuGet-based server
Register-PSRepository -Name LocalPSRepo -SourceLocation http://MyLocalNuget/Api/V2/ -ScriptSourceLocation http://MyLocalNuget/Api/V2 -InstallationPolicy Trusted

# Register a file share on my local machine
Register-PSRepository -Name LocalPSRepo -SourceLocation '\\localhost\PSRepoLocal\' -ScriptSourceLocation '\\localhost\PSRepoLocal\' -InstallationPolicy Trusted

Observe a diferença entre como os dois comandos tratam ScriptSourceLocation.Take note of the difference between how the two commands handle ScriptSourceLocation. Para um repositório baseado em compartilhamento de arquivo, SourceLocation e ScriptSourceLocation devem corresponder.For a file share-based repositories, the SourceLocation and ScriptSourceLocation must match. Para um repositório baseado na Web, eles devem ser diferentes; portanto, neste exemplo à direita "/" é adicionado a SourceLocation.For a web-based repository, they must be different, so in this example a trailing "/" is added to the SourceLocation.

Se você quiser que o PSRepository recém-criado seja o repositório padrão, cancele o registro de todos os outros PSRepositories.If you want the newly created PSRepository to be the default repository, you must unregister all other PSRepositories. Por exemplo:For example:

Unregister-PSRepository -Name PSGallery

Observação

O nome de repositório 'PSGallery' é reservado para uso pela Galeria do PowerShell.The repository name 'PSGallery' is reserved for use by the PowerShell Gallery. Você pode cancelar o registro de PSGallery, mas não é possível reutilizar esse nome para outro repositório.You can unregister PSGallery, but you cannot reuse the name PSGallery for any other repository.

Se você precisar restaurar a PSGallery, execute o seguinte comando:If you need to restore the PSGallery, run the following command:

Register-PSRepository -Default

Publicando em um repositório localPublishing to a local repository

Depois de registrar o PSRepository local, é possível publicar em seu PSRepository local.Once you've registered the local PSRepository, you can publish to your local PSRepository. Há dois cenários principais de publicação: publicar seu próprio módulo e publicar um módulo de PSGallery.There are two main publishing scenarios: publishing your own module and publishing a module from the PSGallery.

Publicando um módulo criado por vocêPublishing a module you authored

Use Publish-Module e Publish-Script para publicar seu módulo no PSRepository local da mesma maneira que faria com a Galeria do PowerShell.Use Publish-Module and Publish-Script to publish your module to your local PSRepository the same way you do for the PowerShell Gallery.

  • Especifique o local para seu códigoSpecify the location for your code
  • Forneça uma chave de APISupply an API key
  • Especifique o nome do repositório.Specify the repository name. Por exemplo, -PSRepository LocalPSRepoFor example, -PSRepository LocalPSRepo

Observação

Você deve criar uma conta no servidor do NuGet e entrar para gerar e salvar a chave de API.You must create an account in the NuGet server, then sign in to generate and save the API key. Para um compartilhamento de arquivos, use qualquer cadeia de caracteres não vazia para o valor de NuGetApiKey.For a file share, use any non-blank string for the NuGetApiKey value.

Exemplos:Examples:

# Publish to a NuGet Server repository using my NuGetAPI key
Publish-Module -Path 'c:\projects\MyModule' -Repository LocalPsRepo -NuGetApiKey 'oy2bi4avlkjolp6bme6azdyssn6ps3iu7ib2qpiudrtbji'
# Publish to a file share repo - the NuGet API key must be a non-blank string
Publish-Module -Path 'c:\projects\MyModule' -Repository LocalPsRepo -NuGetApiKey 'AnyStringWillDo'

Importante

Para garantir a segurança, as chaves de API não devem ser codificadas em scripts.To ensure security, API keys should not be hard-coded in scripts. Use um sistema seguro de gerenciamento de chaves.Use a secure key management system.

Publicando um módulo de PSGalleryPublishing a module from the PSGallery

Para publicar um módulo de PSGallery em seu PSRepository local, use o cmdlet 'Save-Package'.To publish a module from the PSGallery to your local PSRepository, you can use the 'Save-Package' cmdlet.

Exemplo:Example:

# Publish from the PSGallery to your local Repository
Save-Package -Name 'PackageName' -Provider NuGet -Source https://www.powershellgallery.com/api/v2 -Path '\\localhost\PSRepoLocal\'

Se o seu PSRepository local é baseado na Web, ele exige uma etapa adicional que usa nuget.exe para publicar.If your local PSRepository is web-based, it requires an additional step that uses nuget.exe to publish.

Consulte a documentação para usar nuget.exe.See the documentation for using nuget.exe.

Instalando o PowerShellGet em um sistema desconectadoInstalling PowerShellGet on a disconnected system

Implantar o PowerShellGet é difícil em ambientes que exigem que os sistemas sejam desconectados da Internet.Deploying PowerShellGet is difficult in environments that require systems to be disconnected from the internet. O PowerShellGet tem um processo de inicialização que instala a versão mais recente na primeira vez que ele é usado.PowerShellGet has a bootstrap process that installs the latest version the first time it's used. O módulo OfflinePowerShellGetDeploy na Galeria do PowerShell fornece cmdlets que dão suporte a esse processo de inicialização.The OfflinePowerShellGetDeploy module in the PowerShell Gallery provides cmdlets that support this bootstrap process.

Para iniciar uma implantação offline, você precisa:To bootstrap an offline deployment, you need to:

  • Baixar e instalar o OfflinePowerShellGetDeploy em seu sistema conectado à Internet e seus sistemas desconectadosDownload and install the OfflinePowerShellGetDeploy your internet-connected system and your disconnected systems
  • Baixe o PowerShellGet e suas dependências no sistema conectado à Internet usando o cmdlet Save-PowerShellGetForOfflineDownload PowerShellGet and its dependencies on the internet-connected system using the Save-PowerShellGetForOffline cmdlet
  • Copie o PowerShellGet e suas dependências do sistema conectado à Internet para o sistema desconectadoCopy PowerShellGet and its dependencies from the internet-connected system to the disconnected system
  • Use Install-PowerShellGetOffline no sistema desconectado para colocar o PowerShellGet e suas dependências nas pastas apropriadasUse the Install-PowerShellGetOffline on the disconnected system to place PowerShellGet and its dependencies into the proper folders

Os seguintes comandos usam Save-PowerShellGetForOffline para colocar todos os componentes em uma pasta f:\OfflinePowerShellGetThe following commands use Save-PowerShellGetForOffline to put all the components into a folder f:\OfflinePowerShellGet

# Requires -RunAsAdministrator
#Download the OfflinePowerShellGetDeploy to a location that can be accessed
# by both the connected and disconnected systems.
Save-Module -Name OfflinePowerShellGetDeploy -Path 'F:\' -Repository PSGallery
Import-Module F:\OfflinePowerShellGetDeploy

# Put PowerShellGet somewhere locally
Save-PowerShellGetForOffline -LocalFolder 'F:\OfflinePowerShellGet'

Neste ponto, você deve tornar o conteúdo de F:\OfflinePowerShellGet disponível para seus sistemas desconectados.At this point, you must make the contents of F:\OfflinePowerShellGet available to your disconnected systems. Execute o cmdlet Install-PowerShellGetOffline para instalar o PowerShellGet no sistema desconectado.Run the Install-PowerShellGetOffline cmdlet to install PowerShellGet on the disconnected system.

Observação

É importante que você não execute o PowerShellGet na sessão do PowerShell antes de executar esses comandos.It is important that you do not run PowerShellGet in the PowerShell session before running these commands. Depois de carregar o PowerShellGet na sessão, os componentes não podem ser atualizados.Once PowerShellGet is loaded into the session, the components cannot be updated. Se você iniciar o PowerShellGet por engano, saia e reinicie o PowerShell.If you do start PowerShellGet by mistake, exit and restart PowerShell.

Import-Module F:\OfflinePowerShellGetDeploy

Install-PowerShellGetOffline -LocalFolder 'F:\OfflinePowerShellGet'

Depois de executar esses comandos, você está pronto para publicar o PowerShellGet em seu repositório local.After running these commands, you are ready to publish PowerShellGet to your local repository.

# Publish to a NuGet Server repository using my NuGetAPI key
Publish-Module -Path 'F:\OfflinePowershellGet' -Repository LocalPsRepo -NuGetApiKey 'oy2bi4avlkjolp6bme6azdyssn6ps3iu7ib2qpiudrtbji'

# Publish to a file share repo - the NuGet API key must be a non-blank string
Publish-Module -Path 'F:\OfflinePowerShellGet' -Repository LocalPsRepo -NuGetApiKey 'AnyStringWillDo'

Usar soluções de Empacotamento para hospedar repositórios do PowerShellGetUse Packaging solutions to host PowerShellGet repositories

Você também pode usar soluções de empacotamento como o Azure Artifacts para hospedar um repositório público ou privado do PowerShellGet.You can also use packaging solutions like Azure Artifacts to host a private or public PowerShellGet repository. Para obter mais informações e instruções, confira a documentação do Azure Artifacts.For more information and instructions, see the Azure Artifacts documentation.

Importante

Para garantir a segurança, as chaves de API não devem ser codificadas em scripts.To ensure security, API keys should not be hard-coded in scripts. Use um sistema seguro de gerenciamento de chaves.Use a secure key management system.