Cool Client Stuff : Configuration/Settings

Client Settings FAQ updated

rprabhu — Sun, 11 Dec 2005 01:00:00 GMT

I finally got around to updating my FAQ on the settings feature in .NET 2.0. Look for 'Update: 12/10/2005' to identify the new content. The new stuff is mostly some questions frequently asked on forums and internal mailing lists in Microsoft around security, configuration and availability of the settings feature in non-Windows Forms applications.

Saving out a Form's Size and Location using the Application Settings feature

rprabhu — Tue, 29 Nov 2005 10:30:00 GMT

A very common requirement for Windows Forms applications is the ability to 'remember' the location and size of forms when they are closed, so that the next time they are shown, they can be restored to the former position. The Application Settings feature is .NET 2.0 makes it simple to do this, but unfortunately, it is a little hard to get it 'just right'. This question is asked frequently on internal and external Microsoft forums, so I thought it warranted a blog post.

Now, the Windows Forms designer in Visual Studio 2005 provides a simple UI to data bind properties on controls to application settings. So the first thing that might occur to you is to simply bind the Form's Location and Size properties to settings, add a line of code to save the settings class, and that's it! Unfortunately, this is not the best option for a few reasons:

First of all, you may notice that the Form.Size property is not offered up in the settings binding UI. This is because this property is marked DesignerSerializationVisibility.Hidden, so the designer doesn't know how to serialize it, let alone generate a data binding for it. Instead, for Form, the ClientSize property is the one that gets serialized.
So okay, maybe you can bind Location and ClientSize then? Well, yes, but this has another problem. Try setting it up and then attempt to resize the form from the left or top edge. You will see weird behavior. Why is this? It is beyond the scope of this post to give the full explanation, but it suffices to say that it has to do with how two way data binding works in the context of property sets that mutually affect each other (in the case of Location and ClientSize, both eventually call into a common method, SetBoundsCore()).
This solution does not do the 'right' thing in the situation when the user maximized the form before closing it. In this case, you probably want to remember that the form was maximized, but also keep track of the last location/size before it was maximized, so you can restore it the next time the user hits the Restore button. You may want to handle the minimize case in a similar way too. The simple data binding solution does not do this right.
Data binding to properties like Location and Size is just not efficient. Each time the user moves the form or resizes it, Windows sends hundreds of messages to the form, causing the data binding logic to do a lot of processing, when all you want is just to store the last position and size before the form is closed.

The good news is that this is very easy to do with a few lines of code:

private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{

     Properties.Settings.Default.MyState = this.WindowState;

if (this.WindowState == FormWindowState.Normal)

{

   Properties.Settings.Default.MySize = this.Size;

   Properties.Settings.Default.MyLoc = this.Location;

}

else

{

   Properties.Settings.Default.MySize = this.RestoreBounds.Size;

   Properties.Settings.Default.MyLoc = this.RestoreBounds.Location;

}

Properties.Settings.Default.Save();

}

private void Form1_Load(object sender, EventArgs e)

{

this.Size = Properties.Settings.Default.MySize;

this.Location = Properties.Settings.Default.MyLoc;

this.WindowState = Properties.Settings.Default.MyState;

}

By the way, speaking of Windows Forms 2.0, there is a lot of great new content on the WindowsForms.net site. Jessica has been actively blogging on interesting Windows Forms topics too.

Client Settings FAQ posted

rprabhu — Thu, 30 Jun 2005 01:21:00 GMT

We have been getting lots of feedback on the new Whidbey Settings feature that I have blogged about in the past. Since there are a set of questions many people ask as they begin to delve into the API, I thought it might be useful to post an FAQ that I can point folks to that should answer most of these questions. I posted this as an article instead of a regular blog post so I can update it off and on in the future.

If you have any suggestions for questions to add to the FAQ, please feel free to leave a comment here.

Client Settings - Part 3

rprabhu — Fri, 18 Jun 2004 17:00:00 GMT

RichB has some interesting questions in his comments about my earlier post on the client settings feature. I thought it might be worth a separate post to answer them.

