共用方式為

configSections 的 section 項目 (一般設定結構描述)

  • 發行項

更新：2007 年 11 月

在組態區段處理常式和組態項目之間定義關聯。

configuration 項目 (一般設定結構描述)
  configSections 項目 (一般設定結構描述)
    configSections 的 section 項目 (一般設定結構描述)
      configuration 項目 (一般設定結構描述)
        configSections 項目 (一般設定結構描述)
          configSections 的 sectionGroup 項目 (一般設定結構描述)
            configSections 的 section 項目 (一般設定結構描述)

<section 
   name="section name"
   type="configuration section handler class, assembly file name, version, culture, public key token"
   allowDefinition= "Everywhere|MachineOnly|MachineToApplication|MachineToWebRoot" 
   allowLocation="True|False" 
   restartOnExternalChanges="True|False" 
/>

屬性和項目

下列小節描述屬性、子項目和父項目。

屬性

屬性

描述

allowDefinition

選擇性的 Enum 屬性。

僅適用於 ASP.NET 應用程式。

指定可以在哪個組態檔中使用此區段。

這個屬性可能是下列依序減少範圍的各值之一 (在 ConfigurationAllowDefinition 列舉型別中定義)。

值

描述

Everywhere

如下所示，允許在任何組態檔或目錄中設定這個區段：

  • Machine.config

  • 根目錄 Web.config

  • 應用程式的 Web.config

  • 虛擬目錄

  • 應用程式中的實體子目錄

如果沒有使用 allowDefinition 屬性，就會假設為 Everywhere 值。這是預設值。

MachineToApplication

允許在下列其中一個檔案內設定這個區段：

  • Machine.config

  • 根目錄 Web.config

  • 應用程式的 Web.config

這樣便會排除應用程式中虛擬目錄或實體子目錄中的 Web.config 檔。

MachineToWebRoot

允許在下列其中一個檔案內設定這個區段：

  • Machine.config

  • 根目錄 Web.config

Machine.config 和根 Web.config 檔都位於 %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG 中。

MachineOnly

只允許在 Machine.config 檔中設定區段，該檔案位於 %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG 中。

allowExeDefinition

選擇性的 Enum 屬性。

僅適用於 .NET Framework 用戶端應用程式。

指定可以在哪個組態檔中使用此區段。

這個屬性可能是下列依序減少範圍的各值之一 (在 ConfigurationAllowExeDefinition 列舉型別中定義)。

Value

描述

MachineToApplication

允許在下列其中一個檔案內設定這個區段：

  • Machine.config

  • 應用程式組態

MachineToRoamingUser

MachineToLocalUser

MachineOnly

只允許在 Machine.config 檔中設定區段，該檔案位於 %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG 中。

allowLocation

選擇性 Boolean 屬性。

僅適用於 ASP.NET 應用程式。

指定在 location 項目內是否可以使用區段。

預設值為 True。

name

必要 String 屬性。

指定與 type 屬性指定之組態區段處理常式關聯之組態區段或項目的名稱。這也是該項目出現在組態檔中區段設定區域的名稱。

restartOnExternalChanges

選擇性 Boolean 屬性。

不適用於 ASP.NET 應用程式。

指定如果區段的組態資料發生變更，是否應該重新啟動應用程式。

type

必要 String 屬性。

指定組態區段處理常式類別的名稱，該類別處理 name 屬性中指定之區段或項目的組態設定處理。請使用下列格式：

type="Fully qualified class name, assembly file name, Version - 版本, culture, public key token"

定義必須符合組件 (Assembly) 參考。例如，如果下列程式碼範例語法中的版本號碼與組件不符合，便會發生錯誤。

type="MyConfigSectionHandler.MyHandler,MyCustomConfigurationHandler,Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"

組件檔案與定義組件檔案的 Web.config 檔，都必須位於相同的應用程式目錄。如果是根 Web.config 或 Machine.config 檔，組件檔案就必須在 %SystemRoot%\Microsoft.NET\Framework\version 中。

