Howto use antonys configuration systen
TL;DR;
Create a POCO configurationClass and use the attributes within the https://www.nuget.org/packages/antony.Groupware.ExtensionInterfaces/ NuGet package to configure it. Then you can inject yourself a IConfiguration<MyConfiguration> into your module to get and save this configuration. See our trainee project for an concrete example https://bitbucket.org/diegroupware/antony.demo.trainee.desktop/src/master/ .
General
antonys' configuration system consists of multiple configuration layer.
DefaultLayer: The default layer is “hardcoded” by the definition of your configurationClass
GlobalLayer: The global layer is used to create an enterprise-wise configuration
GroupLayer: Each user can be within a configurationGroup. You are able to configure this whole group
UserLayer: The user-specific configurations are stored here
ComputerLayer: If you want to create configurations just for a single computer, this is the layer of choice. This might contain hardware specifics settings
The settings are overwritten from the computerlayer upwards. This means if you provide a configuration C1 within the GlobalLayer and also another configuration C2 in the UserLayer of User U1, the user U1 will get the configuration C2 if requested. Other users will get C1.
Before your start implementing your configuration you might think about which configuration you want to save in which layer. Perhaps you need two different configurations? For example you might have a global configuration for the access to your system to integrate, but also a userspecific one for saving authentication information? As said you should make the decision before you start to implement.
Define your Configuration
First you have to defined your Configuration. Therefore you need to create a POCO Class holding all your configuration values. Below you see an example configuration class. Your class needs to be attributes with the ConfigurationNameAttribute. The name is needed to access your configuration.
You can also use Lists and Dictionarys within your configuration, as these will be serialized. But it is recommended to not place business logic here.
[ConfigurationName(nameof(TraineeConfiguration))]
public class TraineeConfiguration
{
public string MyTitle { get; set; }
[EncryptedConfiguration()]
public string MySecret { get; set; }
[ConfigurationDefault]
public static TraineeConfiguration Default => new TraineeConfiguration()
{
MyTitle = "Trainee",
MySecret = ""
};
}For a simple example we’ll provide a simple property MyTitle. This property is read by the module (see later) and used as a caption for the antonys FlexObject Tab. The property MySecret is an encrypted one. The configurationsystem detects these properties automatically and persists them in an encypted string. Be economical using this option, as you cannot easily by-pass antony to read them directly.
You can only encrypt string properties this way. You cannot use other types will now.
The last property is attribtues with the ConfigurationDefault attribute. If no configuration is stored with the given configurationName you will get the defaultConfiguration.
You can explicit request an configuration from a specific layer. Within this method you will not get the DefaultConfiguration
Access you Configuration
You can access the configuration by injecting a class into your module. All defined extensionspoints are able to inject this. To access the configuration defined in the above TraineeConfiguration you need to inject an IConfiguration<TraineeConfiguration>.
On this interface you can read, write and delete the configurations. The example below will show you an example usage of the IConfiguration interface. You’ll get the configuration of the current context and display it within an example MessageBox.
public class MyChatCommand: IChatCommand, IModuleSelector<AttachedContactViewSelector>
{
private IConfiguration<TraineeConfiguration> _configuration;
public MyAttachedContactView(IConfiguration<TraineeConfiguration> configuration)
{
_configuration = configuration;
}
public Task ExecuteAsync(IntPtr parentWindow, IProgressReporter reporter)
{
var myTraineeConfig = _configuration .GetFromContext();
MessageBox.Show($"Hello World with configuration: {myTraineeConfig .MyTitle}");
)
}
}
Writing the configuration
A config is useless if you dont have the possibility to write it. Therefore you can call the Savemethod of your IConfiguration. Befor you do so, you might check if you are able to Save by calling the “CanSave” Method. As you might guess you need to specify the layer you want to write into.
_config.Save(new TraineeConfiguration()
{
MyTitle = "ChangedTitle"
}, ConfigurationLayer.UserLayer);There is also a nice extension to update an existing config. If you only want to update a single value, you can use this one.