Ajout de champs personnalisés à un fichier journal pour un site <ajouter>

Vue d’ensemble

L’élément <add> sous l’élément <customField> contrôle les paramètres de configuration d’un champ personnalisé pour un journal W3C pour un site.

IIS 8.5 vous permet de journaliser des champs personnalisés en plus de l’ensemble journalisé standard. Ces champs personnalisés peuvent inclure des données provenant d’en-têtes de requête, d’en-têtes de réponse ou de variables serveur. Pour journaliser ces champs, vous pouvez simplement définir des propriétés de configuration plutôt que de créer un module de journalisation personnalisé. Cette fonctionnalité est disponible uniquement au niveau du site. Le format du fichier journal doit être W3C pour ajouter des champs personnalisés.

Lorsqu’un champ personnalisé a été ajouté à l’ensemble standard, « _x » est ajouté au nom de fichier pour indiquer que le fichier journal contient un champ personnalisé. La quantité totale de données ajoutées dans les champs personnalisés ne peut pas dépasser 65 536 octets. IIS tronque les données si les données journalisées personnalisées dépassent cette quantité. La quantité maximale de données pouvant être ajoutées à un fichier journal dans un champ personnalisé est spécifiée par l’attribut maxCustomFieldLength.

Pour configurer un champ personnalisé, spécifiez le nom du champ, le nom de la source et le type de source. Vous pouvez placer des informations personnalisées dans une variable de serveur et consigner la variable de serveur. Une fois que vous avez sélectionné le type de source, vous pouvez sélectionner un nom source existant ou entrer un nouveau nom source.

Les champs personnalisés vous permettent de collecter des données utiles sur le processus et de les agréger aux journaux IIS. Dans un système contenant un équilibreur de charge, vous pouvez voir l’adresse IP de l’équilibreur de charge dans le journal mais vous pouvez enregistrer l’en-tête X-Forwarded-For dans un champ personnalisé afin de pouvoir connaître le demandeur d’origine. Vous pouvez enregistrer le temps de fonctionnement du processus pour voir combien de fois le processus a redémarré pendant la journée. Si la mémoire commence à être utilisée de manière excessive, vous pouvez déterminer à quel moment il a commencé à consommer de la mémoire, la page demandée et l’ID du client (ce qui est particulièrement utile si ce client fait quelque chose de malveillant).

Compatibilité

Version	Notes
IIS 10.0	L’élément <add> n’a fait l’objet d’aucune modification dans IIS 10.0.
IIS 8.5	L’élément <add> a été introduit dans IIS 8.5.
IIS 8.0	S/O
IIS 7.5	S/O
IIS 7.0	S/O
IIS 6.0	S/O

Programme d’installation

L’élément <add> est inclus dans l’installation par défaut d’IIS 8.5.

Procédure

Comment ajouter des champs personnalisés

1. Ouvrez le Gestionnaire Internet Information Services (IIS) :

   • Si vous utilisez Windows Server 2012 R2 :

     • Dans la barre des tâches, cliquez sur Gestionnaire de serveur, cliquez sur Outils, puis sur Gestionnaire Internet Information Services (IIS).

   • Si vous utilisez Windows 8.1 :

     • Maintenez la touche Windows enfoncée, appuyez sur la lettre X, puis cliquez sur Panneau de configuration.
     • Cliquez sur Outils d'administration, puis double-cliquez sur Gestionnaire des services Internet (IIS).

2. Dans le volet Connexions, développez le serveur, développez Sites puis sélectionnez un site.

3. Double-cliquez sur Journalisation.

4. Dans la page d’accueil de journalisation , pourFormat, sélectionnez W3C.

5. Cliquez sur Sélectionner des champs.

6. Dans la boîte de dialogue Champs de journalisation W3C, cliquez surAjouter un champ.

7. Dans la boîte de dialogue Ajouter un champ personnalisé, entrez un nom dans le nom du champ puis sélectionnez l’un des éléments suivants pour le type de source : en-tête de requête,en-tête de réponse ou variable serveur.

8. Dans Source, sélectionnez une source dans la liste ou entrez le nom d’une source personnalisée.

9. Cliquez sur OK puis cliquez à nouveau sur OK.

10. Dans le volet Actions, cliquez sur Appliquer.

    

Comment configurer la longueur maximale du champ personnalisé

1. Ouvrez le Gestionnaire Internet Information Services (IIS) :

   • Si vous utilisez Windows Server 2012 R2 :

     • Dans la barre des tâches, cliquez sur Gestionnaire de serveur, cliquez sur Outils, puis sur Gestionnaire Internet Information Services (IIS).

   • Si vous utilisez Windows 8.1 :

     • Maintenez la touche Windows enfoncée, appuyez sur la lettre X, puis cliquez sur Panneau de configuration.
     • Cliquez sur Outils d'administration, puis double-cliquez sur Gestionnaire des services Internet (IIS).

