ApplicationRegistries

To Japanese

ApplicaitonRegistries is a .NET library that will proxy the application's external settings.

Description

When developing a Windows application, several parameters are implemented so that you can change it later. For example, there are a timeout time which is a parameter affected by specs, and a port number which is a parameter utilizing resources of the entire PC. The general method is as follows.

• setting file
• Environment variable
• Commandline arguments
• Registry (Windows case)
• Application configuration file(*.exe.config)

You can choose freely, but these are the same for the application and are "external settings".

However, the implementation method is different. For example, you need to implement the commandline argument parser yourself. A null check is required in the registry. It is not easy to use.

Also, implementing the loading process in various places makes it difficult to list external settings. Besides that, the implementation is not the same each time.

ApplicationRegistries acts as a proxy for the "External settings" listed above. "External setting value" can be read with simple usage and with priority order. You can also output a list report of "External settings".

Quick Start

The following code is an example of usage

[ApplicationRegistry]
public interface ISettings
{
  /// <Summary>
  /// Listen Port Number
  /// </Summary>
  [DefaultValue(80)]
  int PortNo { get; }

  /// <Summary>
  /// Backup to
  /// </Summary>
  string BackupFolder { get; }
}

class Program
{
  static void Main()
  {
    int portNo = ApplicationRegistry.Get<ISettings>().PortNo;
  }
}

Dependency

ApplicationRegistries2.dll depends only on .NET Framework 4.5. ApplicationRegistries2.dll will be distributed with your application.

Other support tools distributed with nuget depend on the following libraries.

• RazorEngine

How to install

You can install using nuget.

PM> Install-Package ApplicationRegistries

How to use

1. Reference ApplicationRegistries2.dll.
2. Declare the interface corresponding to the external setting value. The interface has the following restrictions.
   • Having only the get property.
   • Property type must be the following Type.
     • Int32
     • string
3. Attach the attribute [ApplicationRegistry] to the external setting value interface.
4. You can read external settings by accessing properties using ApplicationRegistry.Get <T> (). T specifies an interface type declared with 2.

By default ApplicationRegistries loads external settings with the following priority.

• (1)Commandline argument
• (2)Environment Variable
• (3)Registry(HKCU)
• (4)XML File
• (5)Registry(HKLM)

By specifying the loading place in the argument of the [ApplicationRegistry] attribute You can set the priority, enable / disable.

Usage: Commandline arguments

By default, ApplicationRegistries reads external settings with the following commandline arguments.

--[Interface Name]_[Property Name]="[Value]"

Example

  [ApplicationRegistry]
  public interface ISettings
  {
    int PortNo {get;}
  }

--ISettings_PortNo=80

You can change the interface name and property name by specifying the attribute [CommandlineArgumentPrefix] and [CommandlineArgumentName].

Example

  [ApplicationRegistry]
  [CommandlineArgumentPrefix("Settings")]
  public interface ISettings
  {
    [CommandlineArgumentName("ListenPort")]
    int PortNo {get;}
  }

Usage: Environment Valiable

By default, ApplicationRegistries reads external settings with the following Environment Valiable.

set [Assembly Name]_[Interface Name]_[Property Name]=[Value]

例

  // ApplicationRegistries.Sample.dll
  [ApplicationRegistry]
  public interface ISettings
  {
    int PortNo {get;}
  }

set ApplicationRegistries.Sample‗ISettings_PortNo=80

You can change the assembly name , the interface name and property name by specifying the attribute [EnvironmentVariablePrefix] and [EnvironmentVariableName].

例

  [ApplicationRegistry]
  [EnvironmentVariablePrefix("Settings")]
  public interface ISettings
  {
    [EnvironmentVariableName("ListenPort")]
    int PortNo {get;}
  }

Usage: Registry

By default, ApplicationRegistries reads external settings with the following registries'.

In case of HKCU

[HKCU\Software\ApplicationRegistries\[Assembly Name]\[Interface Name]]
"Property Name"=[type]:[value]

In case of HKLM

[HKLM\Software\ApplicationRegistries\[Assembly Name]\[Interface Name]]
"Property Name"=[type]:[value]

Example

  // ApplicationRegistries.Sample.dll
  [ApplicationRegistry]
  public interface ISettings
  {
    int PortNo {get;}
  }

[HKCU\Software\ApplicationRegistries\ApplicationRegistries.Sample\ISettings]
"PortNo"=dword:00000050

[HKLM\Software\ApplicationRegistries\ApplicationRegistries.Sample\ISettings]
"PortNo"=dword:00000050

