Configurar um aplicativo ASP.NET para o Serviço de Aplicativo do Azure

2025-06-05

Observação

Para ASP.NET Core, consulte Configurar um aplicativo ASP.NET Core para o Serviço de Aplicativo do Azure. Se o aplicativo ASP.NET for executado em um contêiner personalizado do Windows ou do Linux, consulte Configurar um contêiner personalizado para o Serviço de Aplicativo do Azure.

Os aplicativos ASP.NET devem ser implantados no Serviço de Aplicativo do Azure como binários compilados. A ferramenta de publicação do Visual Studio cria a solução e implanta os binários compilados diretamente, enquanto o mecanismo de implantação do Serviço de Aplicativo implanta o repositório de código primeiro e, em seguida, compila os binários.

Este guia fornece os principais conceitos e instruções para desenvolvedores de ASP.NET. Se você nunca usou o Serviço de Aplicativo do Azure, siga o início rápido ASP.NET e ASP.NET com o tutorial do Banco de Dados SQL primeiro.

Mostrar versões de tempo de execução .NET Framework com suporte

No Serviço de Aplicativo, as instâncias do Windows já têm todas as versões do .NET Framework com suporte instaladas. Para mostrar o runtime do .NET Framework e as versões do SDK disponíveis para você, acesse seu aplicativo no portal do Azure. Selecione Ferramentas de Desenvolvimento>Ferramentas Avançadas. Selecione Ir. No Kudu, selecione o console de depuração para CMD ou PowerShell. Execute o comando apropriado no console baseado em navegador:

Para versões de runtime do CLR 4 (.NET Framework 4 e acima):

ls "D:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework"

A versão mais recente do .NET Framework pode não estar disponível imediatamente.

Para versões de runtime do CLR 2 (.NET Framework 3.5 e inferior):

ls "D:\Program Files (x86)\Reference Assemblies\Microsoft\Framework"

Se o runtime necessário pelo aplicativo não for compatível, você poderá implantá-lo com um contêiner personalizado.

Mostrar a versão atual do tempo de execução do .NET Framework

Execute o seguinte comando no Cloud Shell:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query netFrameworkVersion

Um valor de v4.0 significa que a versão mais recente do CLR 4 (.NET Framework 4.x) é usado. Um valor de v2.0 significa que uma versão do CLR 2 (.NET Framework 3.5) é usado.

Definir a versão de tempo de execução do .NET Framework

Por padrão, o Serviço de Aplicativo usa a versão de .NET Framework mais recente com suporte para executar o aplicativo ASP.NET. Para executar seu aplicativo usando o .NET Framework 3.5, execute o seguinte comando no Cloud Shell (v2.0 significa CLR 2):

az webapp config set --resource-group <resource-group-name> --name <app-name> --net-framework-version v2.0

O que acontece com ambientes de execução obsoletos no Azure App Service?

Runtimes desatualizados são descontinuados pela entidade mantenedora ou apresentam vulnerabilidades significativas. Assim, eles são removidos da criação e configuração de páginas no portal. Quando um runtime desatualizado está oculto do portal, qualquer aplicativo que ainda esteja usando esse runtime continuará sendo executado.

Se você quiser criar um aplicativo com uma versão de runtime desatualizada que não seja mais mostrada no portal, use a CLI do Azure, o modelo do ARM ou o Bicep. Essas alternativas de implantação permitem que você crie tempos de execução preteridos que foram removidos do portal, mas que ainda têm suporte.

Se um runtime for totalmente removido da plataforma do Serviço de Aplicativo, o proprietário da assinatura do Azure receberá um aviso por email antes da remoção.

Acessar variáveis de ambiente

No Serviço de Aplicativo, você pode definir configurações de aplicativo e cadeias de conexão fora do código do aplicativo. Em seguida, você pode acessá-las em qualquer classe usando o ASP.NET padrão:

using System.Configuration;
...
// Get an app setting
ConfigurationManager.AppSettings["MySetting"];
// Get a connection string
ConfigurationManager.ConnectionStrings["MyConnection"];
}

Se você definir uma configuração de aplicativo com o mesmo nome no Serviço de Aplicativo e em web.config, o valor do Serviço de Aplicativo terá precedência sobre o valor web.config . O valor de web.config local permite que você depure o aplicativo localmente, mas o valor do Serviço de Aplicativo permite que você execute o aplicativo no produto com as configurações de produção. As cadeias de conexão funcionam da mesma maneira. Dessa forma, você pode manter os segredos do aplicativo fora do seu repositório de código e acessar os valores apropriados sem alterar seu código.

Observação

Considere opções de conectividade mais seguras que não exijam segredos de conexão. Para obter mais informações, consulte Conectividade segura com os serviços e bancos de dados do Azure do Serviço de Aplicativo do Azure.

Implantar soluções multiprojetos

Quando uma solução do Visual Studio inclui vários projetos, o processo de publicação do Visual Studio já inclui a seleção do projeto a ser implantado. Quando você implanta no mecanismo de implantação do App Service, como com o Git ou com a implantação via ZIP com automação de build habilitada, o mecanismo de implantação do App Service seleciona o primeiro site ou projeto de aplicativo web que encontrar como o aplicativo do App Service. Você pode definir qual projeto o Serviço de Aplicativo deve usar especificando a configuração do aplicativo PROJECT. Por exemplo, execute o seguinte no Cloud Shell:

az webapp config appsettings set --resource-group <resource-group-name> --name <app-name> --settings PROJECT="<project-name>/<project-name>.csproj"

Obter a página de exceções detalhadas

Quando seu aplicativo ASP.NET gera uma exceção no depurador do Visual Studio, o navegador exibe uma página de exceção detalhada, mas no Serviço de Aplicativo que a página é substituída por uma mensagem de erro genérica. Para exibir a página de exceção detalhada no Serviço de Aplicativo, abra o arquivo Web.config e adicione o <customErrors mode="Off"/> elemento sob o <system.web> elemento. Por exemplo:

<system.web>
    <customErrors mode="Off"/>
</system.web>

Reimplante seu aplicativo com o Web.config atualizado. Você verá agora a mesma página de exceção detalhada.

Acessar logs de diagnóstico

Você pode adicionar mensagens de diagnóstico no código do aplicativo usando System.Diagnostics.Trace. Por exemplo:

Trace.TraceError("Record not found!"); // Error trace
Trace.TraceWarning("Possible data loss"); // Warning trace
Trace.TraceInformation("GET /Home/Index"); // Information trace

Para acessar os logs de console gerados de dentro do código do aplicativo no Serviço de Aplicativo, ative o log de diagnóstico executando o seguinte comando no Cloud Shell:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

Os valores possíveis para --level são Error, Warning, Info e Verbose. Cada nível seguinte inclui o anterior. Por exemplo, Error inclui apenas as mensagens de erro. Verbose inclui todas as mensagens.

Depois de ativar o log de diagnóstico, execute o seguinte comando para ver o fluxo de log:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Se os logs do console não aparecerem imediatamente, verifique novamente em 30 segundos.

Para interromper o streaming de log a qualquer momento, selecione Ctrl+C.

Compartilhar via