Criar e manter uma instalação de rede do Visual Studio

Adoraríamos ouvir seus comentários!Reserve um momento para responder a esta pesquisa e nos informar como podemos melhorar a experiência de layout. Obrigado pelo seu apoio!

Às vezes, um administrador corporativo deseja criar um cache de instalação privada (também conhecido como "layout") que contém arquivos do Visual Studio que podem ser implantados em computadores do cliente dentro de uma organização.

A criação de um layout é útil nas seguintes situações:

• Um usuário tem permissões limitadas
• As máquinas clientes têm acesso limitado à internet
• Uma organização deseja padronizar uma versão específica do conjunto de ferramentas do desenvolvedor

Projetamos o Visual Studio para que um administrador possa criar e manter um layout e armazená-lo em um compartilhamento de rede interno e, opcionalmente, disponibilizá-lo na intranet de uma organização. O layout funciona como o local de origem de todos os arquivos do Visual Studio necessários para a instalação inicial do cliente e as atualizações subsequentes.

As informações nesta página são agrupadas em três seções principais:

• Criar o layout: descreve como criar o layout com o conteúdo correto do produto, definir as configurações padrão, armazená-lo em um compartilhamento de arquivos de rede e disponibilizá-lo em sua intranet.
• Manter o layout: informações de como atualizar melhor a versão do produto do layout ou modificar o conteúdo do produto do layout, as configurações do canal, a versão do instalador e o tamanho da pasta.
• Ajuda e suporte: onde pedir ajuda

Criar o layout

Preparar o local de armazenamento do compartilhamento de arquivos de rede

Primeiro, você precisa determinar onde armazenará os pacotes baixados do Visual Studio. Se você tiver várias edições do Visual Studio em uso na empresa (por exemplo, o Visual Studio 2022 Professional e o Visual Studio 2022 Enterprise), será necessário criar um layout separado para cada edição. Criar um layout separado para cada edição pode consumir muito espaço em disco, especialmente quando você considera que as atualizações de layout também consomem espaço em disco.

O demarcador de layout deve ter menos de 80 caracteres. Algumas organizações usam links simbólicos com sucesso para contornar a limitação de 80 caracteres.

Baixe o bootstrapper do Visual Studio para criar o layout

Baixe o bootstrapper correto para a edição do Visual Studio desejada e copie-o para o diretório que funcionará como repositório do layout. Depois que o layout for criado, você poderá usá-lo para instalar o Visual Studio em qualquer computador cliente. O bootstrapper é o arquivo executável que você usará para criar, atualizar e executar outras operações de layout. Você deve ter uma conexão com a Internet e permissões de administrador para concluir esta etapa.

Baixar os pacotes do Visual Studio

Você deve ter uma conexão com a Internet para concluir esta etapa.

Abra um prompt de comando com privilégios elevados, navegue até o diretório onde você baixou o bootstrapper e use os parâmetros do bootstrapper conforme definido na página Usar parâmetros de linha de comando para instalar o Visual Studio para criar e manter o layout de rede. Os exemplos a seguir ilustram maneiras comuns de criar layouts iniciais. Veja mais exemplos na página Exemplos de parâmetro de linha de comando para uma instalação do Visual Studio.

Um layout inicial completo para uma única localidade de idioma requer cerca de 40 GB de espaço em disco para o Visual Studio Community e cerca de 50 GB para o Visual Studio Enterprise. Extra Localidades de idioma adicionais exigem cerca de meio GB cada.

A abordagem recomendada é criar um layout inicial do Visual Studio com todas as cargas de trabalho e os idiomas apropriados e armazenar os pacotes no diretório de layout no servidor de rede. Dessa forma, qualquer instalação do cliente tem acesso a toda a oferta de produtos do Visual Studio e à capacidade de instalar qualquer subconjunto. Para criar um layout completo do Visual Studio, execute o seguinte comando no diretório no qual planeja hospedar o layout de rede:

vs_enterprise.exe --layout c:\VSLayout

Configurar o conteúdo de um layout

