Custom application settings that are stored using the CustomProfile class have had changes introduced that split the custom application settings into individual application based settings. The way in which custom application settings are stored was changed to increase performance with applications that utilized custom application settings. Specific steps need to be taken to migrate settings from the legacy settings to the new application based settings. The sections below outline how to use the legacy settings, the new application based settings, and how to migrate settings.

Jump to a section:

Working with Legacy Settings

Working with legacy settings can be done in the same way it was done before; however, the CustomProfile(Session) constructor has been obsoleted in preference of the GetLegacyCustomProfile(Session) method.

Back to Introduction

Working with Application Based Settings

To retrieve and set application based settings, the ApplicationProfileName property needs to be set prior to calling Connect(SessionSettings, HostSettings, AuthSettings, StationSettings) (or the associated async method). The GetApplicationCustomProfile(Session) method can then be used to get the CustomProfile object. If the application needs to access custom application settings from a different profile than is referenced on the ApplicationProfileName property, then a call to GetOtherApplicationCustomProfile(Session, String) can be made, and will return the appropriate custom application settings for the supplied profile name. Retrieving the custom application settings this way will not allow modifications, and as such, attempting to modify settings will result in an IceLibException.

Note

Although setting application based settings can be set via SetProfileItem(String, String, Object) (or the associated async method), it is recommended that they be set via SetProfileItem(String, String, String) (or the associated async method).

Back to Introduction

Migration of Legacy Settings to Application Based Settings

Specific steps need to be taken to migrate settings from the legacy application settings to the new application based settings. The following code example outlines a possible migration scenario:

CopyC#
private const string _RootNamespaceName = "My Root Namespace";

private void DoLegacyMigration()
{
    // This example assumes that a _Session object has been declared and already connected.
    // Additionally, it assumes that SessionSettings.ApplicationProfileName was set 
    // prior to connecting.

    // Check to see if the IC Server supports Application Based Settings, and 
    // return out if it doesn't.
    if (!CustomProfile.AreApplicationBasedSettingsSupported(_Session)) return;

    try
    {
        // Create the CustomProfile object to handle the new Application Based Settings.
        CustomProfile applicationProfile = CustomProfile.GetApplicationCustomProfile(_Session);

        // Check to see if the new settings already exist, and return out if they do.
        if (applicationProfile.CheckForApplicationBasedSettings()) return;

        // Get the legacy settings.
        CustomProfile legacyProfile = CustomProfile.GetLegacyCustomProfile(_Session);
        IDictionary<string, ProfileItem> legacySettings = legacyProfile.GetNamespaceContents(_RootNamespaceName);

        // Do the migration.
        foreach (KeyValuePair<string, ProfileItem> legacySetting in legacySettings)
        {
            // Should this setting be migrated?
            if (!IsLegacySettingEligibleForMigration(legacySetting.Value)) continue;

            try
            {
                // Convert the value.
                string newValue = ConvertLegacySettingValue(legacySetting.Value);

                // Set the new profile item on the Application Based Settings.
                applicationProfile.SetProfileItem(
                    legacySetting.Value.NamespacePath, legacySetting.Value.Key, newValue);
            }
            catch (Exception ex)
            {
                // TODO
            }
        }

        // Commit the changes
        applicationProfile.FlushChanges();
    }
    catch (IceLibException iceLibException)
    {
        // TODO
    }
    catch (Exception exception)
    {
        // TODO
    }
}

private bool IsLegacySettingEligibleForMigration(ProfileItem profileItem)
{
    if (profileItem == null) return false;

    // TODO:  Determine if this setting should be migrated or not.

    return true;
}

private string ConvertLegacySettingValue(ProfileItem profileItem)
{
    if (profileItem == null) throw new ArgumentNullException("profileItem");

    // TODO:  Convert the current setting object value to a string value
    //        since Application Based Setting value serialization/deserialization 
    //        should now be handled by each individual application.

    return String.Empty;
}

Back to Introduction

Migration of Application Based Settings from a Different Application Profile Name

It may be necessary for an application to migrate application based settings from a different application profile. One possible scenario for this could be in the case of the release of a new version of a custom IceLib-based application in which settings from a previous version need to be updated/ignored in order to keep compatibility with previous versions that could still be in use. The following code example outlines a possible migration scenario:

CopyC#
private const string _OldRootNamespaceName = "My Root Namespace";
private const string _OriginalApplicationProfileName = "My Custom Application";

private void DoProfileMigration()
{
    // This example assumes that a _Session object has been declared and already connected.
    // Additionally, it assumes that SessionSettings.ApplicationProfileName was set 
    // prior to connecting, and that a different value is used for the 
    // ApplicationProfileName parameter of CustomProfile.GetOtherApplicationCustomProfile.

    // Check to see if the IC Server supports Application Based Settings, and 
    // return out if it doesn't.
    if (!CustomProfile.AreApplicationBasedSettingsSupported(_Session)) return;

    try
    {
        // Create the CustomProfile object to handle the new Application Based Settings.
        CustomProfile applicationProfile = CustomProfile.GetApplicationCustomProfile(_Session);

        // Check to see if the new settings already exist, and return out if they do.
        if (applicationProfile.CheckForApplicationBasedSettings()) return;

        // Create the CustomProfile object to handle the original Application Based Settings.
        CustomProfile oldApplicationProfile = CustomProfile.GetOtherApplicationCustomProfile(
            _Session, _OriginalApplicationProfileName);

        // Check to see if the old settings exist, and return out if they don't.
        if (!oldApplicationProfile.CheckForApplicationBasedSettings()) return;

        // Get the old settings.
        IDictionary<string, ProfileItem> oldSettings =
            oldApplicationProfile.GetNamespaceContents(_OldRootNamespaceName);

        // Do the migration.
        foreach (KeyValuePair<string, ProfileItem> oldSetting in oldSettings)
        {
            // Should this setting be migrated?
            if (!IsOldSettingEligibleForMigration(oldSetting.Value)) continue;

            try
            {
                // Convert the value.
                string newValue = ConvertOldSettingValue(oldSetting.Value);

                // Set the new profile item on the Application Based Settings.
                applicationProfile.SetProfileItem(
                    oldSetting.Value.NamespacePath, oldSetting.Value.Key, newValue);
            }
            catch (Exception ex)
            {
                // TODO
            }
        }

        // Commit the changes
        applicationProfile.FlushChanges();
    }
    catch (IceLibException iceLibException)
    {
        // TODO
    }
    catch (Exception exception)
    {
        // TODO
    }
}

private bool IsOldSettingEligibleForMigration(ProfileItem profileItem)
{
    if (profileItem == null) return false;

    // TODO:  Determine if this setting should be migrated or not.

    return true;
}

private string ConvertOldSettingValue(ProfileItem profileItem)
{
    if (profileItem == null) throw new ArgumentNullException("profileItem");

    // TODO:  Convert the current setting value if needed.

    if (profileItem.IsPlainTextValue)
    {
        // TODO:  Convert the string value.
    }
    else
    {
        // TODO:  Convert the object value to a string.
    }

    return String.Empty;
}

Back to Introduction