2. Dans le volet Connexions, sélectionnez le serveur, puis, dans la zone Gestion, double-cliquez sur Éditeur de configuration.

3. Dans l’Éditeur de configuration, pour la section, sélectionnez system.applicationHost, puis sélectionnez sites.

4. Cliquez sur (Collection)puis sur les points de suspension.

5. Sélectionnez le site, développez logFile, développez customFields puis cliquez sur maxCustomFieldLength.

6. Pour maxCustomFieldLength, entrez la quantité maximale de données en octets qui peuvent être ajoutées à un fichier journal dans n’importe quel champ personnalisé.

7. Fermez l’Éditeur de collection puis, dans le volet Action, cliquez sur Appliquer.

   

Configuration

L’élément <add> est configuré au niveau du site.

Attributs

Attribut	Description
logFieldName	Attribut de chaîne requis. Spécifie le champ personnalisé à ajouter au fichier journal. Le nom du champ ne doit pas contenir d'espaces.
sourceName	Attribut de chaîne requis. Spécifie le nom de l’en-tête HTTP ou de la variable de serveur qui contient des valeurs à ajouter à un champ personnalisé du journal. Le nom peut être une chaîne source personnalisée.
sourceType	Attribut d’énumération obligatoire. Type de source des données à ajouter à un champ personnalisé dans le journal. Peut être RequestHeader (valeur = 0), ResponseHeader (valeur = 1) ou ServerVariable (valeur = 2).

Éléments enfants

Aucune.

Exemple Configuration

L’exemple de configuration suivant utilise l’élément customFields et son élément enfant add pour spécifier les paramètres de champ personnalisé du journal pour le site web par défaut.

<sites>
    <site name="Default Web Site" id="1">
        <logFile logFormat="W3C" logTargetW3C="File, ETW">
            <customFields maxCustomFieldLength="4095">
                <clear />
                <add logFieldName="X-Forwarded-For" sourceName="X_FORWARDED_FOR" 
                    sourceType="RequestHeader" />
            </customFields>
        </logFile>
    </site>   
</sites>

Exemple de code

Les exemples suivants configurent des champs personnalisés pour un journal W3C pour un site.

AppCmd.exe

appcmd.exe set config  -section:system.applicationHost/sites /+"[name='ContosoSite'].logFile.customFields.[logFieldName='ContosoField',sourceName='ContosoSource',sourceType='ServerVariable']" /commit:apphost

Remarque

Vous devez veiller à définir le paramètre commit sur apphost quand vous utilisez AppCmd.exe pour configurer ces paramètres. Cela valide les paramètres de configuration dans la section d’emplacement appropriée dans le fichier ApplicationHost.config.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample 
{
    private static void Main() 
    {
        using(ServerManager serverManager = new ServerManager()) 
        { 
            Configuration config = serverManager.GetApplicationHostConfiguration();
            ConfigurationSection sitesSection = config.GetSection("system.applicationHost/sites");
            ConfigurationElementCollection sitesCollection = sitesSection.GetCollection();
            
            ConfigurationElement siteElement = FindElement(sitesCollection, "site", "name", @"ContosoSite");

            if (siteElement == null) throw new InvalidOperationException("Element not found!");
            
            
            ConfigurationElement logFileElement = siteElement.GetChildElement("logFile");
            ConfigurationElement customFieldsElement = logFileElement.GetChildElement("customFields");
            ConfigurationElementCollection customFieldsCollection = customFieldsElement.GetCollection();
            
            ConfigurationElement addElement = customFieldsCollection.CreateElement("add");
            addElement["logFieldName"] = @"ContosoField";
            addElement["sourceName"] = @"ContosoSource";
            addElement["sourceType"] = @"ServerVariable";
            customFieldsCollection.Add(addElement);
            
            serverManager.CommitChanges();
        }
    }

   private static ConfigurationElement FindElement(ConfigurationElementCollection collection, string elementTagName, params string[] keyValues)
   {
      foreach (ConfigurationElement element in collection)
      {
         if (String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase))
         {
            bool matches = true;
            for (int i = 0; i < keyValues.Length; i += 2)
            {
               object o = element.GetAttributeValue(keyValues[i]);
               string value = null;
               if (o != null)
               {
                  value = o.ToString();
               }
               if (!String.Equals(value, keyValues[i + 1], StringComparison.OrdinalIgnoreCase))
               {
                  matches = false;
                  break;
               }
            }
            if (matches)
            {
               return element;
            }
         }
      }
      return null;
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
     
     Sub Main()
         Dim serverManager As ServerManager = New ServerManager
         Dim config As Configuration = serverManager.GetApplicationHostConfiguration
         Dim sitesSection As ConfigurationSection = config.GetSection("system.applicationHost/sites")
         Dim sitesCollection As ConfigurationElementCollection = sitesSection.GetCollection
         Dim siteElement As ConfigurationElement = FindElement(sitesCollection, "site", "name", "ContosoSite")
         If (siteElement Is Nothing) Then
             Throw New InvalidOperationException("Element not found!")
         End If
         Dim logFileElement As ConfigurationElement = siteElement.GetChildElement("logFile")
         Dim customFieldsElement As ConfigurationElement = logFileElement.GetChildElement("customFields")
         Dim customFieldsCollection As ConfigurationElementCollection = customFieldsElement.GetCollection
         Dim addElement As ConfigurationElement = customFieldsCollection.CreateElement("add")
         addElement("logFieldName") = "ContosoField"
         addElement("sourceName") = "ContosoSource"
         addElement("sourceType") = "ServerVariable"
         customFieldsCollection.Add(addElement)
         serverManager.CommitChanges
     End Sub

   Private Function FindElement(ByVal collection As ConfigurationElementCollection, ByVal elementTagName As String, ByVal ParamArray keyValues() As String) As ConfigurationElement
      For Each element As ConfigurationElement In collection
         If String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase) Then
            Dim matches As Boolean = True
            Dim i As Integer
            For i = 0 To keyValues.Length - 1 Step 2
               Dim o As Object = element.GetAttributeValue(keyValues(i))
               Dim value As String = Nothing
               If (Not (o) Is Nothing) Then
                  value = o.ToString
               End If
               If Not String.Equals(value, keyValues((i + 1)), StringComparison.OrdinalIgnoreCase) Then
                  matches = False
                  Exit For
               End If
            Next
            If matches Then
               Return element
            End If
         End If
      Next
      Return Nothing
   End Function


