Partilhar via


Depurar remotamente o código Python no Linux no Visual Studio

Neste artigo, você explora como configurar a instalação do Visual Studio para dar suporte à depuração de código Python em computadores Linux remotos. Este passo a passo é baseado no Visual Studio 2019 versão 16.6.

O Visual Studio pode iniciar e depurar aplicativos Python local e remotamente em um computador Windows. O Visual Studio também dá suporte à depuração também pode depurar remotamente em um dispositivo ou sistema operacional diferente ou em uma implementação Python que não seja o CPython usando a biblioteca debugpy.

O Visual Studio 2019 versão 16.4 e anterior usa a biblioteca ptvsd. No Visual Studio 2019 versão 16.5 e posterior, a biblioteca debugpy substitui a ptvsd. Quando você usa a debugpy, o código do Python que está sendo depurado hospeda o servidor de depuração ao qual o Visual Studio pode se anexar. Essa hospedagem exige uma pequena modificação no seu código para importar e habilitar o servidor. Talvez também seja preciso ajustar as configurações de rede ou firewall no computador remoto para permitir as conexões TCP.

Pré-requisitos

  • Ter o Visual Studio instalado e compatível com cargas de trabalho do Python. Para obter mais informações, confira Instalar o suporte ao Python no Visual Studio.

  • Um computador remoto que execute o Python em um sistema operacional como o Mac OSX ou Linux.

  • A porta 5678 (entrada) abre no firewall desse computador remoto, que é o padrão para a depuração remota.

Configurar um computador Linux

Crie com facilidade uma máquina virtual do Linux no Azure e acesse-a usando a Área de Trabalho Remota no Windows. O Ubuntu para a máquina virtual é conveniente porque o Python é instalado por padrão. Se você tiver outra configuração, consulte Instalar interpretadores do Python para outros locais de download do Python.

Configurar o firewall

A porta de entrada 5678 deve estar aberta no firewall do computador remoto para dar suporte à depuração remota.

Para ver em detalhes como criar uma regra de firewall para uma máquina virtual do Azure, consulte estes artigos:

Preparar o script para depuração

Siga estes passos para preparar um script para depurar seu código Python no Linux.

  1. No computador remoto, crie um arquivo do Python chamado guessing-game.py com este código:

    import random
    
    guesses_made = 0
    name = input('Hello! What is your name?\n')
    number = random.randint(1, 20)
    print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))
    
    while guesses_made < 6:
        guess = int(input('Take a guess: '))
        guesses_made += 1
        if guess < number:
            print('Your guess is too low.')
        if guess > number:
            print('Your guess is too high.')
        if guess == number:
            break
    if guess == number:
        print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
    else:
        print('Nope. The number I was thinking of was {0}'.format(number))
    
  2. Instale o pacote debugpy no ambiente usando o comando pip3 install debugpy.

    Observação

    É recomendável gravar a versão do debugpy que está instalada caso você precise dela para solução de problemas. A listagem debugpy também mostra as versões disponíveis.

  3. Habilite a depuração remota adicionando o seguinte código na parte superior do arquivo guessing-game.py antes de outro código. (Embora esse não seja um requisito estrito, é impossível depurar os threads em segundo plano gerados antes que a função listen seja chamada.)

    import debugpy
    debugpy.listen(('0.0.0.0', 5678))
    
  4. Salve o arquivo e execute o programa:

    python3 guessing-game.py
    

    A chamada para a função listen é executada em segundo plano e aguarda as conexões de entrada enquanto você interage com o programa de outra maneira. Se quiser, você pode chamar a função wait_for_client depois de chamar a função listen para bloquear o programa até que o depurador seja anexado.

Dica

Além das funções listen e wait_for_client, o debugpy também fornece uma função breakpoint. Essa função serve como ponto de interrupção programático se o depurador estiver conectado. Outra função, is_client_connected1, retorna True se o depurador for anexado. Você não precisa verificar esse resultado antes de chamar outras funções debugpy.

Anexar remotamente por meio das Ferramentas Python

