Configurer une application ASP.NET Core pour Azure App Service

Article
11/04/2024

Notes

Pour ASP.NET dans .NET Framework, consultez Configurer une application ASP.NET pour Azure App Service. Si votre application ASP.NET Core s’exécute dans un conteneur Windows ou Linux personnalisé, consultez Configurer un conteneur personnalisé pour Azure App Service.

Les applications ASP.NET Core doivent être déployées pour Azure App Service en tant que fichiers binaires compilés. L’outil de publication de Visual Studio génère la solution, puis déploie directement les fichiers binaires compilés, alors que le moteur de déploiement d’App Service déploie en premier le référentiel de code, puis compile les fichiers binaires.

Ce guide fournit des concepts clés et des instructions pour les développeurs ASP.NET Core. Si vous n’avez jamais utilisé Azure App Service, suivez au préalable le Guide de démarrage rapide d’ASP.NET Core et le didacticiel sur ASP.NET Core avec SQL Database.

Afficher les versions du runtime .NET Core prises en charge

Dans App Service, toutes les versions de .NET Core prises en charge sont déjà installées sur les instances Windows. Pour afficher le runtime .NET Core et les versions du Kit de développement logiciel (SDK) disponibles, accédez à https://<app-name>.scm.azurewebsites.net/DebugConsole et exécutez la commande suivante dans la console basée sur navigateur :

dotnet --info

Afficher la version de .NET Core

Pour afficher la version actuelle de .NET Core, exécutez la commande suivante dans Cloud Shell :

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

Pour afficher toutes les versions de .NET Core prises en charge, exécutez la commande suivante dans Cloud Shell :

az webapp list-runtimes --os linux | grep DOTNET

Définir la version de .NET Core

Définissez la version cible de .NET Framework dans le fichier projet de votre projet ASP.NET Core. Pour plus d’informations, consultez Sélectionner la version .NET Core à utiliser dans la documentation .NET Core.

Exécutez la commande suivante dans Cloud Shell pour définir la version .NET Core sur 8.0 :

az webapp config set --name <app-name> --resource-group <resource-group-name> --linux-fx-version "DOTNETCORE|8.0"

Personnaliser l’automatisation de la génération

Remarque

La création d’applications .NET 9 (STS) avec Windows App Service en utilisant MSBuild ou SCM_DO_BUILD n’est pas encore prise en charge. La prise en charge de ces scénarios de build viendra après la date de disponibilité générale initiale et d’ici 4 décembre 2024. Les déploiements qui créent en dehors d’App Service via Visual Studio, Visual Studio Code, GitHub Actions et Azure DevOps sont entièrement pris en charge.

Si vous déployez votre application à l’aide de packages Git ou zip avec activation de l’automatisation de la génération, ce processus d’automatisation d’App Service exécute pas à pas la séquence suivante :

Exécution du script personnalisé s’il est spécifié par PRE_BUILD_SCRIPT_PATH.
Exécution de dotnet restore pour restaurer les dépendances NuGet.
Exécution de dotnet publish afin de générer un fichier binaire pour la production.
Exécution du script personnalisé s’il est spécifié par POST_BUILD_SCRIPT_PATH.

PRE_BUILD_COMMAND et POST_BUILD_COMMAND sont des variables d’environnement qui sont vides par défaut. Pour exécuter des commandes de prébuild, définissez PRE_BUILD_COMMAND. Pour exécuter des commandes post-build, définissez POST_BUILD_COMMAND.

L’exemple suivant définit les deux variables sur une série de commandes, séparées par des virgules.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Pour connaître d’autres variables d’environnement permettant de personnaliser l’automatisation de la génération, consultez Configuration d’Oryx.

Pour plus d’informations sur la façon dont App Service exécute et génère des applications ASP.NET Core dans Linux, consultez Documentation Oryx : Comment les applications .NET Core sont détectées et générées.

Accéder aux variables d’environnement

Dans App Service, vous pouvez définir les paramètres de l’application en dehors de votre code d’application. Vous pouvez ensuite y accéder dans n’importe quelle classe en utilisant le modèle d’injection de dépendances ASP.NET Core standard :

using Microsoft.Extensions.Configuration;

namespace SomeNamespace 
{
    public class SomeClass
    {
        private IConfiguration _configuration;
    