子項目

無。

父項目

項目

描述

configuration

指定 Common Language Runtime 和 .NET Framework 應用程式所使用之每個組態檔中需要的根項目 (Root Element)。

configSections

指定組態區段和命名空間宣告。

sectionGroup

在組態區段處理常式和組態區段之間定義關聯。

備註

section 項目會將組態區段處理常式與組態項目或區段產生關聯。這是必要的，因為 ASP.NET 並不假設組態檔中設定的處理方式，相反地，ASP.NET 會將組態資料的處理委派給組態區段處理常式。每個 section 項目都會定義組態區段或項目，以及由處理組態區段或項目之 ConfigurationSection 所衍生的關聯類別。section 項目可在 sectionGroup 項目中形成邏輯群組，以組織項目並避免命名衝突。configSections 項目中包含有 section 和 sectionGroup 項目。

預設組態

.NET Framework 組態項目的組態區段是在 Machine.config 檔中定義，由於數量繁多，無法在此一一列出。下列摘錄來自 Machine.config 檔案，會定義 system.web 區段 authentication 項目的組態區段處理常式。然後，定義 authentication 項目的組態設定。

如果組態區段處理常式與組態項目沒有關聯，ASP.NET 便會發出伺服器錯誤：「無法辨認的組態區段 element_name」。

<configuration>
    <configSections>
        <sectionGroup name="system.web" type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=%ASSEMBLY_VERSION%, Culture=neutral, PublicKeyToken=%MICROSOFT_PUBLICKEY%">
            <section name="authentication" type="System.Web.Configuration.AuthenticationSection, System.Web, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" allowDefinition="MachineToApplication" />
            <!-- Other system.web sections -->
        </sectionGroup>
        <!-- Other configuration sections -->
    </configSections>

    <system.web>
        <authentication mode="Windows">
            <forms name=".ASPXAUTH" 
                   loginUrl="login.aspx" defaultUrl="default.aspx" 
                   protection="All" 
                   timeout="30" 
                   path="/" 
                   requireSSL="False" 
                   slidingExpiration="True" 
                   cookieless="UseCookies" 
                   domain="" 
                   enableCrossAppRedirects="False">
                <credentials passwordFormat="SHA1" />
            </forms>
            <passport redirectUrl="internal" />
        </authentication>
        <!-- Other system.web elements -->
    </system.web>
    <!-- Other configuration settings -->
</configuration>

範例

下列程式碼範例示範如何定義自訂組態區段，以及如何定義該區段的設定。

<configuration>

   <configSections>
      <section name="sampleSection"
               type="System.Configuration.SingleTagSectionHandler" />
   </configSections>

   <sampleSection setting1="Value1" 
                  setting2="value two" 
                  setting3="third value" />

</configuration>

項目資訊

組態區段處理常式

不套用。

組態成員

ConfigurationSection

可設定的位置

Machine.config

根層次的 Web.config

應用程式層級的 Web.config

虛擬或實體目錄層級的 Web.config

需求

Microsoft Internet Information Services (IIS) 5.0、5.1 或 6.0

.NET Framework 1.0、1.1 或 2.0 版

Microsoft Visual Studio 2003 或 Visual Studio 2005

請參閱

概念

ASP.NET 組態檔階層架構和繼承

編輯 ASP.NET 組態檔

ASP.NET 組態案例

參考

configSections 項目 (一般設定結構描述)

configSections 的 sectionGroup 項目 (一般設定結構描述)

configSections 的 clear 項目 (一般設定結構描述)

configSections 的 remove 項目 (一般設定結構描述)

configuration 項目 (一般設定結構描述)

其他資源

一般組態設定 (ASP.NET)

ASP.NET 組態設定

ASP.NET 組態檔

管理 ASP.NET 網站

ASP.NET 組態 API