Os passos a seguir mostram como definir um ponto de interrupção para interromper o processo remoto.

  1. Crie uma cópia do arquivo remoto no computador local e abra-a no Visual Studio. Não importa a localização do arquivo, mas o nome deve corresponder ao nome do script no computador remoto.

  2. (Opcional) Para ter o IntelliSense para debugpy no computador local, instale o pacote de debugpy em seu ambiente de Python.

  3. Selecione Depurar>Anexar ao Processo.

  4. Na caixa de diálogo Anexar ao processo, defina Tipo de conexão como Python remoto (debugpy).

  5. No campo Destino da conexão, insira o comando tcp://<ip_address>:5678.

    • O tcp:// especifica o tipo de conexão como Protocolo TCP (protocolo de controle de transmissão).
    • <ip_address> é o endereço IP do computador remoto; ele pode ser um endereço explícito ou um nome como myvm.cloudapp.net.
    • :5678 é o número da porta de depuração remota.
  6. Selecione Enter para popular a lista de processos do debugpy disponíveis nesse computador:

    Screenshot that shows how to enter the connection target to see a list of available debugpy processes.

    Se outro programa for iniciado no computador remoto após a lista ser populada, selecione o botão Atualizar.

  7. Selecione o processo a ser depurado e selecione Anexar ou clique duas vezes no processo.

  8. Então, o Visual Studio alternará para o modo de depuração enquanto o script continuará a ser executado no computador remoto, fornecendo todos os recursos normais de depuração.

    Você pode definir um ponto de interrupção na linha if guess < number: e, em seguida, mude para o computador remoto e insira outra tentativa. O Visual Studio do seu computador local parará no ponto de interrupção, mostrará variáveis locais e assim por diante:

    Screenshot that shows how Visual Studio pauses debugging when a breakpoint is hit.

  9. Quando você parar de depurar, o Visual Studio irá se desanexar do programa. O programa continua sendo executado no computador remoto. O debugpy também continua a escuta para anexar depuradores, assim, é possível anexá-los novamente ao processo a qualquer momento.

Solucionar problemas de conexão

Analise os seguintes pontos para ajudar a solucionar problemas com a conexão.

  • Certifique-se de selecionar Python remota (debugpy) para Tipo de Conexão

  • Confirme que o segredo no Destino de Conexão corresponde exatamente ao segredo no código remoto.

  • Confirme o endereço IP no Destino de Conexão corresponde ao do computador remoto.

  • Verifique se a porta de depuração remota do computador remoto está aberta e se o destino da conexão inclui o sufixo da porta, como :5678.

    Para usar outra porta, especifique o número da porta na chamada para a função listen, como em debugpy.listen((host, port)). Nesse caso, certifique-se de abrir a porta específica no firewall.

  • Confirme se a versão de depuração instalada no computador remoto (conforme retornado pelo comando pip3 list) corresponde à versão do Visual Studio Python Tools (PTVS).

    A tabela a seguir lista os pares de versões válidos. Conforme necessário, atualize no computador remoto a versão do debugpy.

    Visual Studio Ferramentas do Python debugpy
    2019 16.6 1.0.0b5 1.0.0b5
    2019 16.5 1.0.0b1 1.0.0b1

Observação

O Visual Studio 2019 versão 16.0-16.4 utilizou ptvsd, não debugpy. O processo neste passo a passo para essas versões é semelhante, mas os nomes das funções são diferentes. O Visual Studio 2019 versão 16.5 usa depuração, mas os nomes de função eram iguais aos do ptvsd. Em vez de listen, você usaria enable_attach. Em vez de wait_for_client, você usaria wait_for_attach. Em vez de breakpoint, você usaria break_into_debugger.

Usar ptvsd 3.x para depuração herdada

O depurador herdado do ptvsd 3.x é o padrão no Visual Studio 2017 versão 15.7 e anterior.

Dependendo da configuração do Visual Studio, talvez seja preciso usar o ptvsd 3.x para depuração remota:

  • O Visual Studio 2017 versão 15.7 e anterior com Python 2.6, 3.1 a 3.4 ou IronPython
  • O Visual Studio 2019 versão 16.5 e posterior com Python 2.6, 3.1 a 3.4 ou IronPython
  • Versões 4.x anteriores

Se sua configuração implementar um cenário de versão mais antiga, o Visual Studio mostrará o erro, O depurador não dá suporte a este ambiente do Python.

Configurar depuração remota

