網站 < customFields 記錄檔中的自訂欄位>

發行項
07/19/2023

概觀

元素 <customFields> 的 <logFile> 元素會指定 W3C 記錄檔中自訂欄位集合的組態設定。

除了標準記錄集之外，IIS 8.5 還可讓您記錄自訂欄位。這些自訂欄位可以包含來自要求標頭、回應標頭或伺服器變數的資料。若要記錄這些欄位，您可以直接設定組態屬性，而不是建立自訂記錄模組。此功能僅適用于網站層級。記錄檔格式必須是 W3C，才能新增自訂欄位。

將自訂欄位新增至標準集合時，「_x」會附加至檔案名，以顯示記錄檔包含自訂欄位。自訂欄位中新增的資料總數不能超過 65，536 個位元組。如果自訂記錄的資料超過該數量，IIS 將會截斷資料。任何一個自訂欄位中可新增至記錄檔的資料量上限，都是由 maxCustomFieldLength 屬性指定。

若要設定自訂欄位，請指定功能變數名稱、來源名稱和來源類型。您可以將自訂資訊放入伺服器變數中，並記錄伺服器變數。選取來源類型之後，您可以選取現有的來源名稱或輸入新的來源名稱。

自訂欄位可讓您收集程式的相關實用資料，並將其匯總至 IIS 記錄。在包含負載平衡器的系統中，您可能會在記錄中看到負載平衡器的 IP 位址，但您可以在自訂欄位中記錄 X-Forwarded-For 標頭，以便知道原始要求者。您可以記錄進程執行時間，以查看進程在當天重新開機的次數。如果記憶體過度使用，您可以判斷它開始耗用記憶體的時間、要求的頁面，以及用戶端的識別碼 (當用戶端執行惡意) 時特別有用。

相容性

版本	備註
IIS 10.0	在 `<customFields>` IIS 10.0 中未修改專案。
IIS 8.5	專案 `<customFields>` 是在 IIS 8.5 中引進。
IIS 8.0	N/A
IIS 7.5	N/A
IIS 7.0	N/A
IIS 6.0	N/A

安裝程式

專案 <customFields> 包含在 IIS 8.5 和更新版本的預設安裝中。

作法

如何新增自訂欄位

(IIS) 管理員開啟 Internet Information Services：
- 如果您使用 Windows Server 2012 R2：
  - 在工作列上，依序按一下 [伺服器管理員]、[工具]，然後按一下 [Internet Information Services] ([IIS) 管理員]。
- 如果您使用 Windows 8.1：
  - 按住Windows鍵，按字母X，然後按一下[主控台]。
  - 按一下 [ 系統管理工具]，然後按兩下 [Internet Information Services] ([IIS) 管理員]。
在 [ 連線 ] 窗格中，展開伺服器、展開 [站台]，然後選取月臺。
按兩下 [記錄]。
在 [ 記錄 ] 首頁的 [ 格式] 中，選取 [W3C]。
按一下 [選取欄位]。
在 [ W3C 記錄欄位] 對話方塊中，按一下 [ 新增欄位]。
在 [ 新增自訂欄位 ] 對話方塊中，在 [ 功能變數名稱] 中輸入名稱，然後針對 [來源類型]： [要求標頭]、 [回應標頭] 或 [伺服器變數] 選取下列其中一項。
在 [來源] 中，從清單中選取來源，或輸入自訂來源的名稱。
按一下 [確定]，然後按一下 [ 確定 ]。
在 [ 動作 ] 窗格中，按一下 [ 套用]。

如何設定自訂欄位長度上限

(IIS) 管理員開啟 Internet Information Services：
- 如果您使用 Windows Server 2012 R2：
  - 在工作列上，依序按一下 [伺服器管理員]、[工具]，然後按一下 [Internet Information Services] ([IIS) 管理員]。
- 如果您使用 Windows 8.1：
  - 按住Windows鍵，按字母X，然後按一下[主控台]。
  - 按一下 [ 系統管理工具]，然後按兩下 [Internet Information Services] ([IIS) 管理員]。
在 [ 連線 ] 窗格中，選取伺服器，然後在 [管理 ] 區域中按兩下 [ 組態編輯器]。
在 [ 組態編輯器] 的區段中，選取 system.applicationHost，然後選取 [月臺]。
按一下 [ (集合]) ，然後按一下省略號。
選取網站、依 序展開 logFile、 customFields，然後按一下 maxCustomFieldLength。
針對 maxCustomFieldLength，輸入可新增至任何一個自訂欄位之記錄檔的最大資料量，以位元組為單位。
關閉 [集合編輯器]，然後在 [ 動作 ] 窗格中，按一下 [ 套用]。

組態

專案 <customFields> 是在月臺層級設定。

屬性

屬性	描述
`maxCustomFieldLength`	選擇性 uint 屬性。可以新增至任何一個自訂欄位中記錄檔的最大資料量，以位元組為單位。範圍是 2 到 65，536。預設值是 `4096`。

子元素

元素	描述
`add`	選擇性項目。指定新增至 W3C 記錄檔之自訂欄位的組態設定。

組態範例

下列組態範例會使用 customFields 元素及其 add 子項目來指定預設網站的記錄自訂欄位設定。

<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>

範例程式碼

下列範例會為網站的 W3C 記錄設定自訂欄位。

AppCmd.exe

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

注意

當您使用AppCmd.exe設定這些設定時，請務必將認可參數 apphost 設定為。這會將組態設定認可至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'}

共用方式為