Adding settings to your feature

There are different kind of settings that you can use when developing your feature. There are profile settings, local settings and user/application settings. In this blog I’ll talk about user/application settings and the steps you need to do in order to add settings to your project. Using user/application settings will allow administrators to add role based values for some settings, provided that the Session Provider supports listing roles.

Manual deploy of settings

If you are on Smart Office 10.0.4 or later the settings files are stored in the database and you need to use the Import / Export Manager tool from within Smart Office.

Import_export

If you are using a previous version the files are found under SettingsFiles in the file area on the Smart Office server. LSOFiles is the property and you may or may not have configured this value to point to another folder or drive on the server where Smart Office is installed. The default location is wihin the Grid where the Application is deployed. The default name for the folder is LSOFiles.

Visual Studio 2012 support for LSOSettingsFileGenerator?

LSOSettingsFileGenerator does not support Visual Studio 2012. We just recently updated the plugin and created one install for Visual Studio 2012. The new version of the plugin will be delivered as part of the Smart Office SDK for 10.1.1.1. If you need a preview of the plugin before 10.1.1.1 you can write a comment here and I’ll send it to you. The plugin has one purpose and it is to create a xml that contains the settings you see in the Visual Studio Editor.

VSExtensions

If you don’t have the plugin you can manually create the xml file that is needed by copying one of the settings files that comes with Smart Office.

Step by step instructions for adding a setting

0) Uninstall previous version and close all running instances of Visual Studio

1) Install the MangoSettingsFileGenerator (10.1 and later) or LSOSettingsFileGenerator (10.0.5 and previous versions)

2) Enter the project settings and go to the properties tab. Enter the tool name (LSOSettingsFileGenerator for VS2010 and SettingsFileGenerator for VS2012) and the FeatureName.Properties, where FeatureName is the name of the feature assembly see image below.

VSConfigurations

3) Create your settings in the editor and save

4) Verify that a FeatureName.xml file has been generated in the root of the project and the source code file has been generated and contains all the settings. Make sure that you add this file to the project and select it to be copied to bin. It needs to get copied to the bin directory so that it can be packaged as part of your feature. If the file is generated verify that you have written the correct Tool name in the properties pane for the Settings.settings file in Visual Studio. If not you can always create this file manually by using the settings file in the SDK sample as template.

If the file isn’t created you can try and close Visual Studio. Then test the following:
– Open the Registry Editor and navigate to this key
HKEY_CURRENT_USER\Software\Microsoft\VisualStudio
– Locate a key called 11.0_Config and then delete the key or rename it to something else
The key will be recreated by Visual Studio when started

Start Visual Studio with the feature project and try and edit the settings again.

5) Open your FeatureName.manifest and add a settings element.

<SettingsFile assembly="FeatureName"/>

6) Deploy the generated xml file to the server. If you try to run the project at this time you will probably get an exception with “Root Element is missing”. That is becuase when you run your solution it downloads the settings file from the server since it should be merged with any settings that you have for roles etc. You need to upload the settings file to the server. This is done in different ways depending on the version of Smart Office. If you have settings file on a file area you can add your settingsfile there but then you might need to restart the Smart Office server. I’m not sure. So try without restarting first but if that does not work you need to restart it. If the settings files are in the database (version 10.0.3 and later) you use the import/export tool found under “Administration tools” in the Navigator widget. You export the settings (but not roles and rules) then unzip it, add your file, zip it and then you upload it again.

Now you are ready to use user/application settings!

The next step would be to plugin your settings UI into the User Settings (Show -> Settings)or to create your custom UI for the Settings Editor (for administrators), but simply having the possibility to store and control your settings in the same way and with the same tools as Smart Office is a great gain in itself.

UserSettings

Some implementation advice

There are some considerations that you need to know and be aware of when using the settings class.

1) The first time you access a setting there will be a server call to download and merge the latest version of the settings. This means that you should pre-access a setting (any would do) on a background thread when your application is initialized. So if you don’t already have a displatch to a background thread from the Applications Create method (IClientApplication) you should add that simply to access a setting. You can access an important setting and for example log the value of the setting as the application starts.

2) ReadOnly. All settings can get the IsReadOnly flag. Setting a value on a ReadOnly setting will generate an exception. To prevent that you can add code within your settings class to check the ReadOnly flag before setting a value. If this flag is set it should be reflected in you application by disabling menu items or by disabling or hiding the setting from the user. We generally hide the setting in the Settings UI if the administrator has decided that this setting is ReadOnly.

// access setting
var isSuperUser = Settings.Default.IsSuperUser;
// Check read only
var isReadOnly = Settings.Default.IsReadOnlyIsSuperUser;

8 thoughts on “Adding settings to your feature

  1. Pingback: Add a Profile fragment with Smart Office SDK | M3 ideas

  2. Andrew Cowburn

    Hi,
    I’m looking for the MangoSettingsGenerator for VS2013? Do you know if this is available? The one that is part of SDK 10.1.1 isn’t compatible with VS2013.

    Thank you.

    Andy

    Reply
    1. karinpb Post author

      Hi,
      I’m sorry but the plugin for VS2013 isn’t available. I recommend you to report it to support. The format has changed and we haven’t updated the plugin. It is still possible to manually edit and add settings in the generated xml file. That approach is what we use when we add a new setting. The plugin is great for adding the settings file the first time but once you have an example of the xml for an Application Setting and User Setting you can manually create them in the Feature.Name.xml file and in the generated code file.

      Reply
  3. Billy Willoughby

    Hello; Is there a way to save a setting globally in a way accessible via the SDK? I want to save settings like a provider URL for a custom service, and have the change accessible by everyone using the feature. Is there a way to do so the user can change that value?

    Reply
    1. karinpb Post author

      Hi,
      If you want the user to be able to change the value and that applies to all users- the answer is no. You need to be an LSOAdministrator to be able to change a setting that affects others. Users can only change user settings. So you need to provide your own web service for storing and reading the URL. A URL for a custom servicve would normally go in the profile – but only administrators can change it. Another alternative is an Application setting – but only administrators can change that.

      Reply
      1. Billy Willoughby

        Thank you Ms. Karen! Is there an example settings file since the generation tool doesn’t work with Visual Studio 2013?

  4. karinpb Post author

    Hi,
    Sorry for the late reply. I’m on vacation.

    <?xml version="1.0" encoding="utf-8"?>
    <mp:Properties xmlns:mp="http://schemas.intentia.net/Mango/Settings/Properties">
      <mp:Settings>
        <mp:UserSettings>
        </mp:UserSettings>
        <mp:ApplicationSettings>
          <mp:Property Name="Theme">
            <mp:DefaultValue></mp:DefaultValue>
            <mp:Value />
          </mp:Property>
          <mp:Property Name="EnableCollaboration">
            <mp:DefaultValue>True</mp:DefaultValue>
            <mp:Value />
          </mp:Property>
        </mp:ApplicationSettings>
      </mp:Settings>
      <mp:Hash />
    </mp:Properties>
    
    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s