Suivi dans API Web ASP.NET 2

Lorsque vous essayez de déboguer une application web, rien ne remplace un bon ensemble de journaux de trace. Ce tutoriel montre comment activer le suivi dans API Web ASP.NET. Vous pouvez utiliser cette fonctionnalité pour suivre ce que l’infrastructure d’API web fait avant et après avoir appelé votre contrôleur. Vous pouvez également l’utiliser pour suivre votre propre code.

Versions logicielles utilisées dans le tutoriel

• Visual Studio 2017 (fonctionne également avec Visual Studio 2015)
• API web 2
• Microsoft.AspNet.WebApi.Tracing

Activer le suivi System.Diagnostics dans l’API web

Tout d’abord, nous allons créer un projet d’application web ASP.NET. Dans Visual Studio, dans le menu Fichier , sélectionnez Nouveau>projet. Sous Modèles, Web, sélectionnez ASP.NET application web.

Choisissez le modèle de projet d’API web.

Dans le menu Outils , sélectionnez Gestionnaire de package NuGet, puis Console Gérer le package.

Dans la fenêtre Console du Gestionnaire de package, tapez les commandes suivantes.

Install-Package Microsoft.AspNet.WebApi.Tracing
Update-Package Microsoft.AspNet.WebApi.WebHost

La première commande installe le dernier package de suivi de l’API web. Il met également à jour les principaux packages d’API web. La deuxième commande met à jour le package WebApi.WebHost vers la dernière version.

Ouvrez le fichier WebApiConfig.cs dans le dossier App_Start. Ajoutez le code suivant à la méthode Register .

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // New code
        config.EnableSystemDiagnosticsTracing();

        // Other configuration code not shown.
    }
}

Ce code ajoute la classe SystemDiagnosticsTraceWriter au pipeline d’API web. La classe SystemDiagnosticsTraceWriter écrit des traces dans System.Diagnostics.Trace.

Pour afficher les traces, exécutez l’application dans le débogueur. Dans un navigateur, accédez à /api/values.

Les instructions de trace sont écrites dans la fenêtre Sortie dans Visual Studio. (Dans le menu Affichage , sélectionnez Sortie).

Étant donné que SystemDiagnosticsTraceWriter écrit des traces dans System.Diagnostics.Trace, vous pouvez inscrire des écouteurs de trace supplémentaires ; par exemple, pour écrire des traces dans un fichier journal. Pour plus d’informations sur les enregistreurs de traces, consultez la rubrique Écouteurs de suivi sur MSDN.

Configuration de SystemDiagnosticsTraceWriter

Le code suivant montre comment configurer l’enregistreur de trace.

SystemDiagnosticsTraceWriter traceWriter = config.EnableSystemDiagnosticsTracing();
traceWriter.IsVerbose = true;
traceWriter.MinimumLevel = TraceLevel.Debug;

Vous pouvez contrôler deux paramètres :

• IsVerbose : si la valeur est false, chaque trace contient un minimum d’informations. Si la valeur est true, les traces incluent plus d’informations.
• MinimumLevel : définit le niveau de trace minimal. Les niveaux de trace, dans l’ordre, sont Debug, Info, Warn, Error et Fatal.

Ajout de traces à votre application API web

L’ajout d’un enregistreur de suivi vous donne un accès immédiat aux traces créées par le pipeline d’API web. Vous pouvez également utiliser l’enregistreur de suivi pour suivre votre propre code :

using System.Web.Http.Tracing;

public class ProductsController : ApiController
{
    public HttpResponseMessage GetAllProducts()
    {
        Configuration.Services.GetTraceWriter().Info(
            Request, "ProductsController", "Get the list of products.");

        // ...
    }
}

Pour obtenir l’enregistreur de traces, appelez HttpConfiguration.Services.GetTraceWriter. À partir d’un contrôleur, cette méthode est accessible via la propriété ApiController.Configuration .