Há várias opções que você pode usar para personalizar o conteúdo do layout de rede. Você pode criar um layout parcial que contém apenas um conjunto específico de localidades de idiomas, cargas de trabalho, componentes e suas dependências recomendadas ou opcionais. Um layout parcial é útil se você sabe que só vai implantar um subconjunto de cargas de trabalho em estações de trabalho clientes. Parâmetros de linha de comando típicos para personalizar o layout incluem:

• --add para especificar IDs de componente ou carga de trabalho.
  Se --add for usado, somente as cargas de trabalho e os componentes especificados com --add serão baixados. Se --add não for usado, todas as cargas de trabalho e todos os componentes serão baixados.
• --includeRecommended para incluir todos os componentes recomendados para as IDs de carga de trabalho especificadas.
• --includeOptional para incluir todos os componentes opcionais para as IDs de carga de trabalho especificadas.
• --config para usar um arquivo *.vsconfig para especificar as cargas de trabalho, os componentes ou as extensões que devem ser incluídos ou referenciados pelo layout. Especifique o caminho completo do arquivo de configuração.
• --lang para especificar localidades de idiomas.

Veja alguns exemplos de como criar um layout de rede personalizado.

• Para criar um layout com componentes necessários para todas as cargas de trabalho em apenas um idioma, execute:

  vs_enterprise.exe --layout C:\VSLayout --lang en-US
  

• Para criar um layout com componentes necessários para todas as cargas de trabalho em vários idiomas, execute:

  vs_enterprise.exe --layout C:\VSLayout --lang en-US de-DE ja-JP
  

• Para criar um layout com uma carga de trabalho e todos os componentes necessários e recomendados para essa carga de trabalho em todos os idiomas, execute:

  vs_enterprise.exe --layout C:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --includeRecommended
  

• Para criar um layout com duas cargas de trabalho e um componente opcional em três idiomas, execute:

  vs_enterprise.exe --layout C:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --add Microsoft.VisualStudio.Workload.ManagedDesktop --add Microsoft.VisualStudio.Component.Git --lang en-US de-DE ja-JP
  

Usar um arquivo de configuração para inicializar o conteúdo de um layout

Você pode usar o parâmetro --config para transmitir em um arquivo *.vsconfig. Especifique o caminho completo do arquivo de configuração. O uso de um arquivo *.vsconfig durante a criação de layout personaliza e limita o conteúdo de um layout de rede ao que é especificado no arquivo de configuração. O arquivo de configuração é copiado para o diretório de layout e renomeado para layout.vsconfig.

As extensões especificadas no arquivo *.vsconfig não são copiadas diretamente para o layout. Em vez disso, o arquivo response.json do layout contém uma referência ao arquivo layout.vsconfig recém-criado, definindo o local de instalação das extensões do cliente. Se você estiver instalando extensões que não são assinadas digitalmente, certifique-se de editar o response.json para adicionar "allowUnsignedExtensions": true. Consulte os exemplos de conteúdo response.json.

vs_enterprise.exe --layout "C:\VSLayout" --config "C:\myconfig.vsconfig" 

Copiar o layout para um compartilhamento de rede

Você precisa hospedar o layout em um compartilhamento de rede para que ele possa ser acessado nos computadores cliente. Se você criou o layout em um computador local, precisará copiá-lo para um local de arquivo de rede. O exemplo a seguir usa xcopy. Também é possível usar o robocopy, caso queira. Exemplo:

xcopy /e c:\VSLayout \\server\share\layoutdirectory

Configurar padrões iniciais de instalação do cliente para este layout

Um arquivo chamado response.json é criado na pasta raiz do layout. Este arquivo personalizável fornece as configurações padrão iniciais para configurar no cliente, quando o cliente instala inicialmente a partir do layout. As opções de configuração comuns incluem a capacidade de configurar:

• Quais cargas de trabalho, componentes ou idiomas devem ser instalados por padrão no cliente
• Se os componentes recomendados também devem ser instalados
• Se o cliente deve respeitar um arquivo *.vsconfig de instalação
• De onde o cliente deve receber atualizações
• Se componentes sem suporte devem ser removidos durante uma atualização
• Se as extensões não assinadas tiverem permissão para carregar & silenciosamente e de forma programada