Para se preparar para a depuração remota com o ptvsd 3.x, siga estes passos:

  1. Configure seu segredo, que é usado para restringir acesso ao script em execução.

    No ptvsd 3.x, a função enable_attach requer que você passe um "segredo" como o primeiro argumento.

    • Ao anexar o depurador remoto, insira o segredo com o comando enable_attach(secret="<secret>").

    Embora você possa permitir que qualquer pessoa se conecte usando o comando enable_attach(secret=None), essa opção não é recomendada.

  2. Crie a sua URL de destino de conexão no formato tcp://<secret>@<ip_address>:5678.

    • tcp:// especifica o tipo de conexão como TCP.
    • <secret> é a cadeia de caracteres passada com a função enable_attach no código Python.
    • <ip_address> é o endereço IP do computador remoto; ele pode ser um endereço explícito ou um nome como myvm.cloudapp.net.
    • :5678 é o número da porta de depuração remota.

Conexão segura com protocolo TCPS

Por padrão, a conexão com o servidor de depuração remota ptvsd 3.x é protegida somente pelo segredo e todos os dados são passados em texto sem formatação. Para uma conexão mais segura, o ptvsd 3.x dá suporte a SSL usando a forma segura do protocolo TCP ou TCPS.

Use estes passos para configurar o ptvsd 3.x para funcionar com o protocolo TCPS:

  1. No computador remoto, use o comando openssl para gerar arquivos separados para a chave e o certificado autoassinado:

    openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
    
    • No prompt, openssl digite o nome do host ou o endereço IP que você usa para se conectar ao Nome comum.

    Para obter mais informações, consulte Certificados autoassinados na documentação do módulo Python ssl. Observe que o comando descrito na documentação do Python gera somente um único arquivo combinado.

  2. No código, modifique a chamada para a função enable_attach para incluir os argumentos certfile e keyfile usando os nomes de arquivos como os valores. Esses argumentos têm o mesmo significado que para a função Python padrão ssl.wrap_socket.

    ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
    

    Você também pode fazer a mesma modificação no arquivo de código no computador local. Como esse código não é executado, ele não é estritamente necessário.

  3. Reinicie o programa de Python no computador remoto para que fique pronto para depuração.

  4. Proteja o canal adicionando o certificado à AC Raiz Confiável no computador Windows com o Visual Studio:

    1. Copie o arquivo de certificado do computador remoto para o computador local.

    2. Abra o Painel de Controle e acesse Ferramentas do Windows>Gerenciar certificados de computador.

    3. Na caixa de diálogo certlm [Certificados - computador local], expanda o nó Autoridades de Certificação Confiáveis, clique com o botão direito em Certificados e selecione Todas as tarefas>Importar.

    4. Procure e selecione o arquivo .cer copiado do computador remoto.

    5. Continue pelos prompts da caixa de diálogo para concluir o processo de importação.

  5. Repita o processo de anexação no Visual Studio, como descrito anteriormente em Anexar remotamente por meio das Ferramentas Python.

    Para este caso, defina tcps:// como o protocolo para o Destino da conexão (ou Qualificador).

    Screenshot that shows how to specify TCPS as the remote debugging transport with SSL.

Resolver os problemas de conexão

Ao tentar a conexão, o Visual Studio pode encontrar problemas. Analise os cenários a seguir e aplique a ação apropriada, conforme necessário.

  • O Visual Studio avisa sobre possíveis problemas de certificado ao se conectar via SSL.

    Ação: você pode ignorar a mensagem e continuar.

    Cuidado

    Lembre-se de que, embora o canal ainda esteja criptografado contra espionagem, ele pode estar aberto a ataques de man-in-the-middle.

  • O Visual Studio exibe o aviso de certificado remoto não confiável.

    Problema: o certificado não foi adicionado corretamente à AC de Raiz Confiável.

    Ação: verifique novamente os passos para adicionar o certificado à AC de Raiz Confiável no computador Windows e tente a conexão novamente.

    Screenshot of the warning that says the remote SSL certificate isn't trusted.

  • O Visual Studio mostra o aviso O nome do certificado remoto não corresponde ao nome do host.

    Problema: o nome de host ou endereço IP apropriado não está especificado para o Nome comum do certificado.

    Ação: verifique novamente os passos em Proteger a conexão com TCPS. Certifique-se de usar o Nome comum correto ao criar o certificado e tente a conexão novamente.

    Screenshot of the warning that says the remote SSL certificate doesn't match the hostname.