Écriture de messages de trace

Article
04/11/2008

ASP.NET inclut un objet Trace (similaire aux objets Response, Request et Context) vous permettant d'écrire des instructions de débogage qui apparaissent lorsque vous activez le traçage pour une page ou pour l'application entière.

ASP.NET utilise la classe TraceContext pour stocker les informations concernant une demande, sa hiérarchie des contrôles et les informations de traçage. Les informations de traçage comprennent certaines des étapes du cycle de vie d'une demande de page et les instructions personnalisées que vous choisissez d'y inclure. La classe TraceContext est disponible pour les pages Web Forms par l'intermédiaire de la propriété Page.Trace. Lorsque vous créez des contrôles de serveur ASP.NET personnalisés en étendant la classe Control, vous pouvez accéder à la classe TraceContext par l'intermédiaire de la propriété Control.Context à l'aide de la syntaxe Control.Context.Trace. Toutefois, si vous souhaitez inclure des instructions trace provenant de fichiers autres qu'une page ou un contrôle, par exemple du fichier Global.asax de votre application ou d'une classe qui étend l'interface IHttpHandler, vous devez utiliser la propriété HttpContext.Current pour accéder à la classe TraceContext. Dans ce cas, utilisez la syntaxe HttpContext.Current.Trace.

La classe TraceContext fournit deux méthodes, Write et Warn, qui vous permettent d'écrire des instructions dans le journal des traces. Chaque méthode est surchargée et vous permet de spécifier une catégorie de traçage, un message texte et des informations d'erreur facultatives. La seule différence entre ces méthodes est que Warn affiche son texte en rouge.

Remarque Lorsque vous spécifiez une catégorie dans un appel à la méthode Write ou Warn, vous pouvez utiliser cette catégorie pour trier les instructions trace. Pour plus d'informations, consultez Activation du traçage pour une page et Activation du traçage au niveau de l'application.

Chacune de ces méthodes est surchargée et a trois versions. Si vous n'incluez qu'un argument string lorsque vous appelez Warn ou Write, ASP.NET traite cela comme un message. Si vous incluez deux arguments, le premier est traité comme une catégorie que vous pouvez utiliser pour trier l'emplacement où vos messages apparaissent dans la table Informations de traçage affichée lorsque le traçage est activé. Le troisième argument est du type Exception et contient des informations d'erreur pour la demande, s'il en existe.

Ces instructions trace et le reste des informations de traçage sont affichés dans un navigateur demandeur lorsque vous activez le traçage pour la page ou pour l'application entière.

Remarque sur la sécurité Lorsque le traçage est activé pour une page, les informations de traçage sont affichées sur n'importe quel navigateur faisant une demande pour la page du serveur. Le traçage affiche des informations sensibles telles que les valeurs de variables serveur et peut par conséquent constituer une menace pour la sécurité. Assurez-vous de désactiver le traçage de la page avant de porter votre application vers un serveur de production. Pour ce faire, affectez la valeur false à l'attribut Trace ou supprimez totalement ce dernier.

La capture d'écran suivante illustre les instructions trace personnalisées, rendues à la table Informations de traçage, lorsque le traçage est activé pour une page. La méthode Warn est utilisée pour générer le premier message en texte rouge, avec une catégorie Render et un message Text is about to render!. La méthode Write est utilisée pour générer le second message personnalisé avec la même catégorie, mais avec un message Text finished rendering!.

Instructions trace dans une page

Pour écrire des messages de trace personnalisés dans le journal des traces à partir d'une page

Dans le bloc de déclaration de code ou la classe code-behind de votre page, appelez l'une des méthodes TraceContext, à l'aide de la propriété Trace.
Spécifiez le paramètre category facultatif pour votre instruction trace. Vous pouvez utiliser cette catégorie pour trier les instructions trace lorsqu'elles sont affichées.
Spécifiez le paramètre message pour votre instruction trace. Il peut s'agir d'une chaîne ou d'une méthode.
Spécifiez le paramètre errorInfo facultatif qui contient les informations relatives aux erreurs éventuelles de la page.

L'exemple suivant de la méthode TraceContext.Warn définit une catégorie Render et un message de trace Text is about to render.
```
Trace.Warn("Render", "Text is about to render.");
[Visual Basic]
Trace.Warn("Render", "Text is about to render.")
```

Pour écrire un message de trace personnalisé dans le journal des traces à partir d'un contrôle serveur personnalisé

Dans le code de votre contrôle serveur, appelez l'une des méthodes TraceContext à l'aide de la propriété Context.
Spécifiez le paramètre category facultatif pour votre instruction trace. Vous pouvez utiliser cette catégorie pour trier les instructions trace lorsqu'elles sont affichées.
Spécifiez le paramètre message pour votre instruction trace.
Spécifiez le paramètre errorInfo facultatif qui contient les informations relatives aux erreurs éventuelles de la page.

L'exemple suivant utilise la méthode TraceContext.Write pour écrire des instructions personnalisées dans le journal des traces d'un contrôle serveur. La catégorie est My Class et le message est This is a simple trace statement.
```
Context.Trace.Write("My Class","This is a sample trace statement.");
[Visual Basic]
Context.Trace.Write("My Class","This is a sample trace statement.")
```

Dans certaines circonstances, vous souhaitez passer des instructions aux méthodes Write ou Warn uniquement lorsque le traçage est activé. L'objet TraceContext a une propriété Boolean, IsEnabled, qui vous permet d'appeler ces méthodes de manière conditionnelle.

Pour écrire des messages de trace dans le journal uniquement lorsque le traçage est activé

Créez une instruction If qui vérifie si le traçage est activé pour la page ou l'application à laquelle votre code appartient, puis une instruction conditionnelle à exécuter lorsque la propriété Trace.IsEnabled retourne la valeur true.

L'exemple suivant confirme que le traçage est activé pour une page, puis utilise la méthode Write pour écrire un nombre sélectionné de livres de la base de données dans la table Informations de traçage.
```
If (Trace.IsEnabled) {
    For (int i=0; i<ds.Tables["Books"].Rows.Count; i++) {
         Trace.Write("Prod",ds.Tables["Books"].Rows[i][0].ToString());
    }
}
[Visual Basic]
If Trace.IsEnabled Then
    For i=0 To ds.Tables("Books").Rows.Count-1
        Trace.Write("Prod",ds.Tables("Books").Rows(i)(0).ToString())
    Next
End If
```

Voir aussi

TraceContext, classe | Fonctionnalité de traçage ASP.NET | Page, classe | HttpContext, classe | Activation du traçage au niveau de l'application

Partager via

Écriture de messages de trace

Voir aussi

Ressources supplémentaires