38.2. Configuration Schema
A configuration file, whether it is a machine.config, a web.config, or an application configuration file, needs to adhere to the configuration schema that determines which elements should be included. The schema can be found at C:Program FilesMicrosoft Visual Studio 9.0XmlSchemasDotNetConfig.xsd and is broken down into a number of sections.
38.2.1. Section: configurationSections
Configuration files can be customized to contain any structured XML data. In order to do this, you must define a custom section in the configurationSections block within the configuration file. This defines both the name of the configuration section and the class that is to be called in order to process the section.
The first configurationSections section in the machine.config file defines the handlers for each of the standard configuration sections discussed here. For example, the following code snippet defines the section handler for the ConfigurationApplication.My.MySettings configuration section, along with the corresponding section. The schema of this section must correspond to what the System.Configuration.ClientSettingsSection class expects, rather than the normal configuration file schema.
<configuration>
<configSections>
<section name="ConfigurationApplication.My.MySettings"
type="System.Configuration.ClientSettingsSection,
System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
requirePermission="false" />
</configSections>
...
<ConfigurationApplication.My.Settings>
<setting name="PrimaryServer" serializeAs="String">
<value>www.softteq.com</value>
</setting>
</ConfigurationApplication.My.Settings>
</configuration>It is also possible to include configSections in a sectionGroup element that can be used to help lay out configuration information. The previous example can be extended as follows:
<configuration>
<configSections>
<sectionGroup name="applicationSettings"
type="System.Configuration.ApplicationSettingsGroup,
System, Version=2.0.0.0, Culture=neutral, PublicKeyToken= b77a5c561934e089" >
<section name="ConfigurationApplication.My.MySettings"
type="System.Configuration.ClientSettingsSection,
System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
requirePermission="false" />
<section name="ReferencedAssembly.My.MySettings"
type="System.Configuration.ClientSettingsSection,
System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"requirePermission="false" />
</sectionGroup>
</configSections>
...
<applicationSettings>
<ConfigurationApplication.My.Settings>
<setting name="PrimaryServer" serializeAs="String">
<value>www.softteq.com</value>
</setting>
</ConfigurationApplication.My.Settings>
<ReferencedAssembly.My.Settings>
<setting name="SecondaryServer" serializeAs="String">
<value>www.peaksite.com</value>
</setting>
</ReferencedAssembly.My.Settings>
</applicationSettings>
</configuration>Where used, the configSections element must appear as the first child of the configuration element.
38.2.2. Section: startup
The startup configuration section determines the version of the framework that is either required (requiredRuntime) or supported (supportedRuntime) by the framework. By default, a .NET application will attempt to execute using the same version of the framework on which it was built. Any application being built with support for multiple versions of the framework should indicate this with the supportedRuntime element, defining the most preferred framework version first:
<configuration>
<startup>
<supportedRuntime version="v2.0.50727"/>
<supportedRuntime version="v1.1.4322"/>
</startup>
</configuration>This configuration section would be used by an application that has been tested for both version 2.0 and 1.1 of the .NET Framework. Anomalies were detected in the testing for version 1.0 of the .NET Framework, so it has been omitted from the supportedRuntime list. The version number must correspond exactly to the installation directory for that framework version (for example, version 2.0 of the .NET Framework typically installs to C:WINDOWSMicrosoft.NETFrameworkv2.0.50727).
38.2.3. Section: runtime
Garbage collection is a feature of the .NET Framework that distinguishes it from non-managed environments. The process of collecting and disposing of unreferenced objects is usually done in parallel with the main application on a separate thread. This means that the user should not see any performance issues as a result of this process being run. However, there may be circumstances when this process should be run inline with the main application. The runtime section of the configuration file can be used to provide limited control over how the .NET runtime engine operates. Among other things, you can specify whether the garbage collection should be done concurrently with the main application.
This section can also be used to specify a location in which to search for assemblies that may be required by an application. This attribute can be useful if an application references assemblies. The following code illustrates the use of the codeBase attribute to locate the ImportantAssembly.dll, as well as to dictate that garbage collection be done inline with the main application thread:
<configuration>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="ImportantAssembly"
publicKeyToken="32ab4ba45e0a69a1"
culture="neutral" />
<codeBase version="2.0.0.0" href="../ImportantAssembly.dll"/>
</dependentAssembly>
</assemblyBinding>
<gcConcurrent enabled="false"/>
</runtime>
</configuration>38.2.4. Section: system.runtime.remoting
The remoting section of the configuration file can be used to specify information about remote objects and channels required by the application. For example, the default HTTP channel can be directed to listen to port 8080 by means of the following configuration snippet:
<configuration>
<system.runtime.remoting>
<application>
<channels>
<channel port="8080" ref="http"/>
</channels>
</application>
</system.runtime.remoting>
</configuration>38.2.5. Section: system.net
Because of the current demand for more secure operating environments, organizations often use proxies to monitor and protect traffic on their networks. This can often result in applications not functioning correctly unless they have been configured to use the appropriate proxies. The networking section of the configuration files can be used to adjust the proxy that an application uses when making HTTP requests.
The .NET Framework ships with an SmtpClient class that can be used to send mail from within an application. Obviously, doing this requires information such as the server and the credentials to use when sending mail. Although such information can be hard-coded within an application, a more flexible approach would be to specify it in a configuration file that can be adjusted when the application is deployed. The following configuration snippet illustrates the use of the default proxy (although it bypasses the proxy for local addresses and the DeveloperNews web site) and specifies the default SMTP settings to be used by the SMTP client:
<configuration>
<system.net>
<defaultProxy>
<proxy usesystemdefaults="true"
proxyaddress="http://192.168.200.222:3030"
bypassonlocal="true" />
<bypasslist>
<add address="[a-z]+.developernews.com" />
</bypasslist>
</defaultProxy>
<mailSettings>
<smtp deliveryMethod="network">
<network host="smtp.developernews.com"
port="25" defaultCredentials="true" />
</smtp>
</mailSettings>
</system.net>
</configuration>38.2.6. Section: cryptographySettings
Although the .NET Framework contains base implementations for a number of cryptographic algorithms, such as the hashing function, there are times when it is necessary to override these algorithms. When this is required, the cryptographySettings section of the configuration file can be included to remap existing algorithm names, or map new names, to another implementation class.
38.2.7. Section: system.diagnostics
Debugging is always the hardest part of writing an application. It is made even more difficult when the application is in production and the error cannot be replicated in the debugging environment. One technique that is particularly important for debugging this type of error is to use trace statements:
Trace.WriteLine("The application made it this far before crashing . . .")Both trace and debug statements work very similarly to events and event handlers. For the preceding WriteLine statement to have any effect, an object must be listening for this WriteLine. This is typically done by a TraceListener class. The framework supports a number of default trace listeners that can be wired up to the application via the diagnostics section of the configuration file, as shown in the following section in which an EventLog trace listener has been attached to the application:
<configuration>
<system.diagnostics>
<trace autoflush="true" indentsize="0">
<listeners>
<add name="MyEventListener"
type="System.Diagnostics.EventLogTraceListener, system,
version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"initializeData="DeveloperApplicationEventLog"/>
</listeners>
</trace>
</system.diagnostics>
</configuration>The initializeData attribute specifies a text string to be passed into the constructor for the trace listener. In the case of the event-log listener, this text corresponds to the name of the event log into which trace statements will be inserted.
Other elements can also be added to the diagnostics section of the configuration file — for example, to determine the level of trace logging to perform, which will determine how verbose the trace messages are; or to control whether the debug assertion dialog is displayed for an application or not.
38.2.8. Section: system.web
The system.web section of the configuration file is used to control how web applications behave. This is the section that can have quite a deep hierarchy, as configuration settings can be specified on a machine, web server, web site, web application, or even sub-folder basis. Because this section controls the security requirements for a web application, it is often used to restrict access to certain areas of the web application.
38.2.9. Section: webserver
Although web service applications use several configuration settings, such as authentication and impersonation sections, the system.web section of the configuration file contains some settings that are particular to the way that web services operate. For example, the following code snippet enables the use of SOAP and Documentation protocols, but removes the POST and GET protocols for the application:
<configuration>
<system.web>
<webServices>
<protocols>
<add name="HttpSoap"/>
<remove name="HttpPost"/>
<remove name="HttpGet"/>
<add name="Documentation"/>
</protocols>
</webServices>
</system.web>
</configuration>By default, only SOAP and Documentation are enabled for web services. Quite often, for debugging purposes, it is convenient to allow the POST protocol so that the web service can be tested via a web browser. You should do this on an application basis by including the appropriate section in the configuration file within the application folder.
38.2.10. Section: compiler
The compiler section of the configuration file is used to list the compilers installed on a computer. The following snippet shows how the VB.NET compiler is referenced in the machine.config file. Within an application, this information can be accessed via the CodeDomProvider framework class.
<configuration>
<system.codedom>
<compilers>
<compiler language="vb;vbs;visualbasic;vbscript" extension=".vb"
type="Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089" />
</compilers>
</system.codedom>
</configuration>38.2.11. Configuration Attributes
All configuration elements can specify a configSource, which is simply a redirection to a separate file. This can be useful if a configuration file becomes unwieldy in length. The following code snippet illustrates how a section of a configuration file can be extracted and subsequently referenced by means of this attribute:
<!-- Original Configuration File -->
<configuration>
...
<WindowsApplication1.My.MySettings>
<setting name="Button1_Text" serializeAs="String">
<value>Press Me!</value>
</setting>
</WindowsApplication1.My.MySettings>
</configuration>
<!-- Reduced Configuration File using configSource -->
<configuration>
...
<WindowsApplication1.My.MySettings configSource="MySettings.Config" />
</configuration>
<!-- Code from MySettings.Config -->
<WindowsApplication1.My.MySettings>
<setting name="Button1_Text" serializeAs="String">
<value>Press Me!</value>
</setting>
</WindowsApplication1.My.MySettings>Note a couple of limitations to using a configSource:
There is no merging of configuration sections between the referenced file and the original configuration file. If you include the section in both files, a configuration error will be generated when you attempt to run the application.
This attribute cannot be applied to configuration section groups. This can be a significant limitation, as the purpose of a section group is to group items that relate similar configuration sections. A logical separation could see all items in a particular section group in a separate configuration file.
If the attribute is used within a web.config file, changing the referenced configuration file will not restart the ASP.NET application. In order for the configuration information to be reread, you need to either manually restart the ASP.NET application or modify the web.config file itself.
Each element within the configuration file inherits a number of attributes that can be set to control whether that element can be overridden or not. To prevent an element, or even an entire section, from being overridden, you can lock it. Five different locking attributes (outlined in the following table) can be used to specify any number of configuration attributes and elements that are to be locked.
Being able to lock configuration items is particularly relevant when you're dealing with web applications, which might contain a deep hierarchy of configuration inheritance. Windows applications inherit only from the machine.config file, so it is unlikely that you will need to lock items.
| Configuration Element | Description |
|---|---|
| LockItem | Locks the element to which this attribute is applied, including all other attributes provided on that element and all child elements |
| LockAttributes | Locks the comma-delimited list of attributes provided |
| LockAllAttributesExcept | Locks all attributes except those provided in the comma-delimited list |
| LockElements | Locks the comma-delimited list of child elements provided |
| LockAllElementsExcept | Locks all child elements except those provided in the comma-delimited list |