The .NET Buffet

VBCommenter Source

drohrer — Sat, 22 Dec 2007 03:19:00 GMT

OK, so it's been a really long time since I've posted here. In any case, I noticed that in the very recent past several people were looking for the source to VBCommenter. As it stands, the GotDotNet site is toast, but if you look hard enough, you can still find downloads on their site for VBCommenter.

I've downloaded the 1.2.6 source code and posted it here so others can continue working on it. I'd recommend posting the code to CodePlex if there's really still a strong need for this. Given VS.NET 2005 and 2008 both support XML comments in VB.NET code, I had long ago dropped this project. I'm hopefully that posting the code will help out those who are still maintaining .Net Framework 1.0/1.1 applications in VB.NET. Go forth and code!

Doug

VBCommenter 1.2.5 FINAL released

drohrer — Thu, 17 Mar 2005 03:25:00 GMT

Anyone who is using VB.NET and wished for support for XML comment generation (NDoc, anyone?) should be using VBCommenter. As I found myself in that very situation over the last few months, I've made some fairly major improvements to the VBCommenter add-in, and have wrapped up a new release.

After struggling with IE trying to convince it to load hosted .Net controls using the 1.1 framework (I have the VS.NET 2005 beta installed and, by default, IE will use the latest runtime for hosted controls), I've managed to get the 1.2.5 VBCommenter release completed, in source control, and available. Head to the VBCommenter Workspace Home for the download. Here are the highlights between 1.2 and 1.2.5:

- Major speed improvements (mostly related to schema and XML validation handling). For example, a large project that took 14 minutes to build using 1.2 and 2 minutes without VBCommenter takes about 2.5 minutes with 1.2.5.
- Improved comment schema (includes all NDoc extensions to the XML comment schema)
- Improved XML validation and task list reporting
- Fixed defect relating to Reporting Services projects (MSDN article ID 842434) - your Intellisense will no longer go away when you build a solution with a Reporting Project in it.
- Improved interoperability with other add-ins by not forcing the IDE to shadow copy all assemblies it loaded in the add-in appdomain. This is known to resolve issues with BizTalk 2004, Borland's Together Edition for Microsoft Visual Studio .Net, and (potentially) AnkhSVN.
- <see cref=""/> will output the correct XML for the cref attribute.
- The XmlWriter.FindType method has been simplified and its speed improved dramatically, increasing the reliability and performance of the add-in.
- cref resolution is much better - If your class has a method called "Log" and you want to reference it, the generated cref will be correct instead of pointing to System.Diagnostics.Log
- Handles Enterprise Template Projects correctly
- Reads assemblies in read-only mode to avoid locking the file or the inability to load the assembly if the IDE has it locked
- Fixes issues with duplicate comment prefixes being created
- Renders variables declared as "WithEvents" as properties (which is how the WithEvents keyword is implemented in IL) to allow NDoc to find the appropriate comments for the field.

End to End EntLib Demonstration (Source and Powerpoint presentation)

drohrer — Sun, 20 Feb 2005 19:40:00 GMT

Ok, so between naps (of my 21-month-old son) and some late nights, I've managed to get the source code from my presentation last Tuesday put together. You can downoad the source and my presentation and follow the readme.txt to get set up. The source has examples of consuming all of the application blocks. It also includes an example of how to integrate ASP.NET's Forms Authentication and EntLib's Authentication/Authorization block.

The example application presented and the presentation itself were both based on (ok, mostly copied from) the earlier work of some great people at Avanade - Jeff Donahoe, Kyle Burkholder, and Ben Reierson. I'd like to thank them for their efforts to put this together - hopefully some of my additions will be useful to them as well.

Over the next few weeks, naps permitting, I'll be writing up a blog entry for each block and using this source for my explainations. But not tonight - too much time in front of the computer and not enough time spent with the family over the last week.

Feel free to post here if you have any issues or questions. I'll try my best to help out.

Doug

Another VB.NET note (The BuildRules add-in)

drohrer — Sun, 20 Feb 2005 04:09:00 GMT

