Solução de problemas e problemas conhecidos (Ferramentas do Visual Studio para Unity)

  • Artigo

Nesta seção, você encontrará soluções para problemas comuns das Ferramentas do Visual Studio para Unity, as descrições de problemas conhecidos e aprenderá como ajudar a melhorar as Ferramentas do Visual Studio para Unity por meio de relatórios de erro.

Solução de problemas com a conexão entre o Unity e o Visual Studio

Confirme se Editor Attaching está habilitado ou Code Optimization On Startup está definido como Debug

No Menu do Unity, selecione Edit / Preferences.

Dependendo da versão do Unity:

  • Confirme se Code Optimization On Startup está definido como Debug.
  • Ou selecione a guia External Tools. Confirme se a caixa de seleção Editor Attaching está habilitada.

Para saber mais, confira a Documentação de preferências do Unity.

Não é possível anexar

  • Tente desabilitar o antivírus temporariamente ou criar regras de exclusão para o VS e o Unity.
  • Tente desabilitar o firewall temporariamente ou criar regras para permitir a rede TCP/UDP entre o Unity e o VS.
  • Alguns programas, como o Team Viewer, podem interferir com a detecção do processo. Você pode tentar interromper temporariamente algum software adicional para ver se algo muda.
  • Não renomeie o executável principal do Unity, uma vez que o VSTU está monitorando apenas os processos de “Unity.exe”.

O Visual Studio falha

O problema pode ser causado pela corrupção do cache do MEF do Visual Studio.

Tente remover a pasta a seguir para redefinir o cache do MEF (feche o Visual Studio antes de fazer isso):

%localappdata%\Microsoft\VisualStudio\<version>\ComponentModelCache

Isso deve corrigir o problema. Caso o problema persista, execute um prompt de comando do desenvolvedor do Visual Studio como administrador e use o seguinte comando:

 devenv /setup

O Visual Studio parou de responder

Vários plug-ins do Unity como Parse, FMOD, UMP (Player de Mídia Universal), ZFBrowser ou Embedded Browser usam threads nativos. Isso é um problema quando um plug-in acaba anexando um thread nativo ao runtime, fazendo chamadas de bloqueio para o sistema operacional. Neste caso, o Unity não consegue interromper esse thread para o depurador (ou o recarregamento de domínio) e para de responder.

Para o FMOD, há uma solução alternativa. Você pode passar o sinalizador de inicialização FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE para desabilitar o processamento assíncrono e executar todo o processamento no thread principal.

Se estiver desenvolvendo seu próprio plug-in nativo, recomendamos o uso de chamadas de procedimento assíncrono (APC) e, especialmente, SleepEx, SignalObjectAndWait, MsgWaitForMultipleObjectsEx, WaitForMultipleObjectsEx ou WaitForSingleObjectEx funções para cooperar adequadamente com o Unity e o Mono quando o depurador precisar suspender threads.

Projeto incompatível no Visual Studio

O mais importante é saber que o Visual Studio está salvando o estado "Incompatível" nas configurações do projeto e não tentará recarregar um projeto até que você use Reload Project de forma explícita. Portanto, após cada etapa de solução de problemas, tente reabrir a solução e clicar com o botão direito do mouse em todos os projetos incompatíveis e selecionar Reload Project.

  1. Verifique se o Visual Studio está definido como seu editor de script externo no Unity usando Edit / Preferences / External Tools.
  2. Dependendo da sua versão do Unity:
    • Verifique se o plug-in do Visual Studio está instalado no Unity. Help / About deve exibir uma mensagem como Ferramentas do Microsoft Visual Studio para Unity habilitada na parte inferior.
    • Unity 2020.x+: verifique se você está usando o pacote mais recente do Editor do Visual Studio em Window / Package Manager.
  3. Tente excluir todos os projetos/arquivos de solução e a pasta .vs em seu projeto.
  4. Tente recriar projetos/soluções usando Open C# Project ou Edit / Preferences / External tools / Regenerate Project files.
  5. Verifique se você instalou a carga de trabalho do Game/Unity no Visual Studio.
  6. Tente limpar o cache MEF, conforme explicado aqui.
  7. Tente instalar novamente o Visual Studio (usando a carga de trabalho de Game/Unity somente para iniciar).
  8. Tente desabilitar extensões de terceiros caso possam interferir na extensão do Unity em Tools / Extensions.