        public SomeClass(IConfiguration configuration)
        {
            _configuration = configuration;
        }
    
        public SomeMethod()
        {
            // retrieve nested App Service app setting
            var myHierarchicalConfig = _configuration["My:Hierarchical:Config:Data"];
            // retrieve App Service connection string
            var myConnString = _configuration.GetConnectionString("MyDbConnection");
        }
    }
}

Si vous configurez un paramètre d’application portant le même nom dans App Service et dans appsettings.json, la valeur d’App Service est prioritaire sur la valeur de appsettings.json. La valeur locale appsettings.json vous permet de déboguer l’application localement, tandis que la valeur d’App Service vous permet d’exécuter l’application en production avec les paramètres de production. Les chaînes de connexion fonctionnent de la même façon. De cette façon, vous pouvez conserver les secrets de votre application en dehors de votre référentiel de code et accéder aux valeurs appropriées sans modifier votre code.

Remarque

Envisagez des options de connectivité plus sécurisées qui ne nécessitent pas de secrets de connexion du tout. Pour plus d’informations, consultez Connectivité sécurisée aux services et bases de données Azure à partir d’Azure App Service.

Remarque

Notez que l’accès aux données de configuration hiérarchiques dans appsettings.json se fait à l’aide du délimiteur __ (double trait de soulignement) qui est standard sur Linux pour .NET Core. Pour remplacer un paramètre de configuration hiérarchique spécifique dans App Service, définissez le nom du paramètre d’application avec le même format délimité dans la clé. Vous pouvez exécuter l’exemple suivant dans le service Cloud Shell :

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings My__Hierarchical__Config__Data="some value"

Notes

Notez que l’accès aux données de configuration hiérarchiques dans appsettings.json se fait à l’aide du délimiteur : qui est standard pour .NET Core. Pour remplacer un paramètre de configuration hiérarchique spécifique dans App Service, définissez le nom du paramètre d’application avec le même format délimité dans la clé. Vous pouvez exécuter l’exemple suivant dans le service Cloud Shell :

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings My:Hierarchical:Config:Data="some value"

Déployer des solutions à projets multiples

Quand une solution Visual Studio comprend plusieurs projets, le processus de publication de Visual Studio comprend déjà la sélection du projet à déployer. Lorsque vous effectuez un déploiement vers le moteur de déploiement App Service, comme c’est le cas avec Git ou Zip Deploy, avec l’automatisation de la génération activée, le moteur de déploiement App Service sélectionne le premier site web ou projet d’application web qu’il trouve en tant qu’application App Service. Vous pouvez spécifier le projet qu’App Service doit utiliser en spécifiant le paramètre d’application PROJECT. Par exemple, exécutez la commande suivante dans le Cloud Shell :

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

Accéder aux journaux de diagnostic

ASP.NET Core fournit un module fournisseur d’informations intégré pour App Service. Dans Program.cs pour votre projet, ajoutez le fournisseur à votre application à l’aide de la méthode d’extension ConfigureLogging, comme indiqué dans l’exemple suivant :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddAzureWebAppDiagnostics();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Vous pouvez ensuite configurer et générer des journaux avec le modèle .NET Core standard.

Pour accéder aux journaux de la console générés à l’intérieur du code de votre application dans App Service, activez la journalisation des diagnostics en exécutant la commande suivante dans Cloud Shell :

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

Les valeurs possibles pour --level sont : Error, Warning, Info et Verbose. Chaque niveau suivant comprend le niveau précédent. Par exemple : Error comprend uniquement les messages d’erreur et Verbose comprend tous les messages.

Une fois la journalisation des diagnostics activée, exécutez la commande suivante pour voir le flux de journal :

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

Si vous ne voyez pas les journaux d’activité de la console, attendez 30 secondes et vérifiez à nouveau.

Notes

Vous pouvez également inspecter les fichiers journaux à partir du navigateur sur https://<app-name>.scm.azurewebsites.net/api/logs/docker.

Pour arrêter le streaming des journaux à tout moment, appuyez sur Ctrl+C.

Pour plus d’informations sur la résolution des problèmes des applications ASP.NET Core dans App Service, consultez Résolution des problèmes ASP.NET Core sur Azure App Service et IIS

Accéder à la page d’exceptions détaillées

