將自訂欄位新增至網站 < 新增的記錄檔>

發行項
07/19/2023

概觀

元素 <add> 底下的 <customField> 元素會控制月臺 W3C 記錄檔之自訂欄位的組態設定。

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

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

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

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

相容性

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

安裝程式

元素 <add> 包含在 IIS 8.5 和更新版本的預設安裝中。

作法

如何新增自訂欄位

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

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

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

組態

元素 <add> 是在月臺層級設定。

屬性

屬性	描述
`logFieldName`	必要的字串屬性。指定要新增至記錄檔的自訂欄位。功能變數名稱不能包含空格。
`sourceName`	必要的字串屬性。指定 HTTP 標頭或伺服器變數的名稱，其中包含要加入至記錄檔之自訂欄位的值。名稱可以是自訂來源字串。
`sourceType`	必要的列舉屬性。要加入記錄檔中自訂欄位之資料的來源類型。可以是 RequestHeader (value = 0) 、ResponseHeader (value = 1) ，或 ServerVariable (value = 2) 。

子元素

無。

組態範例

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

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

範例程式碼

下列範例會設定月臺 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'}

共用方式為