You can change the location of the registry by specifying the attribute [RegistryKey] and [RegistryName].

Example

  [ApplicationRegistry]
  [RegistryKey(@"Software\MyCompany\MySoftware")]
  public interface ISettings
  {
    [RegistryName("ListenPort")]
    int PortNo {get;}
  }

Usage: XML File

By default, ApplicationRegistries reads external settings with the following Xml file'.

File Path: [ApplicationRegistries2.dll's Folder]\ApplicationRegisties.xml

<?xml version="1.0" encoding="utf-8" ?>
<ApplicationRegisties>
  <[Interface Name]>
    <[Property Name]>Value</[Property Name]>
  </[Interface Name]>
</ApplicationRegisties>

Example

  // ApplicationRegistries.Sample.dll
  [ApplicationRegistry]
  public interface ISettings
  {
    int PortNo {get;}
  }

<?xml version="1.0" encoding="utf-8" ?>
<ApplicationRegisties>
  <ISettings>
    <PortNo>80</PortNo>
  </ISettings>
</ApplicationRegisties>

You can change the xml file path and the xml file structure by specifying the attribute [XmlFile] and [XmlName].

Example

  [ApplicationRegistry]
  [XmlFile(@".\Settings.xml", "/Settings")]
  public interface ISettings
  {
    [XmlName("ListenPort")]
    int PortNo {get;}
  }

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <ListenPort>80</ListenPort>
</Settings>

Usage: Default Value

You can specify a default value if all of the external settings can not be loaded. You can specify it with the attribute [DefaultValue].

Example

  [ApplicationRegistry]
  public interface ISettings
  {
    [DefaultValue(80)]
    int PortNo {get;}
  }

Priority and invalidation of external setting

The default priority order of external setting is as shown in the following table. You can change the priority or invalidate by specifying the key as an array in the argument of [ApplicationRegistry].

External Setting	default priority	Key
Commandline arguments	1	BuiltInAccessors.CommandlineArguments
Environment variable	2	BuiltInAccessors.EnvironmenetVariable
Registry(HKCU)	3	BuiltInAccessors.UserRegistry
XML File	4	BuiltInAccessors.XmlFile
Registry(HKLM)	5	BuiltInAccessors.MachineRegistry

  [ApplicationRegistry(
    BuiltInAccessors.CommandlineArguments,
    BuiltInAccessors.EnvironmenetVariable,
    BuiltInAccessors.UserRegistry,
    BuiltInAccessors.MachineRegistry
  )]
  public interface ISettings
  {
    int PortNo {get;}
  }

User defined external settings

If you want to read the setting values from application-specific database or configuration file, you can implement your own loading process.

1. Create a user defined class for reading external setting values implementing IAccessor.
2. Register user-defined classes with ApplicationRegistry.RegistCustomAccessor(). At this time, specify the key as the first argument.

  ApplicationRegistry.RegistCustomAccessor("CUSTOM", new CustomAccessor());

3. Specify the key registered in 2 as the argument of the attribute [ApplicationRegistry].

  [ApplicationRegistry(
    "CUSTOM",
    BuiltInAccessors.CommandlineArguments,
    BuiltInAccessors.EnvironmenetVariable,
    BuiltInAccessors.UserRegistry,
    BuiltInAccessors.MachineRegistry
  )]
  public interface ISettings
  {
    int PortNo {get;}
  }

Reporting

You can generate an html report from the external settings interface. If you get from nuget, the path goes to Package Manager Console or post-build action.

> ApplicationRegistries2.Formatters.App.exe --input=<your assembly path> --output=report.html

The command line arguments are as follows.

-i,--input    (required) input assembly file paths.(comma separated)
-o,--output   (required) output html file path.
-f,--format   report template file path.
-t,--template export default report template file. specified output path.
-h,-?,--help  show help.

Customize reports

You can export the default report template with --template option of ApplicationRegistries2.Formatters.App.exe.

> ApplicationRegistries2.Formatters.App.exe --template=<output file path>

You can change the style and format of the report by specifying the modified template file with the --format option.

> ApplicationRegistries2.Formatters.App.exe --input=<your assembly path> --output=report.html --format=<my template>

User defined external settings report

Implement IPropertyFormatter to report user-defined external settings. And you need to specify the assembly with the --input option of ApplicationRegistries2.Formatters.App.exe.

Contribution

1. Fork it ( https://github.com/banban525/ApplicationRegistries/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

MIT

Author

banban525