Recargas extras, ou o Visual Studio perde todas as janelas abertas

Certifique-se de nunca tocar nos arquivos de projeto diretamente de um processador de ativos ou de qualquer outra ferramenta. Se você realmente precisar manipular o arquivo de projeto, expomos uma API para isso. Consulte a seção de Problemas com referências de assembly.

Se você tiver recargas extras ou se o Visual Studio estiver perdendo todas as janelas abertas ao recarregar, verifique se você tem os pacotes corretos de direcionamento do .NET instalados. Verifique a seção a seguir sobre estruturas para obter mais informações.

O depurador não é interrompido quando há exceções

Ao usar o runtime do Unity herdado (equivalente ao .NET 3.5), o depurador sempre será interrompido quando uma exceção ficar sem tratamento (= fora de um bloco try/catch). Se a exceção for manipulada, o depurador usará a janela Configurações de Exceção para determinar se uma interrupção é necessária ou não.

Com o novo runtime (equivalente ao .NET 4.6), o Unity introduziu uma nova forma de gerenciar exceções de usuário e, como resultado, todas as exceções são vistas como "tratados pelo usuário", mesmo se estiverem fora de um bloco try/catch. Por isso, agora é necessário verificá-los explicitamente na janela Configurações de Exceção se você quiser que o depurador seja interrompido.

Na janela Configurações de Exceção (Depurar > Windows > Configurações de Exceção), expanda o nó de uma categoria de exceções (por exemplo, Exceções de Common Language Runtime, ou seja, exceções de .NET) e marque a caixa de seleção referente à exceção específica que você deseja capturar nessa categoria (por exemplo, System.NullReferenceException). Você também pode selecionar uma categoria inteira de exceções.

No Windows, o Visual Studio pede para baixar a estrutura de destino do Unity

Ao usar o runtime herdado do Unity (equivalente ao .NET 3.5), as Ferramentas do Visual Studio para Unity requerem o .NET Framework 3.5, que não está instalado por padrão no Windows 8 ou 10. Para corrigir esse problema, siga as instruções para baixar e instalar o .NET Framework 3.5.

Ao usar o novo runtime do Unity, os pacotes de direcionamento do .NET versão 4.6 ou 4.7.1 também são necessários dependendo da versão do Unity. É possível usar o instalador do Visual Studio para instalá-lo rapidamente (modificar sua instalação, componentes individuais, categoria do .NET, selecionar todos os pacotes de direcionamento 4.x).

Problemas de referência de assembly ou propriedade do projeto

Se seu projeto consegue lidar com referências complexas ou se você quiser controlar melhor essa etapa de geração, use nossa API para manipular o conteúdo da solução ou do projeto gerado. Você também pode usar arquivos de resposta no seu projeto Unity, que serão processados para você.

Com versões recentes do Visual Studio e do Unity, a melhor abordagem parece usar um arquivo personalizado Directory.Build.props junto com seus projetos gerados. Em seguida, é possível contribuir para a estrutura do projeto sem interferir no processo de geração.

Pontos de interrupção com um aviso

Se o Visual Studio não conseguir encontrar um local de origem para um ponto de interrupção específico, você verá um aviso ao lado do ponto de interrupção. Verifique se o script que você está usando está carregado e está sendo usado corretamente na cena atual do Unity.

Pontos de interrupção não atingidos