End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");

var sitesCollection = sitesSection.Collection;

var siteElementPos = FindElement(sitesCollection, "site", ["name", "ContosoSite"]);
if (siteElementPos == -1) throw "Element not found!";
var siteElement = sitesCollection.Item(siteElementPos);

var logFileElement = siteElement.ChildElements.Item("logFile");
var customFieldsElement = logFileElement.ChildElements.Item("customFields");

var customFieldsCollection = customFieldsElement.Collection;

var addElement = customFieldsCollection.CreateNewElement("add");
addElement.Properties.Item("logFieldName").Value = "ContosoField";
addElement.Properties.Item("sourceName").Value = "ContosoSource";
addElement.Properties.Item("sourceType").Value = "ServerVariable";
customFieldsCollection.AddElement(addElement);


adminManager.CommitChanges();


function FindElement(collection, elementTagName, valuesToMatch) {
   for (var i = 0; i < collection.Count; i++) {
      var element = collection.Item(i);
      if (element.Name == elementTagName) {
         var matches = true;
         for (var iVal = 0; iVal < valuesToMatch.length; iVal += 2) {
            var property = element.GetPropertyByName(valuesToMatch[iVal]);
            var value = property.Value;
            if (value != null) {
               value = value.toString();
            }
            if (value != valuesToMatch[iVal + 1]) {
               matches = false;
               break;
            }
         }
         if (matches) {
            return i;
         }
      }
   }
   return -1;
}

VBScript

Set adminManager = CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")

Set sitesCollection = sitesSection.Collection

siteElementPos = FindElement(sitesCollection, "site", array ("name", "ContosoSite"))
if (siteElementPos = -1) THEN throw "Element not found!"
Set siteElement = sitesCollection.Item(siteElementPos)

Set logFileElement = siteElement.ChildElements.Item("logFile")
Set customFieldsElement = logFileElement.ChildElements.Item("customFields")

Set customFieldsCollection = customFieldsElement.Collection

Set addElement = customFieldsCollection.CreateNewElement("add")
addElement.Properties.Item("logFieldName").Value = "ContosoField"
addElement.Properties.Item("sourceName").Value = "ContosoSource"
addElement.Properties.Item("sourceType").Value = "ServerVariable"
customFieldsCollection.AddElement(addElement)


adminManager.CommitChanges()

Function FindElement(collection, elementTagName, valuesToMatch)
   For i = 0 To CInt(collection.Count) - 1
      Set element = collection.Item(i)
      If element.Name = elementTagName Then
         matches = True
         For iVal = 0 To UBound(valuesToMatch) Step 2
            Set property = element.GetPropertyByName(valuesToMatch(iVal))
            value = property.Value
            If Not IsNull(value) Then
               value = CStr(value)
            End If
            If Not value = CStr(valuesToMatch(iVal + 1)) Then
               matches = False
               Exit For
            End If
         Next
         If matches Then
            Exit For
         End If
      End If
   Next
   If matches Then
      FindElement = i
   Else
      FindElement = -1
   End If
End Function

PowerShell

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/sites/site[@name='ContosoSite']/logFile/customFields" -name "." -value @{logFieldName='ContosoField';sourceName='ContosoSource';sourceType='ServerVariable'}