Como configurar o Cloud Debugger para .NET Core

Visão geral

Nesta página, descrevemos como configurar o ambiente e o aplicativo .NET Core para usar o Cloud Debugger. Para alguns ambientes, é necessário especificar explicitamente o escopo de acesso para que o agente do Cloud Debugger envie dados. Recomendamos definir o escopo de acesso da forma mais ampla possível e depois usar o Gerenciador de identidade e acesso para restringir o acesso. Para manter essa prática recomendada, configure o escopo de acesso para todas as APIs do Cloud com a opção cloud-platform.

Versões de linguagem e ambientes de computação

O Cloud Debugger está disponível para .NET Core 1.0 a 2.1 nos seguintes ambientes de computação:

Ambiente padrão do App Engine	Ambiente flexível do App Engine	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	VMs e contêineres em execução em outra plataforma	Cloud Functions

Alfa

Essa biblioteca é coberta pelos Termos de ofertas pré-GA dos Termos de Serviço do Google Cloud. As bibliotecas pré-GA podem ter suporte limitado, e as mudanças nessas bibliotecas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

Como configurar o Cloud Debugger

Para configurar o Cloud Debugger, conclua as seguintes tarefas:

1. Verifique se a API Cloud Debugger está ativada no projeto.

2. Instale e configure o Debugger no ambiente de computação que você está usando.

3. Selecione o código-fonte.

Como verificar se a API Cloud Debugger está ativada

Para começar a usar o Cloud Debugger, verifique se a API Cloud Debugger está ativada. O Cloud Debugger é ativado por padrão na maioria dos projetos.
Ativar a API Cloud Debugger

Observação: o uso do Cloud Debugger é gratuito. No entanto, você precisa de um projeto do Google Cloud com o faturamento ativado antes de usar o Cloud Debugger.

Ambiente padrão do App Engine

O agente do Cloud Debugger para .NET Core não é compatível com o ambiente padrão do App Engine.

Ambiente flexível do App Engine

1. Altere runtime no seu app.yaml para custom:

   runtime: custom
   env: flex
   

2. Use um Dockerfile personalizado:

   FROM gcr.io/dotnet-debugger/aspnetcore:2.0
   COPY . /app
   WORKDIR /app
   
   # If you don't have source context delete the below line.
   # See 'Selecting source code automatically' below for more information.
   COPY ./source-context.json /usr/share/dotnet-debugger/agent/
   ENTRYPOINT ["/usr/share/dotnet-debugger/start-debugger.sh", "dotnet", "APPLICATION.dll"]
   

   Em que:

   • APPLICATION é o binário que você quer executar e depurar.

O pacote de operações do Google Cloud está pronto para ser usado com o aplicativo.

Para que a página "Depuração" no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao aplicativo implantado, consulte Como selecionar o código-fonte automaticamente.

Google Kubernetes Engine

GCLOUD

Para ativar o Debugger usando a gcloud, conclua as etapas abaixo:

1. Crie seu cluster com um destes escopos de acesso:

   • https://www.googleapis.com/auth/cloud-platform concede ao cluster acesso a todas as APIs do Google Cloud.

   • https://www.googleapis.com/auth/cloud_debugger concede ao cluster acesso apenas à API Stackdriver Debugger. Use esse escopo de acesso para reforçar a segurança do seu cluster.

   gcloud container clusters create example-cluster-name \
          --scopes=https://www.googleapis.com/auth/cloud_debugger
   

   Observação: não é possível alterar os escopos de acesso de um cluster após a criação.

2. Adicione as linhas a seguir ao Dockerfile para incluir o agente do Debugger ao app em contêiner:

   FROM gcr.io/dotnet-debugger/aspnetcore:2.0
   COPY . /app
   WORKDIR /app
   # If you don't have the source-context.json file, delete the `COPY` line below.
   # See running locally below for more information.
   COPY ./source-context.json /usr/share/dotnet-debugger/agent/
   
   ENV STACKDRIVER_DEBUGGER_MODULE=MODULE
   ENV STACKDRIVER_DEBUGGER_VERSION=VERSION
   
   # If not running on Google Cloud, uncomment and set the following:
   # ENV GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_FILE
   ENTRYPOINT ["/usr/share/dotnet-debugger/start-debugger.sh", "dotnet", "APPLICATION.dll"]
   

   Em que:

   • source-context.json é o arquivo formatado em JSON que contém sua configuração do contexto de origem. Consulte Como selecionar o código-fonte automaticamente para informações sobre como gerar esse arquivo;

   • MODULE é o nome do aplicativo. Junto com a versão, ele identifica o aplicativo no Console do Google Cloud. Por exemplo, MyApp, Backend ou Frontend;

   • VERSION é a versão do aplicativo, como o ID da compilação. O console do Google Cloud exibe o aplicativo em execução como MODULE - VERSION. Por exemplo, v1.0, build_147 ou v20160520;

   • CREDENTIALS_FILE é o caminho para o arquivo JSON das credenciais da conta de serviço;

   • APPLICATION é o ponto de entrada para o aplicativo .NET Core sendo executado com o Debugger anexado.

O depurador agora estará pronto para uso quando você implantar o app em contêiner.

Para informações mais detalhadas, consulte Como criar um cluster.

CONSOLE

Para ativar o Debugger usando o Console do Google Cloud, siga estas etapas:

1. Na seção Pool de nós, selecione Segurança e Definir acesso para cada API.

2. Ative o Debugger.

   

3. Opcional: selecione Permitir acesso total a todas as APIs do Cloud.

Agora, o depurador está pronto para ser usado com o aplicativo.

Para que a página "Depuração" no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao aplicativo implantado, consulte Como selecionar o código-fonte automaticamente.

Compute Engine

O agente do Cloud Debugger para .NET Core não é aceito no ambiente do Compute Engine.

Observação: encontre o código e a documentação do agente do Debugger (em inglês) no GitHub.

Local

Para usar o pacote de operações do Google Cloud ao executar seu aplicativo localmente, faça o seguinte:

• Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para apontar para o caminho completo do arquivo json da conta de serviço.
• Defina a variável de ambiente STACKDRIVER_DEBUGGER_MODULE como o nome do componente que está sendo depurado. O nome deste módulo vai aparecer na lista de módulos do Console do Google Cloud que podem ser depurados.
• Defina a variável de ambiente STACKDRIVER_DEBUGGER_VERSION para a versão lógica do módulo que está sendo depurado. Isso permite depurar várias versões lógicas do módulo no Console do Google Cloud.
• Defina a variável de ambiente STACKDRIVER_DEBUGGER_DEBUGGER para apontar para um local do binário do pacote de operações do Google Cloud.
• Se a execução ocorrer no Linux, configure a variável de ambiente LD_LIBRARY_PATH para incluir o diretório do pacote de operações do Google Cloud.

Ao criar o aplicativo .NET Core, inclua e implante arquivos PDB com seu código. Inclua as linhas a seguir em cada arquivo PDB:

    <PropertyGroup>
      <TargetFramework>netcoreapp2.1</TargetFramework>
      <DebugType>portable</DebugType>
    </PropertyGroup>

Observe que, ao depurar uma compilação Release, as variáveis podem ser identificadas incorretamente ou estar ausentes.