Task-Based Help How to Modify Settings Model

Application Settings. How to Modify Settings Model

Circumstances may require rename an existing Setting Key or move to another place in Application Model, i.e., to modify the Settings Model. At the same time you want to keep the Setting Values. This section describes the sequence of operations that must be performed to implement such modification.

Note

You can view the code used in this lesson in the Xafari.FeatureCenter|Settings folder of the Feature Center demo installed with Xafari. By default, the Feature Center application is installed in %PUBLIC%\Documents\Xafari Framework vXX.X.XXXX Demos\FeatureCenter.

Code snippet below declares four Settings Keys that are contained in two groups.

public interface IFeatureCenterSettings : IModelBCSettingsGroup
{
  Group1 Group1 { get; }
  [ModelDefault("Value", "Settings slice 'FeatureCenter'.")]
  IModelKeyString KeyString { get; }
}
public interface Group1 : IModelBCSettingsGroup
{
  IModelKeyBool KeyBool { get; }
  IPesistentObject PesistentObject { get; }
  IModelSettingEnum EnumSetting { get; }
}

Public Interface IFeatureCenterSettings
  Inherits IModelBCSettingsGroup
  ReadOnly Property Group1 As Group1
  <ModelDefault("Value", "Settings slice 'FeatureCenter'.")> _
ReadOnly Property KeyString As IModelKeyString
End Interface
Public Interface Group1
  Inherits IModelBCSettingsGroup
  ReadOnly Property KeyBool As IModelKeyBool
  ReadOnly Property PesistentObject As IPesistentObject
  ReadOnly Property EnumSetting As IModelSettingEnum
End Interface

KeyBool, PesistentObject and EnumSetting Keys are included in Group1 group, KeyString Key is in the FeatureCenterSettings group, as shown in the image below.

app_settings_13

The goal of this lesson is to move the KeyBool Key from Group1 group to FeatureCenterSettings group and keep its old value.

app_settings_14

To do this, follow the steps below.

Decorate KeyBool property with Obsolete attribute.

public interface Group1 : IModelBCSettingsGroup
{
  [Obsolete]
  IModelKeyBool KeyBool { get; }
  IPesistentObject PesistentObject { get; }
  IModelSettingEnum EnumSetting { get; }
}

Public Interface Group1
  Inherits IModelBCSettingsGroup
  <Obsolete> _
ReadOnly Property KeyBool As IModelKeyBool
  ReadOnly Property PesistentObject As IPesistentObject
  ReadOnly Property EnumSetting As IModelSettingEnum
End Interface

Define a new KeyBool Key in the FeatureCenterSettings group.

public interface IFeatureCenterSettings : IModelBCSettingsGroup
{
  IModelKeyBool KeyBool { get; }
  Group1 Group1 { get; }
  IModelKeyString KeyString { get; }
}

Public Interface IFeatureCenterSettings
  Inherits IModelBCSettingsGroup
  ReadOnly Property KeyBool As IModelKeyBool
  ReadOnly Property Group1 As Group1
  ReadOnly Property KeyString As IModelKeyString
End Interface

Implement FCSettingsNodeUpdater class. It must to inherit from the Xafari.BC.Settings.SettingsNodeUpdater or to support Xafari.BC.Settings.ISettingsNodeUpdater interface. Code snippet below shows FCSettingsNodeUpdater class.

public class FCSettingsNodeUpdater : SettingsNodeUpdater
{
  public override void UpdateSettingsNode(IModelBCSettings node)
  {
    var FCSettings = node as IModelKeysFC;
    if (FCSettings == null)
      return;
    var oldValue = FCSettings.FeatureCenterSettings.Group1.KeyBool;
    var newValue = FCSettings.FeatureCenterSettings.KeyBool;
    this.Update(oldValue, newValue);
  }
}

Public Class FCSettingsNodeUpdater
  Inherits SettingsNodeUpdater
  Public Overrides Sub UpdateSettingsNode(ByVal node As IModelBCSettings)
    Dim FCSettings = TryCast(node, IModelKeysFC)
    If FCSettings Is Nothing Then
      Return
    End If
    Dim oldValue = FCSettings.FeatureCenterSettings.Group1.KeyBool
    Dim newValue = FCSettings.FeatureCenterSettings.KeyBool
    Me.Update(oldValue, newValue)
  End Sub
End Class

Add FCSettingsNodeUpdater instance to the SettingsAccessor.Instance.Updaters collection. This can be done in Updater class, or when initializing SettingsAccessor. Then, call the Update() method as follows.

public class Updater : XafariModuleUpdater
{
  //...
  public override void SafeUpdateDatabaseAfterUpdateSchema()
  {
    //...
    SettingsAccessor.Instance.Updaters.Add(new FCSettingsNodeUpdater());
    this.ObjectSpace.AppSettings().Update();
    this.ObjectSpace.AppSettings().Root().KeysFCSettings().KeyString.Value = "new value with updater";
    //...
  }
  //...
}

Public Class Updater
  Inherits XafariModuleUpdater
  '...
  Public Overrides Sub SafeUpdateDatabaseAfterUpdateSchema()
    '...
    SettingsAccessor.Instance.Updaters.Add(New FCSettingsNodeUpdater())
    Me.ObjectSpace.AppSettings().Update()
    Me.ObjectSpace.AppSettings().Root().KeysFCSettings().KeyString.Value = "new value with updater"
    '...
  End Sub
  '...
End Class

Perform DB Update. After that you can delete obsolete property and FCSettingsNodeUpdater class from the code.

Important

The operation to transfer Settings values from one node to another is performed only once. To perform the migration again, you must reset the values of the new Settings.