Client Setup
The client is a light-weight class library targeting the .NET standard 2.0 framework. The client library can be installed using the nuget package manager, and will be compatible with both .NET and .NET Core frameworks.
Install-Package Elgorithm.Elconfig -Version 0.9.3
The ConfigurationContainer can be used to retrieve/register configuration objects anywhere in your application. When constructing a ConfigurationContainer, the provided API endpoint and API secret key must be passed into the constructor for the container to successfully call into the Elconfig web services.
The API endpoint and API secret key will be provided to you by Elgorithm.
Please see the Configuration Object Introduction to see how to create a configuration object in your code.
using System;
using System.Threading.Tasks;
using System.Web;
using System.Web.Mvc;
using Elconfig.Client;
using ElconfigTestProject.ConfigurationObjects;
using ElconfigTestProject.Models;
namespace ElconfigTestProject.Controllers
{
public class HomeController : Controller
{
public ActionResult Index()
{
HomeModel model = new HomeModel();
ConfigurationContainer container = new ConfigurationContainer("apiEndPoint", "apiScretKey");
TestConfiguration configuration = container.GetConfiguration<TestConfiguration>();
model.WebsiteText = configuration.WebsiteText;
model.TextColor = configuration.WebsiteTextColor;
model.BulletPointEnabled = configuration.EnableBulletPoint;
return View(model);
}
}
}
Client Operations
The ConfigurationContainer class provides the two methods your application will need to retrieve/register configuration objects. If a configuration object does not exist, that object will be registered by creating an entry for that object in the underlying data storage. Once a configuration object has been registered, it will be available for viewing and editing in the web application.
| Method | Description | Exceptions |
|---|---|---|
| GetConfiguration | Retrieve the specified configuration object. If the object is present in the in-memory cache, then it is returned. If it is not present in the cache, a web service call is required. If the item exists, it will be returned by the web service and then it will be cached based on the configured caching parameters and then returned. If the item does not exist, it will be created by a web service call using the configured default values specified in the configuration object, cached, and then returned to the caller. | ConfigurationValidationException, ConfigurationOperationException |
| GetDynamicConfiguration | Retrieve the specified dynamic configuration object after executing the provided input object against the configured javascript script. Caching is not supported for dynamic configurations and a web service call must be made to execute the configured script against the provided input object and return the result. If the item, does not exist, a web service call is made to register the dynamic configuration object and then perform the execution step to return the result to the caller. | ConfigurationValidationException, ConfigurationOperationException |
| GetDefaultObject | Retrieve a newly instantiated object populated with the specified default values. This method can be used as a fallback in the event of an error when calling GetConfiguration() or GetDynamicConfiguration() |
ConfigurationValidationException, ConfigurationOperationException |
Introduction
Configuration objects hold properties which can represent various configuration knobs and switches that your application can utilize. Configuration objects are defined by your application and then persisted. Once a configuration object is persisted, it becomes available to be edited in the web application.
Once a class is decorated with the Configuration attribute, it becomes eligible to be persisted as a configuration object. Properties inside of your configuration object will need to be decorated with the Property attribute.
When your application goes to retrieve the latest value of your configuration object using the Elconfig client, it will potentially first check an in-memory cache for that object, and if it not present, the client will call into the Elconfig API to retrieve the latest object. Whether or not and how long your configuration item is cached locally is up to you. It is recommended to cache your configuration objects for at least five minutes.
Basic Example
In this basic example we have defined a configuration object with three properties. The class is decorated with the Configuration attribute which specifies the unique identifier, the application this configuration belongs to, and a brief description. Each property in the class is decorated with the Property attribute which indicates how this property should be viewed and configured in the web application.
TestConfiguration configuration = container.GetConfiguration<TestConfiguration>(); is used to retrieve the latest value of the configuration object in your code. Whatever has been saved in the web application will automatically be carried over to the value you retrieve in your application.
using System;
using Elconfig.Client.Core;
using Elconfig.Client.Core.Attributes;
namespace ElconfigTestProject.ConfigurationObjects
{
[Configuration(CONTEXT, APPLICATION_NAME, DESCRIPTION)]
public class TestConfiguration
{
private const string CONTEXT = "TestAppConfig";
private const string DESCRIPTION = "This is a test configuration";
private const string APPLICATION_NAME = "Elconfig Test Application";
[Property("This is the default text of this website. This text can be changed at any time by using Elconfig.", "This is a description of this configuration property. This is text that will be displayed on the website.")]
public string WebsiteText { get; set; }
[Property("Black", "This property allows you to change the color of the web site text.", InputType.Auto, Options = new String[] { "Black", "Blue", "Red" })]
public string WebsiteTextColor { get; set; }
[Property(true, "Enable or disable the third bullet point on the home page.")]
public bool EnableBulletPoint { get; set; }
}
}
Attributes
Configuration Attribute
The Configuration attribute is used to indicate that your class is a persisted configuration object. This attribute is required for the class to be used with the client API and the web application.
| Property | Description | Default Value |
|---|---|---|
| Context | The context is the identifier for your configuration object and is the name the web application will use to refer to your configuration object. This context must be unique within an application space. | |
| ApplicationName | This identifies what application your configuration belongs to. This is used in the web application to organize your configurations for easier access. | |
| Description | A brief description that will be visible in the web application to let users know the purpose of the configuration object. | |
| CacheExpirationMinutes | This specifies the number of minutes the client should hang onto the configuration object in memory before retrieving the latest version from the database. Caching is important for performance. | 5 (five) minutes |
| CachingPolicy | Indicates whether or not this object should be cached locally in memory. Using CachingPolicy.Never will force the client to never cache your configuration object and always attempt to retrieve it from the database. This is not recommended due to the performance implications. |
CachingPolicy.Always |
DynamicConfiguration Attribute
The DynamicConfiguration attribute is used to indicate that your class is a persisted dynamic configuration object. This attribute is required for the class to be used with the client API and the web application. Note that the main difference between the DynamicConfiguration attribute and Configuration attribute is that caching is not supported on the DynamicConfiguration attribute.
| Property | Description | Default Value |
|---|---|---|
| Context | The context is the identifier for your configuration object and is the name the web application will use to refer to your configuration object. This context must be unique within an application space. | |
| ApplicationName | This identifies what application your configuration belongs to. This is used in the web application to organize your configurations for easier access. | |
| Description | A brief description that will be visible in the web application to let users know the purpose of the configuration object. |
Property Attribute
The Property attribute is used to configure individual properties on your configuration object. These configurations allow you to specify how the object should appear and be edited in the web application.
| Property | Description | Default Value |
|---|---|---|
| DefaultValue | This is the value your property will be initialized as. | |
| Description | A brief description that will be visible in the application to let users know the purpose of this specific property on the configuration object. | |
| InputType | The input type specifies how you want your property to behaving in the web application. When using InputType.Auto, the client will look at the value type of your property and attempt to make a best guess as how the value should be edited in the user interface. For example, if your property is a DateTime type, in the user interface the property will be edited with a date selecter. |
InputType.Auto |
| Options | The options is a string array that allows you to specify what the selectable values are for this property. The values will appear as a drop-down in the web application. If options are specified, an input type of Auto or DropDown must be specified. |
public enum InputType
{
TextBox = 1,
MultiLineTextBox = 2,
DropDown = 3,
DateTime = 4,
Date = 5,
RadioButton = 6,
EnableDisable = 7,
Auto = 9,
Script = 10
}
public enum CachingPolicy
{
Always = 1,
Never = 2
}
Making Changes
If a configuration object class is renamed, no change will take place in the Elconfig web application. The client cues off of the context value specified in the Configuration attribute. If the context value is changed, a new identical configuration object will be created using that context. The old context and object associated with it will still be viewable in the Elconfig web application, but can be deleted through the user interface.
If a new property is added, the client library will automatically detect the newly added property and attempt to validate it and register it. If the new property passes validation, it will be available for editing in the Elconfig web application.
If a new option is added to a property's selectable options, that value will automatically be picked up and selectable in the Elconfig user interface. Removing an option will cause that option to no longer be selectable in the Elconfig user interface. It is not recomended to remove an option that is currently selected. In this case, the option value will still be persisted, but not viewable in the Elconfig user interface.
Removing a property from your object will not cause it to be removed from the Elconfig web application. It is recommended that if properties need to be renamed or removed, that the configuration object context be changed so a new context is created in Elconfig and the old context can safely be deleted.
Changing an existing configuration object's default values specified in the Property attributes will have no effect unless the configuration object context is deleted in Elconfig and re-created through your application using the client.
Changing an existing configuration object's description in the Property or Configuration attribute will have no effect unless the configuration context is deleted in Elconfig and re-created through your application using the client. The descriptions are only editable through Elconfig after the configuration object is registered using the client.
Dynamic Introduction
Dynamic Configurations allow you to define a javascript script that can be executed against a C# input object that you define. The result of the execution is then passed back to the caller in the properties you have defined in your configuration object.
Dynamic Example
In this example, a dynamic configuration is defined with a javascript script that adds two numbers and returns the result. In the script, a variable named "output" must be defined or an exception will be thrown. Inside the script, the variable that is passed into GetDynamicConfiguration(object input) is referenced as an existing variable named "input". Properties referenced on the "input" and "output" variables must match (including capitalization) what you have defined.
//
// Sample Execution
//
ConfigurationContainer container = new ConfigurationContainer("apiEndpoint", "apiSecretKey");
var numbers = new
{
X = 5,
Y = 10
};
//Input variable is passed into the javascript script as "input" and can be referenced within the script.
//
DynamicTestConfiguration dynamicConfiguration = container.GetDynamicConfiguration<DynamicTestConfiguration>(numbers);
Debug.Assert(dynamicConfiguration.Sum == 15);
using System;
using Elconfig.Client.Core;
using Elconfig.Client.Core.Attributes;
namespace ElconfigTestProject.ConfigurationObjects
{
[DynamicConfiguration(CONTEXT, APPLICATION_NAME, DESCRIPTION)]
public class DynamicTestConfiguration
{
private const string CONTEXT = "Dynamic";
private const string DESCRIPTION = "Dynamic configuration.";
private const string APPLICATION_NAME = "TestApp";
private const string SCRIPT = @"// Basic javascript script to calculate the sum of two numbers.
var sum = CalculateSum(input.X, input.Y);
var output = {Sum: sum};
function CalculateSum(x, y)
{
return x + y;
}
";
[Property(SCRIPT, "Dynamic Configuration Script", InputType.Script)]
public string Script { get; set; }
public int Sum { get; set; }
}
}
Home Page
After signing in, you will be brought to the home page. The home page serves as a dashboard to quickly look at recent activity and overall statisitics. The home page displays the total number of applications registered, the number of configurations changed in the last twenty four hours, the number of configurations the current user is watching, the total number of configurations, the total number of users, and the total number of configurations changed in the last week.
Under the "Most Recently Viewed" section you have a quick link to navigate to a configuration you have recently viewed or edited. The "Most Recent Activities" section shows you recently changed configurations as well as which user made the change. Clicking on the hourglass for normal configuration object changes will open a new window that shows the before and after values of the change.
Making Updates
Navigating to the "Configurations" menu item at the top will bring you to the Configurations view which is where you can edit and view existing configurations. On the left navigation menu, you will see all the configuration object contexts your application has registered using the client. These can be filtered down to "Standard" and "Script". There is a also a drop-down selector to filter down by application and a search bar to filter down by context name on the configuration objects.
When viewing a specific configuration object, you will see information for that object, including all the properties you have defined and the configured editors for those properties. The are several buttons available to perform actions on the configuration object:
| Button | Description |
|---|---|
| Save | After entering an optional comment, save the current configuration context if all validation passes. The current version in the "Version Logs" will be updated with your changes. |
| Refresh | Refresh the current page and re-load the current version of the configuration context. |
| Watch/Watching | Watch or un-watch the current configuration context. Watching a configuration will give you notifications when other users make changes to that configuration context. |
| Delete | Delete the current configuration context and all the associated activity and versioning for that configuration. This action should only be performed if the configuration context is no longer used by your application. If you delete an active configuration context, your application will immediately re-create it the first time it tries to retrieve it using the client. The newly created version will not have any of the associated version or activity history that existed previously. |
Before a configuration object can be saved, it must pass validation. A validation error can occur if you attempt to save a value that is incompaitble with the property. For example: attempting to save the value "Test" for a property that is an integer will result in a validation error:
If someone else is currently viewing a configuration in the configuration editor, you will be notified with a message in the interface and a viewing icon will appear next to that configuration context in the navigation menu on the left. Although you will be given a warning, you can still save your changes. It is important to check with the other user to avoid overwritting each other's changes.
The "Activity Logs" show a list of changes that have been made to the current configuration context. For a standard configuration object, each row will show the previous and current value for a property value that was changed, the user who made the changes, and the time the change was made. Clicking the calendar icon in the upper right allows you to filter acitivities by date ranges.
Versioning
Every time a configuration is saved within the web application, a new version is created with the developer's comments. Older versions are viewable in the "Version Logs" section of the configuration editor page. In this section you can revert to a previous version which will essentially load the older version of the configuration object into the Configuration Editor view. This allows you to press save and esentially revert to the previous version.
The version logs can be filtered down to specific time windows by clicking the calendar icon in the upper right of the "Version Logs" section.
Watching Configurations
Watching a configuration will allow you to filter for this object on the home page when viewing "Most Recent Activities".
Watching a configuration will also cause you to receive alert notifications when other users make changes to those configuration objects that you are currently watching.
Administration
There are two administration pages that only admin users can access.
The User Administration page allows admins to view, create, edit, delete, and reset passwords for existing users. When creating a user, you must specify whether or not that user is an admin or an editor. Editors are the basic users that can modify configurations and view changes made throughout various applications. Admin users have the same priveleges as editors and the ability to access the administration pages.
When resetting a user's password, it is important to copy the password that is generated. Once the reset password dialog is closed, there is no way to access the previously generated password. If the password is lost, you will have to reset the password again. You cannot reset your own password in the User Administration page.
If you wish to reset your own password, you must navigate to the "Home" page and then select the "Change your password" link on the menu to the left.
The Application Administration page allows admins to edit and delete existing applications that have been registered by a client. It's important to note that application names are generated by the application names specified on your configuration objects in your application. If you change the application name on your configuration object, a new application entry will be generated. Applications can only be deleted by administrators if there are no configuration objects pointed to that application.