From 6d934ba9e415e83bcc79b7c7b70bd291eea3153c Mon Sep 17 00:00:00 2001 From: Marijn van der Zee Date: Fri, 16 Dec 2011 17:40:16 +0100 Subject: [PATCH] Add VariableSource configuration sections to documentation --- doc/reference/src/objects.xml | 253 ++++++++++++++++++++++++++++++++-- 1 file changed, 244 insertions(+), 9 deletions(-) diff --git a/doc/reference/src/objects.xml b/doc/reference/src/objects.xml index 7ab0bf1a..23a9a54d 100644 --- a/doc/reference/src/objects.xml +++ b/doc/reference/src/objects.xml @@ -4996,24 +4996,259 @@ cfg.PostProcessObjectFactory(factory); </object> </list> </property> -</object> - +</object> The use of the IgnoreMissingResources property above will mean that if the property file is not found it will be silently ignored and the resolution will continue to ConfigSectionVariableSource. - The IVariableSource interface is shown below + - public interface IVariableSource + The variable sources that Spring.NET provides out of the box are + described in the following sections. + + + <literal>ConfigSectionVariableSource</literal> + + The ConfigSectionVariableSource allows you + to define variables in a custom configuration section in you + configuration file: + + <!-- app.config: --> +<configuration> + <configSections> + <section name="DonConfiguration" type="System.Configuration.NameValueSectionHandler"/> + </configSections> + <DonConfiguration> + <add key="don_name" value="Dick Whitman"/> + <add key="don_age" value="41" /> + </DonConfiguration> +</configuration> + +<!-- consume variables: --> +<object type="Example.Person, Spring.IocQuickStart.VariableSources"> + <property name="Name" value="${don_name}" /> + <property name="Age" value="${don_age}" /> +</object> + +<!-- VariableSource configuration: --> +<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="DonConfiguration" /> +</object> + + + This is similar to using the + PropertyPlaceHolderConfigurer described + above. + + By simply configuring the appropriate section, you can use the + ConfigSectionVariableSource to retrieve variables + from application settings and user settings. Assuming your + application's root namespace is + Spring.IocQuickStart, then your application- and + user settings can be loaded as variables by configuring the + following variable sources: + + <!-- From .net's ApplicationSettings: --> +<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="applicationSettings/Spring.IocQuickStart.Properties.Settings" /> +</object> + +<!-- From .net's UserSettings: --> +<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="userSettings/Spring.IocQuickStart.Properties.Settings" /> +</object> + + + If you configured your application settings as such: + + + + + + Then you can use ${peggy_name} + and ${peter_age} as variable placeholders in your + object definitions. + + + + <literal>PropertyFileVariableSource</literal> + + A PropertyFileVariableSource allows to read + properties defined in a Java-style property file as variables. + Assume a file named application.properties in + your application folder containing: + + joan_name=Joan Harris +joan_age=35 + + You can use the ${joan_name} and + ${joan_age} variable placeholders if you + configure the following variable source: + + <object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core"> + <property name="Location" value="~\application.properties" /> +</object> + + + + <literal>ConfigurableVariableSource</literal> + + A ConfigurableVariableSource allows you + define variables inline in a variable source definition. To + configure the variables midge_name and + midge_age, you can use the following + ConfigurableVariableSource definition: + + <object type="Spring.Objects.Factory.Config.ConfigurableVariableSource, Spring.Core"> + <property name="Variables"> + <name-values> + <add key="midge_name" value="Midge Daniels"/> + <add key="midge_age" value="33"/> + </name-values> + </property> +</object> + + + + <literal>CommandLineArgsVariableSource</literal> + + You can use commandline arguments as a source for variables. + Assume you issue the following command to start myapp: + + myapp /roger_name:"Roger Sterling" /roger_age:57 + + The following variable source configuration allows you to use + ${roger_name} and ${roger_age} + as variable placeholders: + + <object type="Spring.Objects.Factory.Config.CommandLineArgsVariableSource, Spring.Core"> + <property name="ArgumentPrefix" value ="/" /> <!-- optional; default: "/" --> + <property name="ValueSeparator" value=":" /> <!-- optional; default: ":" --> +</object> + + + + <literal>RegistryVariableSource</literal> + + Entries in the Windows registry can be used as variables. When + your registry contains the key + HKEY_CURRENT_USER\MyKey with entries + freddy_name (String) and freddy_age + (DWord), then you can configure the following variable + source to use freddy_name and + freddy_age as variables: + + <object type="Spring.Objects.Factory.Config.RegistryVariableSource, Spring.Core"> + <property name="Key" value="HKEY_CURRENT_USER\MyKey" /> +</object> + + + + <literal>EnvironmentVariableSource</literal> + + You can configure an + EnvironmentVariableSource an to retrieve + variables from environment variables available through .NET's + System.Environment class: + + <object type="Spring.Objects.Factory.Config.EnvironmentVariableSource, Spring.Core" /> + + + To retrieve a value for a variable named + ken_name, the + EnvironmentVariableSource will directly call + System.Environment.GetEnvironmentVariable("ken_name"). + + + + <literal>ConnectionStringsVariableSource</literal> + + Visual Studio has good support for configuring database + connection strings in a connectionStrings section + in you application configuration file. You can retrieve these + connections as variables by configuring a + ConnectionStringsVariableSource: + + <object type="Spring.Objects.Factory.Config.ConnectionStringsVariableSource, Spring.Core" /> + + Assume the following connection string section in your + application configuration file: + + <connectionStrings> + <add name="myConnection" + connectionString="Data Source=myserver;Integrated Security=True;..." + providerName="System.Data.SqlClient" /> +</connectionStrings> + + Then you would use the variables as in following object + definition: + + <object type="Example.MyClass, MyAssembly"> + <property name="ConnectionString" value="${myConnection.connectionString}" /> + <property name="ProviderName" value="${myConnection.providerName}" /> +</object> + + + Append ".connectionString" to the connection name to get + the connection string and append ".providerName" to the + connection name to get the provider name. + + When adding a connection using Visual Studio's application + settings, your connection will be named similar to + MyNamespace.Properties.Settings.myConnection + and the corresponding variable name for the connection string + would become + MyNamespace.Properties.Settings.myConnection.connectionString. + + + + + + <literal>SpecialFolderVariableSource</literal> + + The SpecialFolderVariableSource resolves + the full path for variable names against special folders as defined + by the System.Environment.SpecialFolder + enumeration. Add it to your variable sources as: + + <object type="Spring.Objects.Factory.Config.SpecialFolderVariableSource, Spring.Core" /> + + Now you can inject the full path to the current user's + desktop, or to this machine's program files folders: + + <object id="specials" type="Example.Specials, Spring.IocQuickStart.VariableSources"> + <property name="FullPathToDesktop" value="${Desktop}" /> + <property name="FullPathToPrgramFiles" value="${ProgramFiles}" /> +</object> + + Any entry in the System.Environment.SpecialFolder + enumeration can be used as a variable name. + + + + Custom <literal>IVariableSource</literal> + implementations + + The IVariableSource is the base interface + for providing the ability to get the value of property placeholders + (name-value) pairs from a variety of sources. The IVariableSource + interface is shown below: + + public interface IVariableSource { + bool CanResolveVariable(string name); string ResolveVariable(string name); } - This is a simple contract to implement if you should decide to - create your own custom implemention. Look at the source code of the - current implementations for some inspiration if you go that route. To - register your own custom implemenation, simply configure - VariablePlaceholderConfigurer to refer to your class. + This is a simple contract to implement if you should decide to + create your own custom implemention. Look at the source code of the + current implementations for some inspiration if you go that route. + To register your own custom implemenation, simply configure + VariablePlaceholderConfigurer to refer to your + class. +