Verifique se o script que você está usando está carregado e está sendo usado corretamente na cena atual do Unity. Feche o Visual Studio e o Unity e exclua todos os arquivos gerados (*.csproj, *.sln) e a pasta .vs e toda a pasta Biblioteca. Saiba mais sobre a depuração do C# no site do Unity.

Não é possível depurar players Android

O multicast é usado para a detecção de player (que é o mecanismo padrão usado pelo Unity), mas depois disso, é usada uma conexão TCP regular para anexar o depurador. A fase de detecção é o principal problema para dispositivos Android.

O Wi-Fi é versátil, mas é muito lento em comparação com o USB devido à latência. Foi constatada uma falta de suporte adequado ao multicast para alguns roteadores ou dispositivos (a série Nexus é conhecida por isso).

O USB é bastante rápido para a depuração, e as Ferramentas do Visual Studio para Unity agora são capazes de detectar dispositivos USB e de se comunicar com o servidor adb para encaminhar corretamente as portas para depuração.

Problemas com o IntelliSense ou com a coloração de código

Tente atualizar o Visual Studio para a versão mais recente. Tente seguir as mesmas etapas de solução de problemas de Projetos incompatíveis.

Problemas conhecidos

Há problemas conhecidos nas Ferramentas do Visual Studio para Unity, decorrentes de como o depurador interage com a versão mais antiga do compilador C# do Unity. Estamos trabalhando para ajudar a corrigir esses problemas, mas, enquanto isso, você poderá enfrentar os seguintes problemas:

  • O Unity pode falhar durante a depuração.

  • O Unity pode congelar durante a depuração.

  • A intervenção ou saída de métodos pode se comportar incorretamente, especialmente em iteradores ou em instruções switch.

Relatar erros

Ajude-nos a melhorar a qualidade das Ferramentas do Visual Studio para Unity enviando relatórios de erro quando ocorrerem falhas, congelamentos ou outros erros. Isso nos ajuda a investigar e corrigir problemas nas Ferramentas do Visual Studio para Unity. Obrigado!

Como relatar um erro quando o Visual Studio congela

Há relatórios que indicam que, às vezes, o Visual Studio congela ao depurar com as Ferramentas do Visual Studio para Unity, mas precisamos de mais dados para entender esse problema. Ajude-nos a investigá-lo seguindo as etapas abaixo.

Para relatar que o Visual Studio congela durante a depuração com as Ferramentas do Visual Studio para Unity

No Windows:

  1. Abra uma nova instância do Visual Studio.

  2. Abra o diálogo Anexar ao Processo. Na nova instância do Visual Studio, escolha Depurar e Anexar ao Processo no menu principal.

  3. Anexe o depurador à instância congelada do Visual Studio. No diálogo Anexar ao Processo, selecione a instância congelada do Visual Studio na tabela Processos Disponíveis e, em seguida, escolha o botão Anexar.

  4. Pause o Depurador. Na nova instância do Visual Studio, no menu principal, escolha Depurar, Interromper Tudo ou apenas pressione Ctrl + Alt + Break.

  5. Crie um despejo de thread. Na janela Comando, insira o seguinte comando e pressione Enter:

    Debug.ListCallStack /AllThreads /ShowExternalCode

    Talvez seja necessário tornar a janela Comando visível primeiro. No Visual Studio, escolha Exibir, Outras Janelas, janela Comando no menu principal.

No Mac:

  1. Abra um terminal e obtenha o PID do Visual Studio para Mac:

    ps aux | grep "[V]isual Studio.app"

  2. Inicie o depurador lldb:

    lldb

  3. Anexe à instância do Visual Studio para Mac usando o PID:

    process attach --pid THE_PID_OF_THE_VSFM_PROCESS

  4. Recupere o rastreamento de pilha de todos os threads:

    bt all

Por fim, envie o despejo de thread para vstusp@microsoft.com, junto com uma descrição do que você estava fazendo quando o Visual Studio congelou.

Confira também