Veja mais informações na página Automatizar a instalação do Visual Studio com um arquivo de resposta.

Tornando o layout acessível por meio de um site da intranet

A partir de junho de 2023, você poderá disponibilizar os layouts em um site interno da intranet para aproveitar o cache de arquivos do servidor Web e os recursos de desempenho de replicação geográfica. Para usar esse novo recurso, você precisa usar os inicializador mais recentes do Visual Studio e o Instalador do Visual Studio mais recente. Os administradores de TI precisam fazer o seguinte para aproveitar essa funcionalidade de hospedagem na Web da intranet:

1. Primeiro, crie e mantenha um layout de rede e verifique se os bits estão presentes e atualizados regularmente no compartilhamento de rede. Além disso, lembre-se de configurar o valor de channelUri no response.json do layout se quiser que os clientes obtenham as atualizações do local do layout da intranet.

2. Em seguida, um administrador precisará preparar um site interno e associar a origem do site ao local do arquivo de rede do layout. Também precisam garantir que o servidor Web respeite os seguintes tipos MIME:

   Extensão do arquivo	Tipo MIME
   .cab	application/vnd.ms-cab-compressed
   .exe	application/octet-stream
   .json	application/json
   .msi	application/octet-stream
   .msu	application/octet-stream
   .nupkg	application/octet-stream
   .opc	application/octet-stream
   .ps1	application/postscript
   .vsix	application/octet-stream
   .xml	text/xml
   .zip	application/x-zip-compressed

3. Por fim, para implantar esse layout no cliente, execute um script do PowerShell no cliente para executar a instalação inicial. Depois que o Visual Studio for instalado com êxito no cliente por meio de um layout hospedado na Web, as atualizações do cliente de layouts hospedados na Web poderão ser feitas por meio de métodos padrão.

Verifique se o layout está usando o instalador mais recente

Se você estiver usando uma versão do Visual Studio enviada antes de junho de 2023, recomendamos que você sempre use o Instalador do Visual Studio mais recente no layout e distribua-o para os clientes. Por exemplo, se você distribuir o instalador do Visual Studio 2022 no layout do Visual Studio 2019, os clientes do Visual Studio 2019 com base nesse layout têm a capacidade de alterar o local de origem de atualizações ou remover facilmente componentes sem suporte. Encontre mais detalhes na seção a seguir.

A funcionalidade para garantir programaticamente que você está usando o instalador mais recente só está disponível para bootstrappers do Visual Studio 2019 criados após o Visual Studio 2022 enviado originalmente. Portanto, o vs_enterprise.exe no exemplo a seguir deve ser uma versão enviada após 10 de novembro de 2021.

Para criar um layout do produto inteiro que usa o maior e mais recente instalador disponível, execute

vs_enterprise.exe --layout C:\VSLayout --useLatestInstaller

Mantendo o layout

É uma melhor prática atualizar periodicamente o layout do Visual Studio para a versão segura mais recente do produto. Isso garante que o layout possa ser usado como um ponto de instalação e como uma fonte de atualização para instalações do cliente. A seção a seguir descreve as operações de manutenção de layout mais comuns ou úteis.

Se você hospedar um layout em um compartilhamento de arquivos de rede, baixe um layout atualizado em um compartilhamento local privado (por exemplo, c:\VSLayoutUpdate) e, depois que todo o conteúdo atualizado for baixado, copie-o no compartilhamento de arquivos de rede de layout (por exemplo, \server\products\VS). Se você não fizer isso, os usuários que executarem a instalação enquanto você estiver atualizando o layout poderão observar uma incompatibilidade de conteúdo do layout porque ele ainda não foi atualizado por completo.

Atualizar o layout para a versão mais atual do produto

A Microsoft lança com frequência versões atualizadas do produto para corrigir problemas de funcionalidade ou segurança. É altamente recomendável que você mantenha seu layout atualizado com a versão mais recente do produto para que os clientes sempre tenham acesso à versão mais recente e segura do produto. Isso é ainda mais importante quando os clientes não tem acesso à Internet e podem apenas receber atualizações do produto por meio do layout. O Visual Studio costuma lançar atualizações de segurança na segunda terça-feira do mês, conhecida como "terça-feira de patch", portanto, uma boa estratégia é atualizar todos os layouts nas tardes da terça-feira de patch.

