mcs/class/referencesource/System/sys/system/configuration/IConfigurationSectionHandler.cs

   1 //------------------------------------------------------------------------------
   2 // <copyright file="IConfigurationSectionHandler.cs" company="Microsoft">
   3 //     Copyright (c) Microsoft Corporation.  All rights reserved.
   4 // </copyright>
   5 //------------------------------------------------------------------------------
   6
   7 namespace System.Configuration {
   8
   9     // The IConfigSectionHandler interface defines the contract that all configuration
  10     // section handlers must implement in order to participate in the resolution of
  11     // configuration settings.
  12     //
  13     // Composes and creates config objects.
  14     //
  15     // This interface is implemented by config providers.
  16     // Classes implementing IConfigSectionHandler define the rules for cooking
  17     // XML config into usable objects. The cooked objects
  18     // can be of arbitrary type.
  19     //
  20     // Configuration is composable (e.g., config in a child
  21     // directory is layered over config in a parent directory),
  22     // so, IConfigSectionHandler is supplied with the parent config
  23     // as well as any number of XML fragments.
  24     public interface IConfigurationSectionHandler {
  25
  26         // Create
  27         //
  28         // @param parent the object inherited from parent path
  29         // @param context reserved, in ASP.NET used to convey virtual path of config being evaluated
  30         // @param section the xml node rooted at the section to handle
  31         // @returns a new config object
  32         //
  33         // The function is responsible for inspecting "section", "context",
  34         // and "parent", and creating a config object.
  35         //
  36         // Note that "parent" is guaranteed to be an object that
  37         // was returned from a Create call on the same IConfigSectionHandler
  38         // implementation. (E.g., if Create returns a Hashtable,
  39         // then "parent" is always a Hashtable if it's non-null.)
  40         //
  41         // Returned objects must be immutable. In particular,
  42         // it's important that the "parent" object being passed
  43         // in is not altered: if a modification must be made,
  44         // then it must be cloned before it is modified.
  45         object Create(Object parent, Object configContext, System.Xml.XmlNode section);
  46
  47     }
  48 }