Using XML to build an ASP+ config.web EditorBy Adam S. Cartwright
ASP+ configuration information is stored in XML-based configuration files. Using built-in features of IIS 5.0 and IE 5.0 such as the FileSystemObject, the XML Document Object Model (DOM) and XML Data Islands, we can easily develop a rich tool for modifying and editing these configuration files. In this three part lesson we will build a web based tool for loading, modifying, and saving the ASP+ config.web configuration file.
In part one (this lesson) we will discuss the contents and structure of the config.web file, then build an ASP+ file for loading the config.web file into a client side DOM object (data island). Part two will feature data-binding the XML DOM object to client intrinsic controls, providing a rich editing environment. Finally, in part three we will post the XML data back to the server and save the new config.web file back to the ASP+ application.
Note: ASP+, config.web, and many other items in this discussion are part of Microsoft's .NET framework, which is still in development and subject to change. Information for these articles has been obtained from preliminary documentation, also subject to change, and from hands on experience working with the .NET framework SDK technology preview.
To run the samples included with this lesson you will need to install the .NET Framework Technology Preview. Visit http://msdn.microsoft.com/net/ for more information.
Welcome to config.web
ASP developers are used to using global configuration files in the form of global.asa and other home built files. ASP+ adds on to this concept of global configuration by providing a true configuration file in the config.web file. Rather than being a global event handler for handling state configuration, the config.web file is a real configuration file for storing system and application settings independent of state.
The config.web file is XML-based, which means that it inherits all of the wonderful features that are the nature of XML files, such as being human-readable and human-writeable, as well as being customizable (extensible). This feature of being extensible means that in addition to storing all of the system configuration items, you can add your own configuration criteria and settings within the configuration system.
Following is an example of a config.web file:
Notice that all configuration information must reside between the <configuration> and </configuration> tags. The file is made up of two main parts. The first part is the <configsections> section which specifies the configuration section handler declarations. The remainder of the file contains the actual configuration sections, as specified in the <configsections> part. The configuration section handler declarations specify the name of each configuration section, and the .NET assembly and class that will handle that configuration information. For Example:
The above example demonstrates the use of four configuration sections.
ASP+ Standard Section Handlers
ASP+ ships with several standard section handlers that can be used to process configuration settings within config.web files. The .NET SDK documents each of these standard section handlers in detail with sample code to demonstrate proper syntax. The following is a summary of these standard section handlers:
Custom Configuration Settings
As I stated above, it is possible to extend the configuration file with your own configuration settings. To do so, all you have to do is create your own Configuration Section Handler, which must be a class that implements the System.Web.Config.IConfigSectionHandler interface.The IConfigSectionHandler interface is defined as follows:
For more information on how to add custom configuration settings, see the .NET Framework SDK.
Accessing Configuration Settings
Accessing the configuration settings found in the config.web file is extremely simple and quite straight forward. One thing to remember is that the configuration settings are hierarchical, thus it is possible to have configuration files for specific URLs.
Accessing the configuration settings is accomplished by using the GetConfig() method exposed on the HttpContext object. For example:
The above example shows how to access configuration information for the current URL being processed. To access configuration information for a specific URL, use the following example:
Building our Editor
Now that we're squared away on the config.web file, what it is and what it looks like, let's get started building our ASP+ based editor tool. In this lesson we are only going as far as loading the config.web document into a DOM object on the client. In follow-on lessons we'll parse and modify the XML data, then return it to the server and save it.
DOM vs. File System Object vs. XmlTextReader
Our task of loading the config.web file into a client side DOM object can be solved quite simply if we were to establish an XML data island on our page and load the config.web file directly into it. However, for our tool we're going to load the file on the server side first, then send it down to the client. This will allow us to add some important server side pre-processing and post-processing to our tool.
Loading the config.web file on the server side can be accomplished several ways including using either the file system object, or the XML DOM object itself, or using the new XmlTextReader object. Each method has its own advantages. For example, we may want to include some additional information to the user of our tool such as last file save date and time. This information is easily obtainable using the file system object. On the other hand, we might be storing that information ourselves, along with versioning and other data directly in the XML file. Using the DOM in this case would likely be preferable. Then again, we might be concerned about speed and performance, and the XmlTextReader object can give us all that without the overhead of the DOM object.
Loading the XML File
To become familiar with loading the XML document on the server, let's first build a page specifically for loading XML using the XmlTextReader class. This class provides direct parsing and tokenizing of XML. The object created here is not a DOM object (we'll cover that in a minute). Instead, the XmlTextReader provides fast, stream based access to the XML data without the overhead of the DOM object.
Below is our .aspx file we'll use to test loading the config.web file and for becoming more familiar with the XmlTextReader class:
Let's quickly review what is being done here. First, we're importing the System.IO, System.Xml, and System.NewXml assemblies. We'll need these for reading the XML document and for communicating back to the user.
Next we have the Page_Load handler and the ReadConfigWebFile class. The Page_Load handler fires off the Start method of the ReadConfigWebFile class, passing to it the name of the configuration file we are going to read (in this case, config.web). Notice that the Page_Load handler is also going to write to the page the results of our loading.
The ReadConfigWebFile class is quite simple, but may look completely foreign to you if you're used to the ASP method of using the DOM. Here, in the Start method, we are using three main objects: myDocument, which is the name of the configuration file we passed in, the Console object that we pass messages to, and the XmlTextReader object used for reading the XML data.
Our "try" structure is going to attempt to open the XML document "config.web" simply by creating a new XmlTextReader object, passing into it the file path and name of our configuration file. Using the XmlTextReader object is that simple! If the load is successful, then processing continues to the "finally" struct, otherwise the "catch" struct will be processed where we will learn what the error message is.
Lastly, we'll return our message, which will be displayed on the screen.
Moving to the DOM
Now that we're using the XmlTextReader object, what if we wanted to create a DOM object out of it? Using the same example as above, let's add just a few lines to introduce DOM functionality.
The lines in red above are the only chances necessary to create a DOM object! Now that we have our DOM object, we can move on and pass it to our client side XML data-island. But first, we'll make one last modification to the page. Instead of writing out to the page as we have been, we'll change the content type of the page to "text/xml" and write the XML data directly to the response stream. This will allow us to load directly into our data island. The modified code now looks like this:
Notice the use of the System.Web.HttpResponse object above. We can simply use standard ASP Response statements to do so. In order to stay compliant we need to add the <?xml version='1.0'> tag to our XML document. That way this file can be used by more than just our editor tool.
Now, the last step is to build our HTML file with the XML Data Island to load into. For now we'll use a simple HTML file as such:
Here our XML Data Island is identified using the <xml id="mydata" src=",,,"></xml> structure. Notice how the source is pointing to our previous example "sample3.aspx". You can see how flexible this method is since we can dynamically build the XML on the server and load it into a client side DOM object. By clicking on the button the content of the Data Island is shown so that we can verify that we have successfully loaded the XML. Now we're ready to build our editing tool that will allow us to modify the XML document and save it back to the server.
Today we've examined the ASP+ config.web file and learned about it's capabilities. We then learned that using the XmlTextReader object on the server we can easily read XML documents onto the server. We also looked at how to send that XML data down to the client as XML. Using this technique we can build rich applications that build XML on the server and leverage client capabilities to handle the resulting XML data.
In our next lesson we will take our editor to the next step by creating a client side editing environment in Internet Explorer using the XML Data Island and data binding features of IE. We'll discover how to use the DOM on the client side to modify the XML data, and return the XML data back to the server.
A zip file containing the code from this article is available for download: source.zip (6 kb)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -