Configuration with XML-Based Files | COBOL and Visual Basic on .NET: A Guide for the Reformed Mainframe Programmer

Let's talk about using external lookup files for configuration. As you know, some of the preferred mainframe-based " name -value" configuration solutions typically involved the use of smartly named partitioned datasets (PDSs). Varying slightly from one mainframe shop to the next , the PDS files might have been referred to as parameter libraries or control libraries (or maybe even copy libraries ). When appropriate, even JCL was leveraged to provide the right level of customization and configuration.

Thinking about the mainframe CICS/online environment? In that case, the topic of configuration and external "files" might take on a different meaning. For example, it is well understood that "configuring" a CICS application involved pos sible updates to the program control table (PCT), processing program table (PPT), and file control table (FCT). Where things really got interesting was when you were given access to the CICS online configuration tools (rather than having to resort to manual batch techniques).

A privileged few were able to use the mainframe CICS online facility called Resource Definition Online (RDO). To use RDO, an authorized user would execute the CEDA CICS transaction. The results of any CEDA modifications would be stored in the CICS System Definition (CSD) file. Then this CSD file would be used to apply updates to the PCT, PPT, and FCT. The point being, even CICS made use of external files in typical configuration scenarios.

Hard Coding

While you were developing on the mainframe, did you ever get into trouble for hard-coding parameter or control type information into your actual code module? Perhaps you received a gentle reprimand on the condition that you promised to never hard-code again, to instead use external lookup files. Once was enough, right? Unfortunately, it is not until some programmers get burned that they truly learn the lesson. The school of hard knocks can be an effective teacher, especially if you get fired in the process.

In this section, I introduce the collection of external files used in .NET appli cation configuration scenarios. Collectively, I refer to them as the XML-based configuration files. They are recognized as ending with the suffix of .config. The default config files for .NET are as follows :

Web.config: This file is located in your ASP.NET application virtual directory. If you use subfolders in your Web application, you can use an additional Web.config file in each folder.
App.config: ^[1] Commonly referred to as the application configuration file, App.config is located in your application directory/folder. You will typically need to manually add the App.config file into your .NET Windows application folder.

Machine.config: The location of this file depends on your runtime installation path and the version of the .NET runtime. On a Windows XP platform, using version 1 of the .NET runtime, the location will typically be C:\WINNT\Microsoft.NET\Framework\v1.0.3705\CONFIG.

Note	There are other config files: Security.config, Enterprisesec.config, Web_hightrust.config, Web_lowtrust.config, and Web_notrust.config. I defer discussion of these other config files until the section "Configuring for Code Access Security" later in this chapter.

The first config file in the preceding list, Web.config, should look familiar to you. In Chapter 15 in the section "A Configuration Primer," I discussed using this file as part of your ASP.NET session-state configuration. I discussed Web.config again later in Chapter 15 in the section "To Be a Cookieless Session or Not to Be a Cookieless Session." In the latter section, I explored the need to use this configu ration file for session state configuration.

If that were not enough, I referred to the Web.config file a third and fourth time in Chapter 15 in the section "In-Process vs. Out-of-Process Session State" and in a Tip about the ASP.NET trace feature (located at the end of the chapter), respec tively. More recently, in Chapter 17 I discussed a "deployment" concern of the config files.

In short, you've heard of the config files before, especially the Web.config file. Are you ready to drill down much deeper? That's great! Let's proceed.

Cross-Reference

I discuss the Security.config and Enterprisesec.config files in the section "Configuring for Code Access Security" later in this chapter.

The XML Schema for the Configuration File

On a couple of occasions, you may have noticed my use of the descriptive phrase "XML-based configuration files." Please make a note of this. The point that I want to get across is that you really should have XML on your mind (well- formed , case- sensitive XML at that) before you even think about modifying any of the config files. Taking the Web.config, App.config, or Machine.config as an example, you will notice the following required XML line at the very top of each file:

 <?xml version="1.0" encoding="utf-8" ?>

Following this line, you will see the root element Configuration followed by other XML child elements. The very last line in each config file is the closing XML tag for the root Configuration element. Therefore, the following two lines of XML should be considered the minimum for any config file:

 <configuration> </configuration>

The question then becomes "What do you put in between these two XML tags?" Good question. The quick and easy answer is "You put XML child elements using well-formed XML in between the root Configuration element XML tags." Now for the realistic answer: "Depending on your configuration needs and depending on which configuration file you are using, you would select from the list of available child elements."

As for the "well-formed XML" part, I did a search in Microsoft's Visual Studio .NET documentation tool ( ms-help://MS.VSCC/MS.MSDNVS/cpguide/html/ cpconformatofconfigurationfiles.htm ) and found the matter was documented quite nicely (see Figure 18-6).

Figure 18-6: Example topic found in Microsoft's Visual Studio .NET documentation tool

Almost all of your .NET application configuration concerns will involve choosing either or both of the following two child elements (to use in between the root Configuration element XML tags):

ASP.NET: <system.web></system.web>
Application settings: <appSettings></appSettings>

Pertaining mostly to the Machine.config file are seven ^[2] other basic child elements, of which you can use one or more (in between the root Configuration element XML tags):

Startup: <startup></startup>
Runtime: <runtime></runtime>
Remoting: <system.runtime.remoting></system.runtime.remoting> ^[3]
Network: <system.net></system.net>
Cryptography: <cryptographySettings></cryptographySettings> ^[4]
Configuration sections: <configSections></configSections>
Tracing and debugging: <system.diagnostics></system.diagnostics>

For now you'll focus mainly on the first two child elements listed previously: <system.web></system.web> and <appSettings></appSettings>. In the next section you'll take a closer look at the <system.web></system.web> child element.

Understanding <system.web></system.web>

You can use the <system.web></system.web> child element in either the Web.config or Machine.config file. However, you will do almost all of your editing for this child element in the Web.config file. The settings performed in the Web.config will override, per application, the settings (if any) found in the Machine.config file. The <system.web></system.web> child element only applies to ASP.NET Web applications (i.e., it is used in either the Web.config or Machine.config file).

Listing 18-11 shows the grouping of XML child elements (children of the <system.web></system.web> element) available for the element <system.web> </system.web>. Several dozen child elements are available for the <system.web></system.web> element. I have intentionally omitted a few child elements from the listing. An example of one that I omitted from the listing is the <webControls></webControls> child element, which happens to control the default client script location (aspnet_client) for several of Microsoft's Web Forms controls. As your needs dictate , consider carefully browsing your Machine.config file to discover the complete list of <system.web></system.web> child elements.

Listing 18-11: Child Elements Available for <system.web></system.web>

 <system.web>     <authentication></authentication>     <authorization></authorization>     <browserCaps></browserCaps>     <clientTarget></clientTarget>     <compilation></compilation>     <customErrors></customErrors>     <globalization></globalization>     <httpHandlers></httpHandlers>     <httpModules></httpModules>     <httpRuntime></httpRuntime>     <identity></identity>     <iisFilter></iisFilter>     <machineKey></machineKey>     <pages></pages>     <processModel></processModel>     <securityPolicy></securityPolicy> <serviceDescriptionFormatExtensionTypes></serviceDescriptionFormatExtensionTypes>     <sessionState></sessionState>     <trace></trace>     <trust></trust>     <webServices></webServices> </system.web>

In reference to Listing 18-11, you will also noticeYou will notice that the <sessionState></sessionState> child element appears in Listing 18-11 (fourth from the bottom). Less than a third of the available child ele ments are included in the Web.config by default. As your needs dictate, you can easily add those that remain .

the <trace></trace> child element (third from the bottom). I have a few points to mention about that par ticular child element:

Become familiar with the <trace></trace> child element. Once you enable a Trace.axd file, you can view it from your Web browser. This file contains lots of useful information for when you need to optimize or debug your application.
Avoid confusing the <trace></trace> child element that is a child element of <system.web> with the other <trace></trace> child element that is a child element of <system.diagnostics> . Unfortunately, they have the same name but totally different uses.
You can also control tracing with the @ Page directive at the ASP.NET page level.

The next step for any child element is to find out what attributes (or other child elements) are available for use. For example, you saw the attribute listing for the <sessionState></sessionState> child element earlier in Chapter 15 in the section "A Configuration Primer." As shown here, you basically have five attributes (one required and four optional) to choose from for the <sessionState> </sessionState> child element (mode is a required attribute):

 <sessionState mode="OffInprocStateServerSQLServer"               cookieless="truefalse"               timeout="number of minutes"               stateConnectionString="tcpip=server:port"               sqlConnectionString="sql connection string" />

The attributes available for the <trace></trace> child element are as follows:

 <system.web>   <trace enabled="falsetrue"          pageOutput="falsetrue"          requestLimit="number of trace requests"          traceMode="SortByTimeSortByCategory"          localOnly="falsetrue"/>  </system.web>

You had already seen the Web.config file and <sessionState></sessionState> child element in earlier chapters. Nevertheless, I do believe that by presenting it here in the context of the configuration discussion, you will gain a more complete understanding. You can now continue to use the <sessionState></sessionState> child element and other <system.web></system.web> child elements for your ASP.NET configuration needs.

Note

If you update a Web.config file while an application is executing, the CLR will recognize this change and trigger the application to recompile/reload. This "feature" is generally looked at as being a good thing. However, be aware that an application recompile/reload may introduce state management concerns.

On that note, let's shift focus toward one of the child elements of the root Configuration element: the <appSettings></appSettings> child element.

Understanding <appSettings></appSettings>

This is one of my favorite configuration child elements. As its name implies, you should use the <appSettings></appSettings> child element for application-level settings. In other words, in most of the instances where you might be so inclined to include hard-coded "settings" in your code modules, you would use this <appSettings></appSettings> child element instead.

The preferred use of the <appSettings></appSettings> child element applies to each of the occasions when I hard-coded ^[5] configuration information in pre vious sample code demonstrations , as shown in Table 18-1.

Table 18-1: Code Samples in Previous Chapters with Hard-Coded Configuration Information
CHAPTER	DESCRIPTION
Chapter 10	The names of the output .txt files were hard-coded.
Chapter 11	The database connection string was hard-coded.
Chapter 12	The names of the output .xml files were hard-coded.
Chapter 13	The HREF value (Web site URL) was hard-coded.
Chapter 14	The database connection string was hard-coded.
Chapter 15	No hard-coding, but state management was used.
Chapter 16	The exported Crystal Reports file names were hard-coded.
Chapter 17	No hard-coding, but an IIS virtual directory was created.

Yes, in each of the previous cases where the configuration settings were hard- coded, an alternative approach (i.e., using <appSettings></appSettings>) might have worked better. ^[6] Now, why do I mention Chapters 15 and 17?

In Chapter 15, as you know, I discussed state and cache management. You will often find state and cache management used in conjunction with configu ration settings. For example, after you retrieve a specific setting from the <appSettings></appSettings> child element, you can store the value using state and cache management. You may find it appropriate, then, to store your database connection string using an application state technique.

In Chapter 17, you learned how to manually create an IIS virtual directory. Now it is fair to reemphasize one of the typical uses of virtual directories. In most cases, when you need to output files (as you did in Chapter 16 with the Crystal Reports file export logic), you would use a virtual directory as a target location, in which case you could retrieve the virtual directory name (or physical directory name) from the <appSettings></appSettings> child element. This enables you to properly configure your application.

You can use ^[7] the <appSettings></appSettings> child element in the Web.config file (for ASP.NET applications), the App.config file (for .NET Windows applications), and the Machine.config file (for machine-level impact). The <appSettings></appSettings> child element has a rather simple schematic, as shown in Listing 18-12. I have included the <configuration> and <system.web> elements to provide clarifying context. The <system.web> element would not apply for Windows (non-Web) applications.

Listing 18-12: The XML Schema for <appSettings></appSettings>

 <?xml version="1.0" encoding="utf-8" ?> <configuration>       <appSettings>          <add key="key" value="value"/>          <remove key="predefined setting key"/>          <clear/>       </appSettings>         <system.web>         . . .         </system.web> </configuration>

Note

You can easily define other <appSettings>-type elements using other names. For example, if you want to have an element called databaseSettings to use in your config files, you can. To do this, you need to first edit the Machine.config file by adding an appropriate <section> entry in the <configSections> element. Optionally, you could modify the element entry that already exists for <appSettings> in the Machine.config file to have a name more to your liking. I find that the predefined <appSettings> element with its given name is flexible enough to meet my needs. Your needs may be different. Just remember to back up your Machine.config file prior to editing it. Also, consider adding lots of comments for documentation purposes.

To further demonstrate the use of the <appSettings></appSettings> child element in a typical application configuration scenario, you will use two sample applications. The following section continues on that note.

Using <appSettings></appSettings>

The sample code I use to demonstrate the use of the <appSettings></appSettings> child element is taken mostly from the code originally used in Chapter 14's sample applications. In other words, the original sample applications MyInformativeWinFormCobol and MyInformativeWinFormVB have been mod ified for this chapter to become My Enhanced InformativeWinFormCobol and My Enhanced InformativeWinFormVB.

For each sample application, the goal is to add the desired database con nection string configuration into an external XML-based configuration file. Subsequently, the original hard-coded configuration coding will be replaced . For the "modified" VB .NET sample application, an application configuration file (App.config) was added to the project folder (right-click the project file in the Solution Explorer window and select Add Add New Item), as shown in Figure 18-7.

Figure 18-7: The VS .NET Add New Item window to add an application configuration file to a VB .NET Windows application

The following code snippet reflects the code used for the VB .NET sample application, using the App.config file:

 <?xml version="1.0" encoding="utf-8" ?> <configuration>     <appSettings>       <add key="MyVBConnectionString"        value="user id=sa;pwd=;Database=northwind;Server=(LOCAL)" />     </appSettings> </configuration>