On another VB.NET note, for anyone using the BuildRules tool included in the Microsoft Visual Studio .Net 2003 Automation Samples and have noticed that when you have a reporting project in your solution the BuildRules tree doesn't populate itself, the bug is essentially the same bug as the one I fixed in VBCommenter. There's a "foreach (project in solution.projects)" or some such loop in the BuildRules code, which fails somewhat silently when a reporting services project is in the solution. If you change it to an indexed loop going from 1 to the count of the Solution.Projects.Count property (yes, it really is a one-based array) and get the project using the Projects.Item(index) property, it will work again. This appears to have something to do with the COM interface to VS.NET and its implementation of the COM equivalent of IEnumerable.GetEnumerator (NewEnum? Sorry, I wasn't a COM guy before .NET) method, which fails in this case.

Specifics (DISCLAIMER: this is mostly untested code, but should work):

On line 266 of the RulesFrm.vb file, you'll find this:

266 For Each project In applicationObject.Solution.Projects

267 Dim globals As EnvDTE.Globals

268 Try

269 globals = project.Globals

270 Catch

271 globals = Nothing

272 End Try

273

274 If Not (globals Is Nothing) Then

275 projectNode = preBuildNode.Nodes.Add(project.Name)

276 projectNode.Tag = project

277 projectNode = postBuildNode.Nodes.Add(project.Name)

278 projectNode.Tag = project

279 End If

280 Next

If you change it to read:

266 For i As Integer = 1 To applicationObject.Solution.Projects.Count

267 project = applicationObject.Solution.Projects.Item(i)

268 Dim globals As EnvDTE.Globals

269 Try

270 globals = project.Globals

271 Catch

272 globals = Nothing

273 End Try

274

275 If Not (globals Is Nothing) Then

276 projectNode = preBuildNode.Nodes.Add(project.Name)

277 projectNode.Tag = project

278 projectNode = postBuildNode.Nodes.Add(project.Name)

279 projectNode.Tag = project

280 End If

281

282 Next

It should fix the issue and allow you to use the BuildRules add-in with Reporting Services projects. It seems strange, but it's true!

A new VBCommenter release for those of you using VB.NET...

drohrer — Sun, 20 Feb 2005 03:43:00 GMT

I've just posted a new release of VBCommenter on the GotDotNet workspaces. This tool has been invaluable to us on my current project, where VB.NET has been mandated but where we wanted to create our API documentation just like a C# project. However, there were several issues with the 1.2 release that caused us issues, and over the last few months I've been slowly working on cleaning them up. Major improvements over the 1.2 version include:

Improved performance - Build times on our (admitedly highly-commented) solution have gone from 14 minutes to 2 minutes with XML comment generation turned on (and about 1.5 minutes without)
Improved error handling and reporting - I've included the C# Comment Schema from Daniel Cazzulino's Blog, with a few minor modifications to make it validate fragments of XML comments. This schema is much more accurate than the original included with VBCommenter, and also helped improve performance because there are fewer XML comment errors thrown by the add-in.
Fixed a bug related to Reporting Services projects - see this Microsoft support article for more details on the problem.

There are still a few things I'd like to improve, so I've labeled this a "release candidate," but we're using it heavily on my current project and others at my client and things seem to work well so far.

Check out the VBCommenter Workspace Home for more information and the download.

And, for those of you awaiting the source code from my presentation at the Cincinnati .NET User's Group, it will be up tomorrow as promised. I'll be posting on all of the major EntLib blocks in the next few weeks, using this solution as a running example.

My EntLib presentation to the Cincinnati .Net users' group meeting is TONIGHT (2/15) at 6

drohrer — Tue, 15 Feb 2005 17:09:00 GMT

If you happen to live in the Cincinnati area and read my blog - I'm giving a presentation on Enterprise Library tonight at the Cincinnati .Net Users Group - see their site for directions. The presentation will start at 6pm and last until around 7.

I hope to see you there!

Doug

Enterprise Library Configuration (Part 2/2): Customizable configuration with framework extensions.

drohrer — Sat, 05 Feb 2005 18:57:00 GMT

In my first article on Enterprise Library configuration, I talked about how to build your own "root node" in a configuration file. We also discussed how to use the ILinkedNodeService to reference another configuration node from within your custom configuration section, and went over some details as to how the code worked in relation to the configuration manager tool. I provided a downloadable code example that I will use again in this post.

Before I get started, I wanted to point you to the tool that myself (and many others) use to get our VS.NET code into such nice HTML format - it's called CopySourceAsHtml by Colin Coller. Thanks for such a time-saving tool.

In this post, I'm going to discuss how you can create customized "providers" (the Enterprise Library term for pluggable modules that fit within the code EntLib frameworks), and how those providers can use the configuration tool to gather customizable information from the user beyond default key/value pairs you get without any additional work. We're going to build an Authorization Provider that will authorize a given request based solely on the system's pseudo-random number generator and a threshold value provided through the configuration framework.

If you open up the solution, we'll be looking at the EntLibFrameworkConfigDemo project this time. I want to start with the MyAuthenticationProvider class, which is the actual random authenticator.

MyAuthorizationProvider.cs 
    1 using System;
    2 using Microsoft.Practices.EnterpriseLibrary.Configuration;
    3 using Microsoft.Practices.EnterpriseLibrary.Security;
    4 
    5 
    6 namespace EntLibConfigDemo.ExtendingFrameworks
    7 {
    8     /// <summary>
    9     /// Summary description for MyAuthenticationProvider.
   10     /// </summary>
   11     public class MyAuthorizationProvider: ConfigurationProvider, IAuthorizationProvider
   12     {
   13 
   14         private static System.Random _rnd = new System.Random();
   15 
   16         private double threshold;
   17         private string applicationName;
   18 
   19         public MyAuthorizationProvider()
   20         {
   21             // No constructor logic needed
   22         }
   23         #region IAuthorizationProvider Members
   24 
   25         public bool Authorize(System.Security.Principal.IPrincipal principal, string context)
   26         {
   27             if (_rnd.NextDouble()>threshold) 
   28             {
   29                 return true;
   30             }
   31             return false;
   32         }
   33 
   34         #endregion
   35 
   36         #region IConfigurationProvider Members
   37 
   38         private SecurityConfigurationView securityConfigurationView;
   39 
   40         /// <summary>
   41         /// Initializes the state of the current object from
   42         /// the specified configuration data.
   43         /// </summary>
   44         /// <param name="configurationView">A <see cref="SecurityConfigurationView"></see> object</param>
   45         public override void Initialize(ConfigurationView configurationView)
   46         {
   47             // Check to make sure we have a valid configuration node before continuing
   48             if (null==configurationView) 
   49             {
   50                 throw new ArgumentNullException("configurationView cannot be null");
   51             }
   52             securityConfigurationView = configurationView as SecurityConfigurationView;
   53             if (null==securityConfigurationView) 
   54             {
   55                 throw new ArgumentException("configurationView is not of the correct type.");
   56             }
   57 
   58             // Load our authorization data and store the relevant information for later use
   59             MyAuthorizationProviderData data = securityConfigurationView.GetAuthorizationProviderData(ConfigurationName) as MyAuthorizationProviderData;
   60             if (null==data) {
   61                 throw new ArgumentException("AuthorizationProviderData is not of type MyAuthorizationProviderData");
   62             }
   63             threshold = data.AuthorizationRate;
   64             applicationName = data.Application;
   65         }
   66         #endregion
   67     }
   68 }

The IConfigurationManager interface:

What we're interested in here is the IConfigurationManager implementation, which is nothing more than the Initialize method. This method is called when the provider is first loaded, and provides the framework a way to pass configuration data to the provider. Here we check to make sure we've received the right type of configuration data and then initialize the private variables from the configuration data. Pretty simple all in all. The SecurityConfigurationView class is part of the core EntLib class library and provides several utility methods including the GetAuthorizationProviderData we use to retrieve the authorization data, which is defined in the MyAuthroizationProviderData class. Both the MyAuthorizationData and the MyAuthroizationProviderNode don't add anything new from my previous post, so I'm not going to go into detail on them here. The major difference between the two examples is in the DesignManager class, in this case MyAuthorizationProviderDesignManager class:

MyAuthorizationProviderDesignManager.cs 
    1 //===============================================================================
    2 // Microsoft patterns & practices Enterprise Library
    3 // Security Application Block
    4 //===============================================================================
    5 // Copyright © Microsoft Corporation.  All rights reserved.
    6 // THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY
    7 // OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
    8 // LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
    9 // FITNESS FOR A PARTICULAR PURPOSE.
   10 //===============================================================================
   11 
   12 using System;
   13 using System.Diagnostics;
   14 using Microsoft.Practices.EnterpriseLibrary.Configuration;
   15 using Microsoft.Practices.EnterpriseLibrary.Configuration.Design;
   16 using Microsoft.Practices.EnterpriseLibrary.Security.Configuration;
   17 
   18 namespace EntLibConfigDemo.ExtendingFrameworks
   19 {
   20     /// <summary>
   21     /// Configuration Design Manager for MyAuthorizationProvider. <seealso cref="IConfigurationDesignManager"/>.
   22     /// </summary>
   23     public class MyConfigurationDesignManager : IConfigurationDesignManager
   24     {
   25         /// <summary>
   26         /// Initializes a new instance of the <see cref="MyConfigurationDesignManager"/> class.
   27         /// </summary>
   28         public MyConfigurationDesignManager()
   29         {
   30         }
   31 
   32         /// <summary>
   33         /// <para>Registers the <see cref="MyAuthorizationProviderNode"/> in the application.</para>
   34         /// </summary>
   35         /// <param name="serviceProvider">
   36         /// <para>The a mechanism for retrieving a service object; that is, an object that provides custom support to other objects.</para>
   37         /// </param>
   38         public void Register(IServiceProvider serviceProvider)
   39         {
   40             RegisterNodeTypes(serviceProvider);
   41             RegisterXmlIncludeTypes(serviceProvider);
   42         }
   43 
   44         /// <summary>
   45         /// <para>Opens the configuration settings and registers them with the application.</para>
   46         /// </summary>
   47         /// <param name="serviceProvider">
   48         /// <para>The a mechanism for retrieving a service object; that is, an object that provides custom support to other objects.</para>
   49         /// </param>
   50         public void Open(IServiceProvider serviceProvider)
   51         {
   52         }
   53 
   54         /// <summary>
   55         /// <para>Saves the configuration settings created for the application.</para>
   56         /// </summary>
   57         /// <param name="serviceProvider">
   58         /// <para>The a mechanism for retrieving a service object; that is, an object that provides custom support to other objects.</para>
   59         /// </param>
   60         public void Save(IServiceProvider serviceProvider)
   61         {
   62         }
   63 
   64         /// <summary>
   65         /// <para>Adds to the dictionary configuration data for 
   66         /// the enterpriselibrary.configurationSettings configuration section.</para>
   67         /// </summary>
   68         /// <param name="serviceProvider">
   69         /// <para>The a mechanism for retrieving a service object; that is, an object that provides custom support to other objects.</para>
   70         /// </param>
   71         /// <param name="configurationDictionary">
   72         /// <para>A <see cref="ConfigurationDictionary"/> to add 
   73         /// configuration data to.</para></param>
   74         public void BuildContext(IServiceProvider serviceProvider, ConfigurationDictionary configurationDictionary)
   75         {
   76         }
   77 
   78         private static void RegisterXmlIncludeTypes(IServiceProvider serviceProvider)
   79         {
   80             // Find the xmlIncludeTypeService, which registers the XML-serializable class representing the configuration data.
   81             IXmlIncludeTypeService xmlIncludeTypeService = serviceProvider.GetService(typeof(IXmlIncludeTypeService)) as IXmlIncludeTypeService;
   82             Debug.Assert(xmlIncludeTypeService != null, "Could not find the IXmlIncludeTypeService");
   83             // Register the MyAuthorizationProviderData type with the xmlIncludeTypeService
   84             xmlIncludeTypeService.AddXmlIncludeType(SecuritySettings.SectionName, typeof(MyAuthorizationProviderData));
   85         }
   86 
   87         private static void RegisterNodeTypes(IServiceProvider serviceProvider)
   88         {
   89             // Get the Node Creation Service to we can register our configuration node (the designer class) with the configuration tool.
   90             INodeCreationService nodeCreationService = ServiceHelper.GetNodeCreationService(serviceProvider);
   91 
   92             Type nodeType = typeof(MyAuthorizationProviderNode);
   93             // Register a new command with the Node Creation Service, allowing multiple instances within a single configuration file.
   94             // The DisplayName parameter is what is displayed in the configuration manager menu.
   95             NodeCreationEntry entry = NodeCreationEntry.CreateNodeCreationEntryWithMultiples(new AddChildNodeCommand(serviceProvider, nodeType), nodeType, typeof(MyAuthorizationProviderData), "My Authorization Provider");
   96             nodeCreationService.AddNodeCreationEntry(entry);
   97         }
   98     }
   99 }

Because we are simply adding a new provider of a type the configuration manager already knows something about, we just have to figure out how to add our type to the correct menu item. In this case, the key is to know that in the RegisterXmlIncludeTypes method to call the AddXmlIncludeType takes the section name as its first parameter. Otherwise, the major difference between this class and the AppConfig example is that this one is much simpler. Most of the implementation of the IConfigurationDesignManager interface is not necessary, and there is no CreateCommands method, as the command to create an authentication provider node is already part of the configuration manager.

With that, I'll leave you to explore the Enterprise Library configuration management classes.

Enterprise Library Configuration (Part 1/2): Customized Appsettings and the EntLib Configuration Manager tool.

drohrer — Thu, 03 Feb 2005 03:30:00 GMT

So I've finally gotten comfortable enough with the configuration management tool to post some examples. I'll be doing a 2-part series on the Enterprise Library configuration framework and how you can incorporate your own application configuration into the tool and also customize the configuration offered by your custom frameworks.

I'd also like to point out the posts of Hisham Baz and Scott Densmore who have done some similar work and has a few other walk-throughs on both the Configuration topic and others.

I've included two projects in the downloadable solution. The first is essentially a customized appsettings node that can be edited in the configuration tool. The second is an overly simplified Authorization manager, which shows how to extend the existing frameworks and provide a user-friendly way to edit the configuration data for those extensions.

Update: I missed four lines of code in my example download code (sent an older version to James) and as of 11:51 PM EST on 2/2/2005, I've sent the update to James to get to his site. If you download it before he uploads the update, simply take the code in the blog post for the AppConfigNode.cs file and replace the code in the download with this code. Sorry for the inconvenience.

Update 2: It's now 9:45am on 2/3/2005 and James has updated the download.

My good friend James was nice enough to host the example's source for me, so, grab the code, sit back, and let's take a look.

Customized Application Configuration Nodes

Each customized configuration node requires several classes in order to be completely integrated with the configuration management tool. The first, as explained in the EntLib Quick Starts, is the container class, usually named with a postfix of "Data." This class is the class that is actually serialized to the config file, and is fairly simple.

AppConfigData.cs  
  1 using System;
    2 using System.Xml.Serialization;
    3 using EntLib = Microsoft.Practices.EnterpriseLibrary.Configuration;
    4 
    5 namespace EntLibConfigDemo {
    6     /// <summary>
    7     /// This class is the serializable representation of our configuration data.
    8     /// </summary>
    9     /// 
   10     [XmlRoot()]
   11     public class AppConfigData {
   12 
   13         public AppConfigData() {
   14         }
   15 
   16         public AppConfigData(string name) {
   17             this._name = name;
   18         }
   19 
   20         private string _url;
   21 
   22         /// <summary>
   23         /// The URL for the application
   24         /// </summary>
   25         [XmlElement("Url")]
   26         public string Url {
   27             get { 
   28                 return _url;
   29             }
   30             set {
   31                 _url = value;
   32             }
   33         }
   34 
   35         private int _maxUsers;
   36 
   37         [XmlElement("MaxUsers")]
   38         public int MaxUsers {
   39             get {
   40                 return _maxUsers;
   41             }
   42             set {
   43                 _maxUsers = value;
   44             }
   45         }
   46 
   47         private string _database;
   48 
   49         [XmlElement("Database")]
   50         public string Database {
   51             get {
   52                 return _database;
   53             }
   54             set {
   55                 _database = value;
   56             }
   57         }
   58 
   59         private string _name;
   60 
   61         [XmlElement("Name")]
   62         public string Name {
   63             get {
   64                 return _name;
   65             }
   66             set {
   67                 _name = value;
   68             }
   69         }
   70 
   71         /// <summary>
   72         /// Used to demonstrate the configuration manager's ability to display enums easily
   73         /// </summary>
   74         public enum AppState {
   75             Unknown,
   76             Up,
   77             Down
   78         }
   79 
   80         private AppState _state;
   81 
   82         [XmlElement("State")]
   83         public AppState State {
   84             get {
   85                 return _state;
   86             }
   87             set {
   88                 _state = value;
   89             }
   90         }
   91     }
   92 }

Note that the "State" property is defined by an Enum type, and in the configuration tool you will find that this data is represented by a drop-down list as you would expect. As stated earlier, this class is really just a data container, and the next class, the AppConfigNode, defines how this class is displayed in the configuration tool and what happens when certain events like node renames or removes happen in the tool. These events allow you to utilize other configuration nodes, like the database in this example, and be assured that when the user renames or removes them you can handle those changes appropriately. Here's the source for the AppConfigNode class, which we'll dig into more once you've read over it.

AppConfigNode.cs 
    1 using System;
    2 using System.ComponentModel;
    3 using System.Drawing.Design;
    4 
    5 using Microsoft.Practices.EnterpriseLibrary.Configuration.Design;
    6 using Microsoft.Practices.EnterpriseLibrary.Data.Configuration;
    7 using Microsoft.Practices.EnterpriseLibrary.Data.Configuration.Design;
    8 using Microsoft.Practices.EnterpriseLibrary.Configuration.Design.Validation;
    9 
   10 namespace EntLibConfigDemo {
   11     /// <summary>
   12     /// AppConfigNode is the configuration-time representation of the AppConfigData class.
   13     /// The ServiceDependency attribute informs the configuration manager that this class
   14     /// needs to instantialte an ILinkNodeService to make sure that other configuration nodes
   15     /// on which this node depends can be found.
   16     /// </summary>
   17     /// <remarks>
   18     /// Apply attributes from the System.ComponentModel namespace to tbe public properties to control their
   19     /// behavior in the configuration tool 
   20     /// </remarks>
   21     [ServiceDependency(typeof(ILinkNodeService))]
   22     public class AppConfigNode: ConfigurationNode {
   23 
   24         #region Constructors
   25 
   26         public AppConfigNode():this(new AppConfigData("Application Configuration")) {
   27         }
   28 
   29         public AppConfigNode(AppConfigData data) {
   30             _appConfigData = data;
   31         }
   32 
   33         #endregion
   34 
   35         #region Public properties
   36 
   37         private AppConfigData _appConfigData;
   38 
   39         [Browsable(false)]
   40         public AppConfigData Data {
   41             get {
   42                 return _appConfigData;
   43             }
   44         }
   45 
   46         [Category("General"), Description("Url of the system"), Required()]
   47         public string Url {
   48             get {
   49                 return _appConfigData.Url;
   50             }
   51             set {
   52                 _appConfigData.Url = value;
   53             }
   54 
   55         }
   56 
   57         [Category("General"), ReadOnly(true)]
   58         public override string Name {
   59             get { return base.Name; }
   60             set { base.Name = value; }
   61         }
   62 
   63         [Category("General"), Description("Maximum Users Allowed")]
   64         public int MaxUsers {
   65             get {
   66                 return _appConfigData.MaxUsers;
   67             }
   68             set {
   69                 _appConfigData.MaxUsers = value;
   70             }
   71         }
   72 
   73         private InstanceNode _database;
   74 
   75         [Category("Database"), Description("Database to use")]
   76         [Editor(typeof(ReferenceEditor), typeof(UITypeEditor))]
   77         [ReferenceType(typeof(InstanceNode))]
   78         [Required]
   79         public InstanceNode Database {
   80             get {
   81                 return _database;
   82             }
   83             set {
   84                 ILinkNodeService service = (ILinkNodeService)GetService(typeof(ILinkNodeService));
   85                 System.Diagnostics.Debug.Assert(null!=service, "Could not get the ILinkNodeService");
   86                 this._database = (InstanceNode)service.CreateReference(Database, value, new ConfigurationNodeChangedEventHandler(this.DatabaseRemoved), new ConfigurationNodeChangedEventHandler(this.DatabaseRenamed));
   87                 this.Data.Database = _database.Name;
   88             }
   89         }
   90 
   91         [Category("General"), Description("Application state")]
   92         public AppConfigData.AppState State {
   93             get {
   94                 return _appConfigData.State;
   95             }
   96             set {
   97                 _appConfigData.State = value;
   98             }
   99         }
  100 
  101         #endregion
  102 
  103         #region Configuration Tool Event Handlers
  104 
  105         private void DatabaseRemoved(object sender, ConfigurationNodeChangedEventArgs e) {
  106             this._database = null;
  107         }
  108 
  109         private void DatabaseRenamed(object sender, ConfigurationNodeChangedEventArgs e) {
  110             this._appConfigData.Database = e.Node.Name;
  111         }
  112 
  113         #endregion
  114 
  115         #region Private helper methods
  116 
  117 
  118         /// <summary>
  119         /// Used to create a blank database node if none exist in the application.
  120         /// </summary>
  121         private void CreateDatabaseSettingsNode() {
  122             if (!DatabaseSettingsNodeExists()) {
  123                 AddConfigurationSectionCommand cmd = new AddConfigurationSectionCommand(Site, typeof(DatabaseSettingsNode), DatabaseSettings.SectionName);
  124                 cmd.Execute(Hierarchy.RootNode);
  125             }
  126         }
  127 
  128 
  129         /// <summary>
  130         /// Attempts to find a database settings node in the database and returns if it was successful
  131         /// </summary>
  132         /// <returns>True if a DatabaseSettingsNode exist, and False if it doesn't.</returns>
  133         private bool DatabaseSettingsNodeExists() {
  134             DatabaseSettingsNode node = (DatabaseSettingsNode)Hierarchy.FindNodeByType(typeof(DatabaseSettingsNode));
  135             return (null!=node);
  136         }
  137         #endregion
  138 
  139         #region Configuration Manager-related Overrides
  140 
  141         /// <summary>
  142         /// This is called by the framework the each time an instance of this node is created from a previous saved state.
  143         /// This is used to find any dependent nodes in the configuration file and load their values for the user of this node.
  144         /// </summary>
  145         public override void ResolveNodeReferences() {
  146             DatabaseSettingsNode node = (DatabaseSettingsNode)Hierarchy.FindNodeByType(typeof(DatabaseSettingsNode));
  147             System.Diagnostics.Debug.Assert(null!=node, "How is it that the datbase node doesn't exist?");
  148             InstanceCollectionNode instCollNode = (InstanceCollectionNode)Hierarchy.FindNodeByType(typeof(InstanceCollectionNode));
  149             this.Database = (InstanceNode)Hierarchy.FindNodeByName(instCollNode, this._appConfigData.Database);
  150         }
  151 
  152 
  153         /// <summary>
  154         /// This method is called after the main node is created and gives the node an opportunity to add any default child nodes if necessary.
  155         /// </summary>
  156         protected override void AddDefaultChildNodes() {
  157             base.AddDefaultChildNodes ();
  158             this.CreateDatabaseSettingsNode();
  159         }
  160 
  161         /// <summary>
  162         /// This method is called when the configuration node is added to the heirarchy.  
  163         /// Used in this case to set the name of the node, as it is a single-instance node that cannot be renamed by the user.
  164         /// </summary>
  165         protected override void OnSited() {
  166             base.OnSited ();
  167             Site.Name = "Application Configuration";
  168         }
  169 
  170 
  171         /// <summary>
  172         /// Called when the node is renamed by the user.
  173         /// </summary>
  174         /// <param name="e">A <see cref="ConfigurationNodeChangedEventArgs"/> instance, which is used to get the new name of the node.</param>
  175         protected override void OnRenamed(ConfigurationNodeChangedEventArgs e) {
  176             base.OnRenamed (e);
  177             this.Data.Name = e.Node.Name;
  178         }
  179 
  180         #endregion
  181     }
  182 }

There's a lot going on in this class, so we're going to take some time to understand it better.

System.ComponentModel Attributes

The first thing to notice are the attributes attached to the public properties of the class. Most of these attributes are from the System.ComponentModel namespace, and are the same attributes you would use when create a design surface for a custom control. The Browsable(false) attribute tells the designer not to display the attribute in the designer, and the Category(), Description(), Required(), and ReadOnly() attributes should be self-explanatory. Many of the EntLib classes use SRCategory() and SRDescription() attributes, which use the as-yet-unreleased StringResource custom tool to derive their values. Hopefully that will be released to the public soon, because I like the concept of the StringResource tool and the SR* attributes.

One other set of attributes to note are the Editor() attribute on the Database property, which specifies that the run-time configuration tool should use a special control to display the choices for this type. The ReferenceEditor class will filter the nodes based on the type provided, and only display those nodes that exist in the current config file.

Update before posting: Someone has now release a String Resource Tool.

The ILinkNodeService and Referencing Other Node Types

Note that the Database property is of type InstanceNode, and that, when set, we use the ILinkNodeService instance provided by a call to the base class's GetService method to inform the configuration manager that we'd like a reference to that node by calling the CreateReference method. Further, we pass this method a few delegates to handle changes in that node, including removal or renaming of the node. In this way, whenever the user modifies our referenced node, we are informed of the change and can handle it appropriately.

ConfigurationNode Overrides

Our class overrides several members of the ConfigurationNode class to handle certain additional events that happen on all configuration nodes:

ResolveNodeReferences() - This method is called to provide the ConfigurationNode an opportunity to find it's dependent nodes when it is loaded in the configuration manager. Because our configuration node uses a Database instance node, we take this opportunity to find the referenced node in the configuration heirarchy and set our Database property appropriately. Note that, in theory, the FindNodeByName call could fail if the user manually edits a configuration file, but, in that case, our Database property should just be null and (if it were a required field) would force the user to pick a new node before the file would be saved.
AddDefaultChildNodes() - This method is called to make sure that, if your configuration node requires another node, you have an opportunity to create it if no node of that type exists. Here, we call a private method that checks to see if any database nodes exist, and, if not, add a new, empty database instance to the configuration. You can demonstrate this if you simply add a new application and then our "Test Application Configuration" node in the configuration manager. You'll notice that the entire Data Access Application Block configuration section is automatically added to the configuration file.
OnSited() - This is called when your node is added to the configuration file. In our case, we only want one instance of our settings node per application, and we don't want the user to be able to edit the name of the node, so we take this opportunity to set the name of the node in the configuration tree to "Application Configuration."
OnRenamed() - Called when the user renames the node. Of course, our node is not renamable and, therefore, this method would never truly be called. However, I kept it in the code so you would be aware of its existence and use.

That's about it for the AppConfigNode class. Hopefully you have a better idea of the magic behind the node. Now, we just have to get the configuration manager to know how to serialize/deserialize our class and how we expect users to add it to our configuration file. These tasks are accomplished by the AppConfigManager class:

AppConfigManager.cs 
    1 using System;
    2 using System.Configuration;
    3 using System.Windows.Forms;
    4 using Microsoft.Practices.EnterpriseLibrary.Configuration.Design;
    5 using Microsoft.Practices.EnterpriseLibrary.Configuration;
    6 
    7 
    8 namespace EntLibConfigDemo {
    9     /// <summary>
   10     /// Summary description for AppConfigManager.
   11     /// </summary>
   12     public class AppConfigManager: IConfigurationDesignManager {
   13 
   14         #region Constructors
   15 
   16         public const string SectionName = "AppConfigData";
   17         public AppConfigManager() {
   18             // No constructor logic required
   19         }
   20 
   21         #endregion
   22 
   23 
   24         #region IConfigurationDesignManager Members
   25 
   26         /// <summary>
   27         /// Registers configuration nodes and commands with the configuration manager
   28         /// </summary>
   29         /// <param name="serviceProvider"></param>
   30         public void Register(IServiceProvider serviceProvider) {
   31             // First, register the note type and data type with the node creation service
   32             RegisterNodeTypes(serviceProvider);
   33 
   34             // Map the XML section name in the config file to our node type
   35             RegisterXmlIncludeTypes(serviceProvider);
   36 
   37             // Create the new "Test Application Configuration" menu item for the application
   38             CreateCommands(serviceProvider);
   39         }
   40 
   41         /// <summary>
   42         /// Adds our data to the configuration dictionary
   43         /// </summary>
   44         /// <param name="serviceProvider"></param>
   45         /// <param name="configurationDictionary"></param>
   46         public void BuildContext(IServiceProvider serviceProvider, ConfigurationDictionary configurationDictionary) {
   47             AppConfigNode node = GetAppConfigNode(serviceProvider);
   48             if (node != null) {
   49                 AppConfigData settings = node.Data;
   50                 configurationDictionary[SectionName] = settings;
   51             }
   52         }
   53 
   54         /// <summary>
   55         /// Called when the configuration manager finds an instance of the configuration node in the config file.  
   56         /// Maps the data from the configuration file to the UI Configuration Node and adds it to the root node.
   57         /// </summary>
   58         /// <param name="serviceProvider"></param>
   59         public void Open(IServiceProvider serviceProvider) {
   60             ConfigurationContext configurationContext = ServiceHelper.GetCurrentConfigurationContext(serviceProvider); 
   61             if (configurationContext.IsValidSection(SectionName)) {
   62                 AppConfigNode appConfigNode = null;
   63                 try {
   64                     AppConfigData data = configurationContext.GetConfiguration(SectionName) as AppConfigData;
   65                     if (data != null) {
   66                         // If an instance of our data type was successfully loaded, add our UI node to the root configurationNode
   67                         appConfigNode = new AppConfigNode(data);
   68                         ConfigurationNode configurationNode = ServiceHelper.GetCurrentRootNode(serviceProvider);
   69                         configurationNode.Nodes.Add(appConfigNode);
   70                     }
   71                 }
   72                 catch (ConfigurationException e) {
   73                     ServiceHelper.LogError(serviceProvider, appConfigNode, e);
   74                 }
   75             }
   76 
   77         }
   78 
   79 
   80         /// <summary>
   81         /// Called when saving the configuration file.  Used to map the configuration node to its XML data representation and save the data to disk.
   82         /// </summary>
   83         /// <param name="serviceProvider"></param>
   84         public void Save(IServiceProvider serviceProvider) {
   85             ConfigurationContext configurationContext = ServiceHelper.GetCurrentConfigurationContext(serviceProvider);
   86             if (configurationContext.IsValidSection(SectionName)) {
   87                 AppConfigNode appConfigNode = GetAppConfigNode(serviceProvider);
   88                 AppConfigData data = appConfigNode.Data;
   89                 if (data != null) {
   90                     try {
   91                         configurationContext.WriteConfiguration(SectionName, data);
   92                     }
   93                     catch (InvalidOperationException e) {
   94                         ServiceHelper.LogError(serviceProvider, appConfigNode, e);
   95                     }
   96                 }
   97             }
   98         }
   99 
  100         #endregion
  101 
  102 
  103         #region Private implementation details
  104 
  105         /// <summary>
  106         /// Used to inform the Configuration Manager of our configuration node and data types.
  107         /// </summary>
  108         /// <param name="serviceProvider"></param>
  109         private void RegisterNodeTypes(IServiceProvider serviceProvider) {
  110             // Get the node creation service so we can add our node type.
  111             INodeCreationService nodeCreationService = ServiceHelper.GetNodeCreationService(serviceProvider);
  112             Type nodeType = typeof(AppConfigNode);
  113             // Creates a new entry to add to the node creation service.  The NoMultiples method creates a new entry that cannot have multiple instances in the same root node.
  114             NodeCreationEntry entry = NodeCreationEntry.CreateNodeCreationEntryNoMultiples(new AddChildNodeCommand(serviceProvider, nodeType), nodeType, typeof(AppConfigData), "Application Configuration Data");
  115             nodeCreationService.AddNodeCreationEntry(entry);
  116         }
  117 
  118         /// <summary>
  119         /// Register the relation between our section name and the configuration node used to display it.
  120         /// </summary>
  121         /// <param name="serviceProvider"></param>
  122         private void RegisterXmlIncludeTypes(IServiceProvider serviceProvider) {
  123             IXmlIncludeTypeService xmlIts = (IXmlIncludeTypeService)serviceProvider.GetService(typeof(IXmlIncludeTypeService));
  124             System.Diagnostics.Debug.Assert(null!=xmlIts, "Could not find IXmlIncludeTypeService");
  125             xmlIts.AddXmlIncludeType(SectionName,typeof(AppConfigNode));
  126         }
  127 
  128         /// <summary>
  129         /// Create new menuitem to allow the user to add an instance of our configuration node.
  130         /// </summary>
  131         /// <param name="serviceProvider"></param>
  132         private static void CreateCommands(IServiceProvider serviceProvider) {
  133             IUIHierarchyService hierarchyService = ServiceHelper.GetUIHierarchyService(serviceProvider);
  134             IUIHierarchy currentHierarchy = hierarchyService.SelectedHierarchy;
  135             bool containsNode = currentHierarchy.ContainsNodeType(typeof(AppConfigNode));
  136             IMenuContainerService menuService = ServiceHelper.GetMenuContainerService(serviceProvider);
  137             ConfigurationMenuItem item = new ConfigurationMenuItem("Test Application Configuration", new AddConfigurationSectionCommand(serviceProvider, typeof(AppConfigNode), SectionName), ServiceHelper.GetCurrentRootNode(serviceProvider), Shortcut.None, "Test Application Configuration", InsertionPoint.New);
  138             item.Enabled = !containsNode;
  139             menuService.MenuItems.Add(item);
  140         }
  141 
  142         /// <summary>
  143         /// Used to find the instance of the AppConfigNode for use in Load and Save methods
  144         /// </summary>
  145         /// <param name="serviceProvider"></param>
  146         /// <returns></returns>
  147         private static AppConfigNode GetAppConfigNode(IServiceProvider serviceProvider) {
  148             IUIHierarchy hierarchy = ServiceHelper.GetCurrentHierarchy(serviceProvider);
  149             if (hierarchy == null) return null;
  150 
  151             return hierarchy.FindNodeByType(typeof(AppConfigNode)) as AppConfigNode;
  152         }
  153 
  154         #endregion
  155 
  156     }
  157 }

IConfigurationDesignManager Ties It All Together

So you've got your data class, and you've got your node class, but you still can't see it in the configuration manager. Although there are a few tricks left after this class is implemented, they are nothing more than attributes and post-build events. It is the IConfigurationDesignManager interface that lets you register your classes in the configuration manager and create new menu items in the appropriate places for those classes. So, let's dig in:

Register() - Most of the UI-level hookups happen in this method. We register our Node types, which tells the Configuration Manager which visual classes we support in our assembly. We register our XmlIncludeTypes, which tell the configuration tool how to serialize and deserialize our data classes. And then, we add a new menu command to allow our uses to click on a "Test Application Configuration" menu item to add our new node to their configuration file. These things all happen in the private implementation details section, which, because of its importance to the grand scheme, I will go into in more detail below.
BuildContext() - Simply adds our data to the configuration dictionary. Even Scott Densmore doesn't think the context is all that interesting.
Open() - When the configuration manager finds the XML representation of one of our Data classes in the configuration file, it calls the Open method to let our manager map the data class to the appropriate visual node element.
Save() - When saving the configuration file, this method is called and we write our data back out to the configuration file. If any exceptions are thrown during the write, we log the exception so the configuration manager can display it to the user to fix.

The Guts (Private Implementation Details)

These methods are important as they are what drives the addition of our classes into the config tool in the IConfigurationDesignManager.Register() method, so let's look a little more carefully at these:

RegisterNodeTypes() - This method retrieves the default instance of the NodeCreationService provided by the ServiceProvider passed to us (which will be implemented by the configuration management tool). Once we have a node creation service, we register our AppConfigNode type as available for use, and mapping our AppConfigNode and our AppConfigData types together.
RegisterXmlIncludeTypes() - Similar to the RegisterNodeTypes method, we retrieve an instance of the XmlIncludeTypeService provided by the configuration manager and register our AppConfigData type to be mapped to the given section name.
CreateCommands() - Get the UI Heirarchy service, find the currently selected node in the heirarchy, and check to see if we already have an instance of our node (the containsNode variable). We'll use this information later to enable or disable our menu item based on this result. Then, get the IMenuContainerService instance and add a new menu command to the New menu (InsertionPoint.New) at the root node level (ServiceHelper.GetCurrentRootNode()) that will execute the AddConfigurationSectionCommand.ExecuteCore() method to add our config section, using the display text "Test Application Configuration" and enabled/disabled based on if we have our node in the configuration already (containsNode).

What's left? (Answer: Attributes and Build Events)

Two things remain to get your assembly registered with the UI:

Add an attribute to your AssemblyInfo.cs file that tells the configuration manager UI which class(es) in your assembly implement the IConfigurationDesignManager interface. The relevant sections of the file are:
-     1 using System.Reflection;
  
      2 using System.Runtime.CompilerServices;
  
      3 using Microsoft.Practices.EnterpriseLibrary.Configuration.Design;
  
        ...
  
     60 [assembly: ConfigurationDesignManager(typeof(EntLibConfigDemo.AppConfigManager))]
Push the DLL and any required reference DLLs to the EntLib\Bin directory (usually C:\Program Files\Microsoft Enterprise Library\Bin) so that the configuration manager can find them when it's loaded. As I develop a new configuration management implementation, I tend to like to be able to easily debug these classes so I also push the PDB files. If you run into issues, just add a call to System.Diagnostics.Debugger.Launch() in your code and then, when the configuration tool loads your assembly and fires off the relevant method, you can force the debugger to attach to the configuration manager and find your error. The file copy is accomplished using a post-build event on the project (mine is completely generic except for the location of EntLib, and so these two lines can be added to pretty much any project to move the target DLL to the correct directory):
- copy $(TargetPath) "C:\Program Files\Microsoft Enterprise Library\bin"
  
  copy $(ProjectDir)$(OutDir)*.pdb "C:\Program Files\Microsoft Enterprise Library\bin"

So that walks you through everything you need to know to add a single-instance configuration node to the root of your configuration file and allow your end-user to edit it easily in the configuration manager. OK, so it's nowhere close to everything, but I believe this should give you enough understanding to go "code spelunking" on your own.

Good luck. The next installment will cover extending existing frameworks with your own implementations, which require custom configuration sections of their own to be integrated with the tool. I'll use an AuthorizationProvider as an example, and you'll see that, once you grok the tool, it's not difficult to add your own configuration sections anywhere you need them.

EntLib is released!

drohrer — Sat, 29 Jan 2005 02:08:00 GMT

For those of you who have been following the development of Enterprise Library, it has been released. Now, go forth and download.

The first in my series of EntLib presentations will be on creating extensions to Enterprise Libary that plug in to the configuration manager, and I hope to have it up in the next few days, so stay tuned!

Enterprise Library presentation at Cincinnati .Net Users Group

drohrer — Wed, 26 Jan 2005 01:37:00 GMT

After a very long hiatus, I've returned to the blogging world with a bang. As my good friend James pointed out, I'll be giving a presentation on Enterprise Library, Microsoft's new consolidated application blocks, on February 15th at the Cincinnati .Net Users Group. Once EntLib goes gold (this Friday, no less) I'm going to do a series of posts discussing its use in a consolidated application. Additionally, there are some more esoteric areas of EntLib that deserve a look, and I'll cover some of those as well.