I don't have the CTP available, but from the documentation it appears that ApplicationSettingsBase can read and write to a collection of providers. I can understand the writing to multiple providers (saving the same values into multiple locations) but how does it read the same values from multiple locations.

Yes, a settings class can talk to multiple providers, but each setting (or property) in it is associated with a single provider. This just means that you can have different providers for different settings in a settings class.

I also hope you have a good "story" for plug-in based applications. For example, Lutz Roeder's Reflector and Nikhil's Web Matrix are both heavily pluggable. Is there a prescribed way for each plug-in/component to obtain and save configuration information to the same store?

Yes, we have a story for this scenario. There is an interface called IPersistComponentSettings that any component can implement to save its own settings when hosted in an application. For example, the ToolStrip control implements this. Someone using the ToolStrip in their app can just set a property called SaveSettings to true and the ToolStrip will save/restore settings automatically without the user having to set anything up.

I'm also a bit hazy on Setting Groups. I've noticed the SettingsGroupNameAttribute - but am not entirely clear on how it's meant to be used.

Usually, the settings class name is used to identify your settings in the store. If you want them stored with a different name or share settings with some other class, you can use the SettingsGroupNameAttribute to rename/redirect your settings.

Finally, do you have generic methods for loading from the store to prevent boxing?

No, but that's a good suggestion. We will consider doing this.

Client Settings - Part 2

rprabhu — Sat, 03 Apr 2004 08:45:00 GMT

In a post a few months ago, I wrote about a new Whidbey feature called Client Settings. While we briefly described this feature at the PDC, it wasn't available in the build of Whidbey released then. The Community Preview build gives you a chance to try out everything I mentioned and more.

Quite some functionality has been added to this feature since the PDC. I list some of the new capabilities below. If you haven't read my previous post, please read that first for background.

[Caveat: Not all this may work very well in the recently released Community Preview build]

First of all, we now provide full fledged design time support in Visual Studio for you to easily create some settings and bind to them. As a simple example, lets say you want to provide the user of your app the ability to customize the BackColor of a Form, and you want to save their setting, so that when they run the app again, you can restore their preference. All you need to do is this: in the Form designer in Visual Studio, you will notice a new property in the property browser named “(Application Settings)”. This allows you to create a setting (in this case, user scoped) and set up a binding to a property in a manner very similar to setting up data bindings. In the background, the Settings Designer will create a class for you that derives from ApplicationSettingsBase that has a property corresponding to the setting you just created. And the Forms Designer will generate the code to data bind that setting to your BackColor property. All you need to do now is to call Save() on your settings object - say, in the Form's Closing event. This line, in VB, will look something like:

My.Settings.Save()

That's it! You now have everything setup to save each user's preference for BackColor of the Form.

The Settings Designer itself is another place you can start to create settings. In a VB project, the settings designer is offered as a tab in the Application Designer. In C#, you should be able get to it in a similar manner in a future build. The designer has simple UI to create settings and assign default values to them. It will generate the code for the settings class and its properties, with appropriate attributes specified.
ApplicationSettingsBase offers a bunch of new functionality. It has events that are fired when a setting's value changes, or when settings are saved (i.e., passed down to the provider). You can use these to do validation for example. It also provides methods to reset the settings to their default values and upgrade settings from a previous version of the settings class.
We also provide the ability for components to store their own settings, in a manner transparent to the host, through an interface called IPersistComponentSettings. The ToolStrip is an example of a control that implements this interface. If you drop a ToolStrip on your Form, you will notice a boolean property called 'SaveSettings'. Just set this to true, and the ToolStrip will automatically begin to store its own settings - like which rafting container it is placed in and what its location is within the container. ToolStrip items too can store out settings of their own. All this happens transparently - a ToolStrip user doesn't need to setup anything - just set SaveSettings to true! You can provide this same functionality for your component/control just by implementing IPersistComponentSettings.

So you may be wondering - where are these settings stored? That really depends on the settings provider you are using. The default settings provider that ships in Whidbey is called the LocalFileSettingsProvider. This stores all the settings in configuration files. One of the other things the Settings Designer described above does for you is put the required entries in the application config file, where our provider stores application scoped settings, and default values for user scoped settings. In .Net Framework v1.1, there were two levels of configuration files - machine and application. In Whidbey, we have introduced the concept of user specific config files, that are stored under the user's profile path. These config files are created when a user saves their preferences, and contain the values that differ from the defaults.

