Campos personalizados en un archivo de registro para <customFields> de un sitio

Artículo
03/19/2024

Información general

El elemento <customFields> del elemento <logFile> especifica los valores de configuración de una colección de campos personalizados en un registro W3C.

IIS 8.5 permite registrar campos personalizados además del conjunto de registros estándar. Estos campos personalizados pueden incluir datos de encabezados de solicitud, encabezados de respuesta o variables de servidor. Para registrar estos campos, simplemente puede establecer propiedades de configuración en lugar de crear un módulo de registro personalizado. Esta característica solo está disponible en el nivel de sitio. El formato del archivo de registro debe ser W3C para agregar campos personalizados.

Cuando se ha agregado un campo personalizado al conjunto estándar, "_x" se anexará al nombre de archivo para mostrar que el archivo de registro contiene un campo personalizado. La cantidad total de datos agregados en campos personalizados no puede superar los 65 536 bytes. IIS truncará los datos si los datos registrados personalizados superan esa cantidad. El atributo maxCustomFieldLength especifica la cantidad máxima de datos que se pueden agregar a un archivo de registro en cualquier campo personalizado.

Para configurar un campo personalizado, especifique el nombre del campo, el nombre de origen y el tipo de origen. Puede colocar información personalizada en una variable de servidor y registrar la variable de servidor. Una vez que haya seleccionado el tipo de origen, puede seleccionar un nombre de origen existente o escribir un nombre de origen nuevo.

Los campos personalizados permiten recopilar datos útiles sobre el proceso y agregarlos a los registros de IIS. En un sistema que contiene un equilibrador de carga, es posible que vea la dirección IP del equilibrador de carga en el registro, pero podría registrar el encabezado X-Forwarded-For en un campo personalizado, por lo que puede conocer el solicitante original. Puede registrar el tiempo de actividad del proceso para ver cuántas veces se reinició el proceso durante el día. Si la memoria comienza a usarse excesivamente, puede determinar en qué momento comenzó a consumir memoria, qué página se solicitó y cuál era el identificador del cliente (lo que sería especialmente útil si estuvieran haciendo algo malintencionado).

Compatibilidad

Versión	Notas
IIS 10.0	El elemento `<customFields>` no se modificó en IIS 10.0.
IIS 8.5	El elemento `<customFields>` se introdujo en IIS 8.5.
IIS 8.0	N/D
IIS 7.5	N/D
IIS 7.0	N/D
IIS 6,0	N/D

Configuración

El elemento <customFields> se incluye en la instalación predeterminada de IIS 8.5 y versiones posteriores.

Procedimientos

Adición de campos personalizados

Abra el Administrador de Internet Information Services (IIS):
- Si usa Windows Server 2012 R2:
  - En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
- Si usa Windows 8.1:
  - Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
  - En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
En el panel Conexiones, expanda el servidor, expanda Sitios y, a continuación, seleccione un sitio.
Haga doble clic en Registro.
En la página principal Registro, en Formato, seleccione W3C.
Haga clic en Seleccionar campos.
En el cuadro de diálogo Campos de registro de W3C, haga clic en Agregar campo....
En el cuadro de diálogo Agregar campo personalizado, escriba un nombre en Nombre de campo y seleccione uno de los siguientes para Tipo de origen: Encabezado de solicitud, Encabezado de respuesta o Variable de servidor.
En Origen, seleccione un origen de la lista o escriba el nombre de un origen personalizado.
Haga clic en Aceptar y, a continuación, haga clic en Aceptar de nuevo.
En el panel Acción, haga clic en Aplicar.

Configuración de la longitud máxima del campo personalizado

Abra el Administrador de Internet Information Services (IIS):
- Si usa Windows Server 2012 R2:
  - En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
- Si usa Windows 8.1:
  - Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
  - En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
En el panel Conexiones, seleccione el servidor y, después, en el área Administración, haga doble clic en Editor de configuración.
En el Editor de configuración, en la sección, seleccione system.applicationHost y, a continuación, seleccione sitios.
Haga clic en (Colección) y, a continuación, haga clic en los puntos suspensivos.
Seleccione el sitio, expanda logFile, expanda customFields y, a continuación, haga clic en maxCustomFieldLength.
En maxCustomFieldLength, escriba la cantidad máxima de datos que se pueden agregar a un archivo de registro en cualquier campo personalizado, en bytes.
Cierre el Editor de recopilación y, a continuación, en el panel Acción, haga clic en Aplicar.

Configuración

El elemento <customFields> se configura en el nivel de sitio.

Atributos

Atributo	Descripción
`maxCustomFieldLength`	Atributo uint opcional. Cantidad máxima de datos, en bytes, que se pueden agregar a un archivo de registro en cualquier campo personalizado. El intervalo es de 2 a 65.536. El valor predeterminado es `4096`.

Elementos secundarios

Elemento	Descripción
`add`	Elemento opcional. Especifica los valores de configuración de un campo personalizado agregado a un registro W3C.

Ejemplo de configuración

En el ejemplo de configuración siguiente se usa el elemento customFields y su elemento secundario add para especificar la configuración del campo personalizado de registro para el sitio web predeterminado.

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

Código de ejemplo

En los ejemplos siguientes se configuran campos personalizados para un registro W3C para un sitio.

AppCmd.exe

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

Nota:

Debe asegurarse de establecer el parámetro de confirmación en apphost cuando use AppCmd.exe para configurar estas opciones. Esto confirma los valores de configuración en la sección de ubicación adecuada del archivo 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'}

Compartir a través de

Campos personalizados en un archivo de registro para <customFields> de un sitio

Información general

Compatibilidad

Configuración

Procedimientos

Adición de campos personalizados

Configuración de la longitud máxima del campo personalizado

Configuración

Atributos

Elementos secundarios

Ejemplo de configuración

Código de ejemplo

AppCmd.exe

C#

VB.NET

JavaScript

VBScript

PowerShell

Comentarios

Recursos adicionales