Edit

Application Settings for Custom Controls

  • Article

You must complete certain tasks to give your custom controls the ability to persist application settings when the controls are hosted in third-party applications.

Most of the documentation about the Application Settings feature is written under the assumption that you are creating a standalone application. However, if you are creating a control that other developers will host in their applications, you need to take a few additional steps for your control to persist its settings properly.

Application Settings and Custom Controls

For your control to properly persist its settings, it must encapsulate the process by creating its own dedicated applications settings wrapper class, derived from ApplicationSettingsBase. Additionally, the main control class must implement the IPersistComponentSettings. The interface contains several properties as well as two methods, LoadComponentSettings and SaveComponentSettings. If you add your control to a form using the Windows Forms Designer in Visual Studio, Windows Forms will call LoadComponentSettings automatically when the control is initialized; you must call SaveComponentSettings yourself in the Dispose method of your control.

In addition, you should implement the following in order for application settings for custom controls to work properly in design-time environments such as Visual Studio:

  1. A custom application settings class with a constructor that takes an IComponent as a single parameter. Use this class to save and load all of your application settings. When you create a new instance of this class, pass your custom control using the constructor.

  2. Create this custom settings class after the control has been created and placed on a form, such as in the form's Load event handler.

For instructions on creating a custom settings class, see How to: Create Application Settings.

Settings Keys and Shared Settings

Some controls can be used multiple times within the same form. Most of the time, you will want these controls to persist their own individual settings. With the SettingsKey property on IPersistComponentSettings, you can supply a unique string that acts to disambiguate multiple versions of a control on a form.

The simplest way to implement SettingsKey is to use the Name property of the control for the SettingsKey. When you load or save the control's settings, you pass the value of SettingsKey on to the SettingsKey property of the ApplicationSettingsBase class. Application Settings uses this unique key when it persists the user's settings to XML. The following code example shows how a <userSettings> section may look for an instance of a custom control named CustomControl1 that saves a setting for its Text property.

<userSettings>
    <CustomControl1>
        <setting name="Text" serializedAs="string">
            <value>Hello, World</value>
        </setting>
    </CustomControl1>
</userSettings>

Any instances of a control that do not supply a value for SettingsKey will share the same settings.

See also