Lorsque votre application ASP.NET Core génère une exception dans le débogueur Visual Studio, le navigateur affiche une page d’exception détaillée, mais dans App Service, cette page est remplacée par un générique HTTP 500 ou Une erreur s’est produite lors du traitement de votre demande. Pour afficher la page d’exceptions détaillées dans App Service, ajoutez le paramètre d’application ASPNETCORE_ENVIRONMENT à l’application en exécutant la commande suivante dans Cloud Shell.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings ASPNETCORE_ENVIRONMENT="Development"

Détecter une session HTTPS

Dans App Service, une terminaison TLS/SSL se produit au niveau des équilibreurs de charge réseau. Toutes les requêtes HTTPS accèdent donc à votre application en tant que requêtes HTTP non chiffrées. Si votre logique d’application doit savoir si les demandes utilisateur sont chiffrées ou non, configurez l’intergiciel Forwarded Headers dans Startup.cs :

Configurez l’intergiciel avec ForwardedHeadersOptions pour transférer les en-têtes X-Forwarded-For et X-Forwarded-Proto dans Startup.ConfigureServices.
Ajoutez des plages d’adresses IP privées aux réseaux connus afin que l’intergiciel puisse approuver l’équilibreur de charge d’App Service.
Appelez la méthode UseForwardedHeaders dans Startup.Configure avant d’appeler les autres intergiciels.

Assemblez les trois éléments ; le code ressemble à l’exemple suivant :

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    services.Configure<ForwardedHeadersOptions>(options =>
    {
        options.ForwardedHeaders =
            ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
        // These three subnets encapsulate the applicable Azure subnets. At the moment, it's not possible to narrow it down further.
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:10.0.0.0"), 104));
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:192.168.0.0"), 112));
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:172.16.0.0"), 108));
    });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseForwardedHeaders();

    ...

    app.UseMvc();
}

Pour plus d’informations, consultez l’article Configurer ASP.NET Core pour l’utilisation de serveurs proxy et d’équilibreurs de charge.

Réécrire ou rediriger l’URL

Pour réécrire ou rediriger l’URL, utilisez l’intergiciel de réécriture d’URL dans ASP.NET Core.

Ouvrir une session SSH dans un navigateur

Pour établir une session SSH directe avec votre conteneur, votre application doit être en cours d’exécution.

Collez l’URL suivante dans votre navigateur et remplacez <app-name> par le nom de votre application :

https://<app-name>.scm.azurewebsites.net/webssh/host

Si vous n’êtes pas encore authentifié, vous devez le faire avec votre abonnement Azure pour vous connecter. Une fois authentifié, vous voyez un interpréteur de commandes dans le navigateur, vous permettant d’exécuter des commandes à l’intérieur de votre conteneur.

Connexion SSH

Notes

Les modifications apportées en dehors du répertoire /home sont stockées dans le conteneur lui-même et ne sont pas conservées après le redémarrage d’une application.

Pour ouvrir une session SSH à distance à partir de votre machine locale, consultez Ouvrir une session SSH à partir d’un interpréteur de commandes à distance.

robots933456 dans les journaux

Le message suivant peut s'afficher dans les journaux du conteneur :

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Vous pouvez sans risque ignorer ce message. /robots933456.txt est un chemin d’URL factice utilisé par App Service pour vérifier si le conteneur est capable de traiter des requêtes. Une réponse 404 indique que le chemin d’accès n’existe pas, mais informe App Service que le conteneur est intègre et prêt à répondre aux requêtes.

Étapes suivantes

Tutoriel : application ASP.NET Core avec SQL Database

Questions fréquentes (FAQ) sur App Service sur Linux

Ou vous pouvez également consulter d’autres ressources :

Informations de référence sur les variables d’environnement et les paramètres d’application

Partage via

Configurer une application ASP.NET Core pour Azure App Service

Afficher les versions du runtime .NET Core prises en charge

Afficher la version de .NET Core

Définir la version de .NET Core

Personnaliser l’automatisation de la génération

Accéder aux variables d’environnement

Déployer des solutions à projets multiples

Accéder aux journaux de diagnostic

Accéder à la page d’exceptions détaillées

Détecter une session HTTPS

Réécrire ou rediriger l’URL

Ouvrir une session SSH dans un navigateur

robots933456 dans les journaux

Étapes suivantes

Commentaires

Ressources supplémentaires