Quando você cria o layout inicial, as opções especificadas, como quais cargas de trabalho e idiomas incluir no layout, são salvas no arquivo de configuração do layout layout.json. Posteriormente, ao atualizar o layout para uma versão mais recente do produto, você não precisará especificar novamente quais componentes do produto deseja no layout. Uma atualização de layout simplesmente atualiza os componentes existentes no layout para a versão mais atual.

Suponha que você já tenha criado esse layout parcial usando um dos bootstrappers evergreen da tabela acima.

vs_enterprise.exe --layout c:\VSLayout --add Microsoft.VisualStudio.Workload.ManagedDesktop --lang en-US

É fácil atualizar esse layout para a versão mais recente do produto, oferecida pela Microsoft e hospedada em servidores Microsoft. Basta usar o inicializador persistente existente no layout e executar o comando --layout em um prompt com privilégios elevados para baixar os pacotes mais recentes no layout, da seguinte maneira:

vs_enterprise.exe --layout c:\VSLayout

Você também pode atualizar o layout para uma versão atualizada de maneira autônoma. A operação de layout executa o processo de configuração em uma nova janela do console. A janela é deixada aberta para que os administradores possam ver o resultado final da atualização de layout e um resumo dos erros que podem ter ocorrido. Se você quiser executar uma operação de atualização de layout de maneira autônoma (por exemplo, se você tiver um script que é executado regularmente para atualizar seu layout para a versão mais recente), então, use o parâmetro --passive e o processo fechará automaticamente a janela.

vs_enterprise.exe --layout c:\VSLayout --passive

Atualizar o layout para uma versão específica do produto

Às vezes, talvez você queira atualizar seu layout para uma determinada versão do produto. Por exemplo, talvez você queira fazer com que seu layout corresponda à versão mais recente segura da linha de base de manutenção que você padronizou na sua organização. Veja como fazer isso:

visualstudioupdate-16.0.0to16.11.23.exe layout --layoutPath c:\VSLayout

visualstudioupdate-17.0.0to17.4.4.exe layout --layoutPath c:\VSLayout

Modificar o conteúdo de um layout

É possível modificar um layout parcial e adicionar outras cargas de trabalho, componentes ou idiomas. Não é possível remover componentes de um layout de modo confiável.

No exemplo a seguir, adicionaremos a carga de trabalho do Azure e um idioma localizado ao layout que foi criado anteriormente apenas com a carga de trabalho da Área de Trabalho Gerenciada e o idioma inglês. Depois de fazermos a modificação, as cargas de trabalho da Área de Trabalho Gerenciada e do Azure, e recursos em inglês e alemão, serão incluídos neste layout. Além de adicionar componentes, o comando --layout também fará com que o layout seja atualizado para a versão especificada pelo bootstrapper. Portanto, se você estiver usando o bootstrapper evergreen, o layout resultante terá o novo componente, o novo idioma e todo o conteúdo do layout será atualizado para a versão mais recente no canal do bootstrapper.

vs_enterprise.exe --layout c:\VSLayout --add Microsoft.VisualStudio.Workload.Azure --lang de-DE

Se você quiser atualizar um layout existente para que se torne um layout completo, use a opção --all, como mostrado no exemplo a seguir. Novamente, esse comando fará com que o conteúdo do layout seja atualizado para a versão especificada pelo bootstrapper.

vs_enterprise.exe --layout c:\VSLayout --all

Você pode adicionar componentes a um layout passando um arquivo *.vsconfig que contém os componentes adicionais desejados no layout. Se você fizer isso, o novo conteúdo *.vsconfig substituirá o conteúdo layout.vsconfig existente. Para obter mais informações, consulte a seção anterior Usando um arquivo de configuração para inicializar o conteúdo de um layout.

vs_enterprise.exe --layout C:\VSLayout --config "C:\myupdatedconfig.vsconfig"