Anyway, that's just an overview of some of the new functionality we have added since the PDC. If you are using the feature, do let us know what you think!

Feature Preview: Client Settings

rprabhu — Fri, 21 Nov 2003 14:11:00 GMT

One of the new Whidbey features Joe Stegman talked about at the PDC was Client Settings. This is a feature I have spent a lot of time on in Whidbey, so I thought I would talk a little bit about it.

Very often, if you are writing a client app (also for web apps, but let me focus on client for now), you need the ability to store some settings. These settings are often user preferences, like Form size and location, look and feel of various controls, toolbar positions, last read entry etc. etc. These could also be more application specific things like connection strings and resource paths. In .NET Framework v1.0 and v1.1, there are several ways to achieve this - using dynamic properties, writing your own configuration section to store stuff into the application config file or storing the settings in a separate file, possibly in XML format, and parsing the content yourself. Ofcourse, then there is the traditional store for application settings - the Windows registry.

Each of these, however, has some limitations. Dynamic properties support a limited range of types and are read only. Writing a configuration section isn't very easy - you need to do all the parsing, merging between levels and validation yourself. Storing settings into an independent file means you need to management the deployment of that file yourself, besides, ofcourse, having to do the parsing, defining what schema to use and so on. The registry too isn't the right place to store settings in many cases.

So, if you want to store settings today, you need to put in considerable effort to do it right. The Configuration Management Application Block solves some of these problems for you today, and is pretty cool, but in Whidbey, we are taking a big step forward and are trying to design a model which makes it super easy to consume settings in your application. What's more, the core parts of this model are common to web and client apps, so there is more consistency in how you store and access settings across different kinds of applications.

At the core of the new settings infrastructure are two abstract classes - SettingsBase and SettingsProvider. SettingsBase hides the storage details way from the application developer and exposes an easy mechanism to read, write and save settings. The SettingsProvider is actually responsible for persisting these settings. How it persists them is its own choice - SettingsBase doesn't really care. It could store them in a local file, a database or retrieve them through a web service, for example. In each case, the way the application consumes the settings remains the same.

The ApplicationSettingsBase class Joe talked about adds value to SettingsBase and makes it even more easier to create your own settings. Essentially, in this model, settings are nothing but properties on classes that are decorated with a bunch of attributes that describe them.

Here is a how a simple settings class would look:

public class MySettings : ApplicationSettingsBase {
   [UserScopedSetting] // varies by user
   [DefaultSettingValue("Blue")] // use this if no value is stored
   public Color MyFormColor {
       get {
             return (Color) this["MyFormColor"];
        }
        set {
              this["MyFormColor"] = value;
         }
   }

   [ApplicationScopedSetting] //shared by all users
   [SettingsProvider("MyWebServiceProvider.blahblah")]
   public Point FooLocation {
       get {
             return (Point) this["FooLocation"];
        }
        set {
              this["FooLocation"] = value;
         }
   }
}

and then consuming these settings is equally staightforward:

myForm1.BackColor = MySettings.MyFormColor;
...
MySettings.FooLocation = myControl1.Location;
...
MySettings.Save();

Its as simple as that! You can read/write settings of arbitrary types (which the provider can serialize, ofcourse) with just a few simple lines of code. By default, for client apps, we will ship a provider that can store settings into the application configuration files (we are extending the configuration system to store user specific stuff too) without any extra effort on the application developer's part!

That's not it, though. This model is also powerful for those who have more requirements. You can write your own custom provider that stores settings wherever it wants. You can exercise more control over how the default provider serializes its settings. You can define your own attributes that only your provider understands - ApplicationSettingsBase will pass the metadata over to the provider. You can group your settings into a bunch of different classes, map settings to different providers, bind the settings to properties of your UI/business objects through data binding and so on and so forth. If you wish to write your own configuration section, the ASP.NET team has made that much easier too.

That's not all we have planned - there is more, including great design time support in Visual Studio and the concept of component settings.

More on all this as we approach Whidbey Beta!