Pour écrire une trace, vous pouvez appeler directement la méthode ITraceWriter.Trace , mais la classe ITraceWriterExtensions définit certaines méthodes d’extension plus conviviales. Par exemple, la méthode Info indiquée ci-dessus crée une trace avec les informations de niveau de trace.

Infrastructure de suivi d’API web

Cette section explique comment écrire un enregistreur de traces personnalisé pour l’API web.

Le package Microsoft.AspNet.WebApi.Tracing s’appuie sur une infrastructure de suivi plus générale dans l’API web. Au lieu d’utiliser Microsoft.AspNet.WebApi.Tracing, vous pouvez également brancher d’autres bibliothèques de suivi/journalisation, telles que NLog ou log4net.

Pour collecter des traces, implémentez l’interface ITraceWriter . Voici un exemple simple :

public class SimpleTracer : ITraceWriter
{
    public void Trace(HttpRequestMessage request, string category, TraceLevel level, 
        Action<TraceRecord> traceAction)
    {
        TraceRecord rec = new TraceRecord(request, category, level);
        traceAction(rec);
        WriteTrace(rec);
    }

    protected void WriteTrace(TraceRecord rec)
    {
        var message = string.Format("{0};{1};{2}", 
            rec.Operator, rec.Operation, rec.Message);
        System.Diagnostics.Trace.WriteLine(message, rec.Category);
    }
}

La méthode ITraceWriter.Trace crée une trace. L’appelant spécifie une catégorie et un niveau de trace. La catégorie peut être n’importe quelle chaîne définie par l’utilisateur. Votre implémentation de Trace doit effectuer les opérations suivantes :

1. Créez un nouvel enregistrement TraceRecord. Initialisez-le avec la requête, la catégorie et le niveau de trace, comme indiqué. Ces valeurs sont fournies par l’appelant.
2. Appelez le délégué traceAction . À l’intérieur de ce délégué, l’appelant est censé remplir le reste du TraceRecord.
3. Écrivez traceRecord à l’aide de la technique de journalisation de votre choix. L’exemple présenté ici appelle simplement System.Diagnostics.Trace.

Définition de l’enregistreur de traces

Pour activer le suivi, vous devez configurer l’API web pour utiliser votre implémentation ITraceWriter . Pour ce faire, utilisez l’objet HttpConfiguration , comme indiqué dans le code suivant :

public static void Register(HttpConfiguration config)
{
    config.Services.Replace(typeof(ITraceWriter), new SimpleTracer());
}

Un seul enregistreur de traces peut être actif. Par défaut, l’API web définit un traceur « no-op » qui ne fait rien. (Le traceur « no-op » existe afin que le code de suivi n’ait pas à case activée si l’enregistreur de trace est null avant d’écrire une trace.)

Fonctionnement du suivi des API web

Le suivi dans l’API web utilise un modèle de façade : lorsque le suivi est activé, l’API web encapsule différentes parties du pipeline de requête avec des classes qui effectuent des appels de trace.

Par exemple, lors de la sélection d’un contrôleur, le pipeline utilise l’interface IHttpControllerSelector . Une fois le suivi activé, le pipeline insère une classe qui implémente IHttpControllerSelector , mais appelle à l’implémentation réelle :

Les avantages de cette conception sont les suivants :

• Si vous n’ajoutez pas d’enregistreur de suivi, les composants de suivi ne sont pas instanciés et n’ont aucun impact sur les performances.
• Si vous remplacez les services par défaut tels que IHttpControllerSelector par votre propre implémentation personnalisée, le suivi n’est pas affecté, car le suivi est effectué par l’objet wrapper.

Vous pouvez également remplacer l’ensemble de l’infrastructure de suivi de l’API web par votre propre infrastructure personnalisée, en remplaçant le service ITraceManager par défaut :

config.Services.Replace(typeof(ITraceManager), new MyTraceManager());

Implémentez ITraceManager.Initialize pour initialiser votre système de suivi. N’oubliez pas que cela remplace l’ensemble de l’infrastructure de suivi, y compris tout le code de suivi intégré à l’API web.