For the "modified" COBOL .NET sample application, I reluctantly chose to use the Machine.config file (see Figure 18-8). It appears that Fujitsu's NetCOBOL for .NET product does not support the VS .NET application configuration file Add New Item feature. ^[8]

Figure 18-8: Preparing to edit the Machine.config file after making the suggested backup

The following code snippet reflects the code used for the COBOL .NET sample application, using the Machine.config file (additional child elements are shown to provide context):

 <?xml version="1.0" encoding="utf-8" ?> <configuration>     <configSections>     . . .     </configSections>     . . .     <appSettings>       <add key="MyCOBOLConnectionString"        value="user id=sa;pwd=;Database=northwind;Server=(LOCAL)" />     </appSettings>     . . .     <system.diagnostics>     . . .     </system.diagnostics>     . . . </configuration>

Now all that is left to do is implement the appropriate logic to retrieve the con figuration settings from the respective config file. To accomplish that, you will need to enhance each sample application with additional code. The discussion in the section "Configuration with Configuration Namespaces" introduces the needed support provided by the .NET Framework configuration namespaces.

The Assembly Resource File: Another XML Configuration File

You may have noticed a file with the .resx extension lingering around in your application folder. As it turns out, you have another set of external XML configuration-type files other than the config files. Allow me to introduce you to the XML-based assembly resource file. The .resx file is automatically created by VS .NET for Windows applications and ASP.NET applications. You use the .resx file to configure applications as per globalization and localization requirements (e.g., culture, currency, and so forth).

Commonly referred to as a resource file, the .resx file is easily confused with the CLR binary resource file, which has the . resource extension. The .resx file is an XML- based file that has a predefined XML Schema.

The command-line tool Resource File Generator (Resgen.exe) is available to convert .resx resource files from their text/readable XML format to the binary .resources format. The binary .resources file can then be embedded/compiled into an executable/assembly. A second tool, the Windows Forms Resource Editor (Winres.exe), is available for those who want to edit a .resx or .resource file outside of the VS .NET environment.

The System.Resources namespace is provided to support the programmatic use of the resource files. The ResourceManager class (from the System.Resources namespace) enables reading and writing of resources associated with the assembly. Additionally, the System.Globalization namespace is available to assist you with your globalization (and localization) configuration needs.

^[1] Microsoft's documentation mentions a naming convention of ApplicationName.exe.config for the Windows application configuration file. The config file that matches that naming convention is automatically created for you. You actually create the App.config file. When you "build" your solution/project, the App.config file is copied to the \bin folder with the name of ApplicationName.exe.config. You then continue to edit the App.config file that remains in the application folder. This automatic copying scenario repeats with subsequent builds.

^[2] You could have more or fewer "other" basic child elements. This is controlled in your Machine.config file in the <configSections> </configSections> XML element.

^[3] Chapter 20 covers the <system.runtime.remoting></system.runtime.remoting> XML child element.

^[4] This element is a child element of <mscorlib></mscorlib>.

^[5] Yes, I did, but let that be our little secret. Go ahead, call me a hypocrite.

^[6] Previous to .NET, the use of the Windows registry was more commonplace as an alternative to hard coding configuration settings. Though it is still possible to use the Windows registry, the use of XML-based configuration files is quickly becoming the preferred approach.

^[7] According to Microsoft's documentation, the <appSettings> child element can be used in "Web.config files that are not at the application directory level". I did not find this restriction to be true. My use of the <appSettings> child element has worked well, even with the Web.config file being located in its default application directory level location.

^[8] The Fujitsu tech support team promptly responded regarding my inquiry into this matter. According to that communication, they too feel that "application-specific" configuration changes belong in an application configuration file, not in the Machine.config file. In fact, after I mentioned to them that the VS .NET Application Configuration File Add New Item feature was not available, they suggested an alternative approach to creating the App.config XML file: Use the VS .NET Dynamic Properties feature. I followed their suggestion and it worked perfectly . I tried it out by first selecting the Windows Form in Design view and viewing the properties of the Form by pressing F4. Then, I selected Dynamic Properties and selected one or more of the dynamic properties. After I clicked OK, the App.config file was created and appeared in the VS .NET Solution Explorer window. I could have edited the App.config XML file directly to add additional configuration settings. With this alternative approach suggested by the Fujitsu tech support team, I hardly had the heart to further harass them about improving their Help text to more clearly instruct developers with regard to the use of configuration files. At any rate, for sake of the demonstration here, I chose to leave the Machine.config update in for the sample application. This way, you will see how not to do application-specific configuration (while still using one of the XML configuration files).