Por fim, você pode editar diretamente o arquivo de configuração layout.json na pasta de layout e atualizar a seção "add" desse arquivo para incluir os componentes adicionais que deseja incluir no layout. Em seguida, você precisará atualizar o layout usando --layout, conforme descrito anteriormente para baixar os componentes mais recentes.

Configure o layout para remover componentes fora de suporte no computador cliente.

Algumas empresas vão querer aproveitar o recurso introduzido no Visual Studio 2022 versão 17.4, que remove componentes que passaram para um estado sem suporte. É algo relativamente fácil de configurar se você estiver gerenciando um layout e se seus clientes estiverem recebendo atualizações de administrador. Primeiro, você precisará configurar o layout para ter o versão mais recente do instalador, conforme descrito abaixo. Em segundo lugar, você precisará adicionar a linha "removeOos": true ao arquivo response.json. Se o layout tiver esses dois detalhes definidos corretamente, as atualizações subsequentes do administrador respeitarão a configuração e removerão componentes sem suporte dos computadores cliente.

Verificar um layout

Use --verify para executar a verificação no layout de rede que confirma se os arquivos de pacotes estão ausentes ou inválidos. No final da verificação, a lista de arquivos ausentes e inválidos é impressa.

A verificação funciona apenas para a versão mais recente de uma versão secundária específica do Visual Studio. Assim que uma nova versão for lançada, a verificação não funcionará em layouts com versões anteriores.

vs_enterprise.exe --layout <layoutDir> --verify

Lembre-se de que a Microsoft envia atualizações ao Visual Studio periodicamente, portanto, se você estiver usando um bootstrapper evergreen, um layout mais recente poderá não conter a mesma versão do layout inicial. No entanto, se você usar bootstrappers de link fixo, (quase) sempre obterá um conjunto de arquivos determinístico.

Corrigir um layout

Use --fix para executar a mesma verificação que --verify e também tentar corrigir os problemas identificados. O processo --fix precisa de uma conexão de Internet, portanto, verifique se o computador está conectado à Internet antes de você invocar --fix.

vs_enterprise.exe --layout <layoutDir> --fix

Remover versões mais antigas de um layout

Depois de executar atualizações de layout em um cache de rede, a pasta de layout pode ter alguns pacotes obsoletos que não são mais requeridos pela instalação do Visual Studio mais recente. Você pode usar a opção --clean para remover pacotes obsoletos de uma pasta de layout de rede.

Para fazer isso, você precisará dos caminhos de arquivo para os manifestos de catálogo que contêm esses pacotes obsoletos. Você pode encontrar os que manifestos de catálogo na pasta "Arquivo morto" do cache de layout de rede. Eles são salvos nela quando você atualiza um layout. Na pasta "Arquivo morto", há uma ou mais pastas chamadas "GUID", cada qual contendo um manifesto de catálogo obsoleto. O número de pastas "GUID" deve ser o mesmo que o número de atualizações feitas em seus layouts.

Alguns arquivos são salvos dentro de cada pasta "GUID". Os dois arquivos mais interessantes são um arquivo "catalog.json" e um arquivo "version.txt". O arquivo "catalog.json" é o manifesto de catálogo obsoleto que você precisará passar para a opção --clean. O outro arquivo, version.txt, contém a versão deste manifesto de catálogo obsoleto. Com base no número de versão, você pode decidir se deseja remover pacotes obsoletos do manifesto de catálogo. Você pode fazer o mesmo ao percorrer as outras pastas "GUID". Depois de tomar a decisão sobre os catálogos que deseja limpar, execute o comando --clean fornecendo os caminhos de arquivos para esses catálogos.

Aqui está um exemplo de como usar a opção --clean:

c:\VSLayout\vs_enterprise.exe --layout c:\VSLayout --clean c:\VSLayout\Archive\1cd70189-fc55-4583-8ad8-a2711e928325\Catalog.json --clean c:\VSLayout\Archive\d420889f-6aad-4ba4-99e4-ed7833795a10\Catalog.json

Quando você executa esse comando, a instalação analisa sua pasta de layout de rede para localizar a lista de arquivos que ela removerá. Você terá a oportunidade de examinar os arquivos que serão excluídos e confirmar as exclusões.

Configurar o layout para sempre incluir e fornecer o instalador mais recente

No entanto, se você estiver usando um layout criado antes de junho de 2023, também poderá configurar explicitamente o layout para sempre incluir e fornecer o instalador mais recente aos clientes, mesmo que o instalador seja considerado parte de uma versão mais recente do Visual Studio. Assim, ao atualizar o cliente com esse layout, o cliente adquirirá o instalador mais recente incluído e fornecido por esse layout. O benefício é que, depois que o instalador mais recente estiver no cliente, as instalações do cliente poderão aproveitar as correções de bugs e novas funcionalidades que continuamos a adicionar ao instalador.

Há várias maneiras de habilitar o layout para incluir e fornecer o instalador mais recente:

• Você pode usar uma versão do Visual Studio criada em junho de 2023 ou após essa data.

• Você pode passar o parâmetro --useLatestInstaller para o bootstrapper ao criar ou atualizar o layout. Isso fará com que uma configuração seja definida no arquivo layout.json, que pode ser encontrado no diretório raiz do layout. Aqui está um exemplo de como atualizar o layout e configurá-lo para usar o melhor e mais recente instalador disponível.

  vs_enterprise.exe --layout C:\VSLayout --useLatestInstaller
  

• Você pode editar o arquivo layout.json para adicionar essa configuração.

  {
     "installChannelUri": ".\\ChannelManifest.json",
     "channelUri": "\\\\server\\share\\layoutdirectory\\ChannelManifest.json",
     "installCatalogUri": ".\\Catalog.json",
     "channelId": "VisualStudio.16.Release",
     "productId": "Microsoft.VisualStudio.Product.Enterprise",
  
     "useLatestInstaller": true,
     "removeOos": true
  
  }
  

Não há como remover programaticamente essa configuração do arquivo layout.json, portanto, se você quiser que o layout pare de usar o instalador mais recente que a Microsoft disponibiliza e, em vez disso, use a versão do instalador que corresponde ao inicializador (que provavelmente é mais antigo que o instalador mais recente), edite o arquivo layout.json e remova a configuração "UseLatestInstaller": true.

Observe que você também pode encontrar essa configuração "UseLatestInstaller": true no arquivo response.json do layout, mas ela é ignorada lá para garantir que o layout sempre tenha o instalador mais recente. O arquivo response.json é usado para definir opções de configuração padrão no cliente quando o cliente instala ou atualiza a partir de um layout. Essa configuração "useLatestInstaller": true específica no arquivo layout.json é usada para garantir que o conteúdo do layout contenha o instalador mais recente, para que os computadores cliente possam adquirir o instalador mais recente do layout.

Códigos de erro

Se você tiver usado o parâmetro --wait, dependendo do resultado da operação, a variável de ambiente %ERRORLEVEL% será definida como um dos seguintes valores:

Obter suporte para o layout de rede

Caso você tenha um problema com o layout de rede, gostaríamos de saber a respeito. A melhor maneira de nos comunicar o assunto é usando a ferramenta Relatar um Problema, exibida no Instalador do Visual Studio e no IDE do Visual Studio. Se você for um Administrador de TI e não tiver o Visual Studio instalado, poderá enviar comentários de Administração de TI aqui. Ao usar essa ferramenta, será muito útil se você puder enviar os logs da ferramenta Visual Studio Collect, que pode nos ajudar a diagnosticar e corrigir o problema.

Também oferecemos uma opção de suporte por meio de chat de instalação (somente em inglês) para problemas relacionados à instalação.

Também temos outras opções de suporte disponíveis. Confira nossa Visual Studio Developer Community.

Conteúdo relacionado

• Guia do administrador do Visual Studio
• Implantar o Visual Studio usando um layout em um computador cliente
• Atualizar uma instalação em rede do Visual Studio
• Solução de erros relacionados à rede ao instalar ou usar o Visual Studio
• Configurar políticas para implantações empresariais do Visual Studio
• Ciclo de vida e manutenção do produto Visual Studio
• Usar parâmetros de linha de comando para instalar o Visual Studio
• IDs de carga de trabalho e de componente do Visual Studio
• Instalar os certificados necessários para instalação offline do Visual Studio