diff --git a/doc/reference/src/images/applicationsettings.png b/doc/reference/src/images/applicationsettings.png new file mode 100644 index 00000000..997d7a97 Binary files /dev/null and b/doc/reference/src/images/applicationsettings.png differ diff --git a/doc/reference/src/objects.xml b/doc/reference/src/objects.xml index 3fd88644..c135e961 100644 --- a/doc/reference/src/objects.xml +++ b/doc/reference/src/objects.xml @@ -3922,7 +3922,7 @@ public sealed class Font : MarshalByRefObject, ICloneable, ISerializable, IDispo <object id="exampleInitObject" type="Examples.ExampleObject" init-method="init"/> - [C#] + [C#] public class ExampleObject { public void Init() @@ -4607,7 +4607,7 @@ DEBUG - MovieApp Done. Customizing configuration metadata with - ObjectFactoryPostProcessors + IObjectFactoryPostProcessors The next extension point that we will look at is the Spring.Objects.Factory.Config.IObjectFactoryPostProcessor. @@ -4658,15 +4658,15 @@ DEBUG - MovieApp Done. An object factory post-processor is executed manually (in the case - of a IObjectFactory) or automatically (in the case of an - IApplicationContext) to apply changes of some sort to the configuration - metadata that defines a container. Spring.NET includes a number of - pre-existing object factory post-processors, such as - PropertyResourceConfigurer and + of a IObjectFactory) or automatically (in the case of + an IApplicationContext) to apply changes of some sort + to the configuration metadata that defines a container. Spring.NET + includes a number of pre-existing object factory post-processors, such + as PropertyResourceConfigurer and PropertyPlaceHolderConfigurer, both described below - and ObjectNameAutoProxyCreator, which is very useful for wrapping other - objects transactionally or with any other kind of proxy, as described - later in this manual. + and ObjectNameAutoProxyCreator, which is very useful + for wrapping other objects transactionally or with any other kind of + proxy, as described later in this manual. In an IObjectFactory, the process of applying an IObjectFactoryPostProcessor is manual, and will be @@ -4717,9 +4717,9 @@ cfg.PostProcessObjectFactory(factory); excellent solution when you want to externalize a few properties from a file containing object definitions. This is useful to allow the person deploying an application to customize environment specific - properties (for example database configuration strings, usernames, and - passwords), without the complexity or risk of modifying the main XML - definition file or files for the container. + properties (for example database configuration strings, user names, + and passwords), without the complexity or risk of modifying the main + XML definition file or files for the container. Variable substitution is performed on simple property values, lists, dictionaries, sets, constructor values, object type name, and @@ -4741,10 +4741,10 @@ cfg.PostProcessObjectFactory(factory); with a database connection and also a value for the maximum number of results to return in a query. Instead of hard coding the values into the main Spring.NET configuration file we use place holders, in the - NAnt style of ${variableName}, and obtain their values from - NameValueSections in the standard .NET application configuration file. - The Spring.NET configuration file looks like: <configuration> + NAnt style of ${variableName}, and obtain their + values from NameValueSections in the standard .NET + application configuration file. The Spring.NET configuration file + looks like: <configuration> <configSections> <sectionGroup name="spring"> @@ -4770,9 +4770,9 @@ cfg.PostProcessObjectFactory(factory); </configuration> - Notice the presence of two NameValueSections in the - configuration file. These name value pairs will be referred to in the - Spring.NET configuration file. In this example we are using an + Notice the presence of two NameValueSections + in the configuration file. These name value pairs will be referred to + in the Spring.NET configuration file. In this example we are using an embedded assembly resource for the location of the Spring.NET configuration file so as to reduce the chance of accidental tampering in deployment. This Spring.NET configuration file is shown @@ -4783,29 +4783,29 @@ cfg.PostProcessObjectFactory(factory); xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/xsd/spring-objects.xsd" > - <object name="productDao" type="DaoApp.SimpleProductDao, DaoApp "> - <property name="maxResults" value="${maxResults}"/> - <property name="dbConnection" ref="myConnection"/> - </object> - - <object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data"> - <property name="connectionstring" value="${connection.string}"/> - </object> + <object name="productDao" type="DaoApp.SimpleProductDao, DaoApp "> + <property name="maxResults" value="${maxResults}"/> + <property name="dbConnection" ref="myConnection"/> + </object> + + <object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data"> + <property name="connectionstring" value="${connection.string}"/> + </object> - <object name="appConfigPropertyHolder" - type="Spring.Objects.Factory.Config.PropertyPlaceholderConfigurer, Spring.Core"> + <object name="appConfigPropertyHolder" + type="Spring.Objects.Factory.Config.PropertyPlaceholderConfigurer, Spring.Core"> + <property name="configSections"> + <value>DaoConfiguration,DatabaseConfiguration</value> + </property> + </object> - <property name="configSections"> - <value>DaoConfiguration,DatabaseConfiguration</value> - </property> - - </object> </objects> The values of ${maxResults} and ${connection.string} match the key names used in - the two NameValueSectionHandlers DaoConfiguration - and DatabaseConfiguration. The + the two NameValueSectionHandlers + DaoConfiguration and + DatabaseConfiguration. The PropertyPlaceholderConfigurer refers to these two sections via a comma delimited list of section names in the configSections property. If you are using section @@ -4846,8 +4846,10 @@ cfg.PostProcessObjectFactory(factory); If the class is unable to be resolved at runtime to a valid type, resolution of the object will fail once it is about to be - created (which is during the PreInstantiateSingletons() phase of an - ApplicationContext for a non-lazy-init object.) + created (which is during the + PreInstantiateSingletons() phase of an + ApplicationContext for a non-lazy-init + object.) Similarly you can replace 'ref' and 'expression' metadata, as shown below @@ -4959,51 +4961,18 @@ cfg.PostProcessObjectFactory(factory); - IVariableSource + Example: The + <literal>VariablePlaceholderConfigurer</literal> - 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. Out of the box, Spring.NET supports a - number of variable sources that allow users to obtain variable values - from .NET config files, java-style property files, environment - variables, command line arguments and the registry and the new - connection strings configuration section in .NET 2.0. The list of - implementing classes is listed below. Please refer to the SDK - documentation for more information. - - - - ConfigSectionVariableSource - - - - PropertyFileVariableSource - - - - EnvironmentVariableSource - - - - CommandLineArgsVariableSource - - - - RegistryVariableSource - - - - SpecialFolderVariableSource - - - - ConnectionStringsVariableSource - - - - ConfigurableVariableSource - - + The VariablePlaceholderConfigurer is an + evolution of the PropertyPlaceHolderConfigurer. Out + of the box, Spring.NET supports a number of variable sources that + allow users to obtain variable values from .NET configuration files, + Java-style property files, environment variables, command line + arguments, the registry and the new connection strings configuration + section in .NET 2.0. It is possible to add your own variable sources + to a VariablePlaceholderConfigurer by implementing + the IVariableSource interface. You use this by defining an instance of Spring.Objects.Factory.Config.VariablePlaceholderConfigurer @@ -5015,35 +4984,303 @@ cfg.PostProcessObjectFactory(factory); property defined in multiple IVariableSource implementations, the first one in the list that contains the property value will be used. <object type="Spring.Objects.Factory.Config.VariablePlaceholderConfigurer, Spring.Core"> - <property name="VariableSources"> - <list> - <object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core"> - <property name="Location" value="~\application.properties" /> - <property name="IgnoreMissingResources" value="true"/> - </object> - <object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> - <property name="SectionNames" value="CryptedConfiguration" /> - </object> - </list> - </property> -</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 + <property name="VariableSources"> + <list> + <object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core"> + <property name="Location" value="~\application.properties" /> + </object> + <object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="CryptedConfiguration" /> + </object> + </list> + </property> +</object> - 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 your + 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> + +<!-- VariableSource configuration: --> +<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="DonConfiguration" /> +</object> + +<!-- consume variables: --> +<object type="Example.Person, Spring.IocQuickStart.VariableSources"> + <property name="Name" value="${don_name}" /> + <property name="Age" value="${don_age}" /> +</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 .NET's application settings and user settings. Assuming your + application's root namespace is MyApp, 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/MyApp.Properties.Settings" /> +</object> + +<!-- From .net's UserSettings: --> +<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"> + <property name="SectionNames" value="userSettings/MyApp.Properties.Settings" /> +</object> + + + If you configured your application settings as such: + + + + + + Then you can use ${peggy_name}, + ${peggy_age}, + &{peter_name} and + ${peter_age} as variables in your object + definitions. They will be retrieved using the appropriate + scope. + Changes to user settings during the lifetime of your + application context will not be be visible + to the ConfigSectionVariableSource. Although + variables based on user settings will be resolved using user + scope, variables will only be resolved when the + VariablePlaceholderConfigurer is + initialized: that is when the context is created. Any + object (including lazy-loaded singletons and non-singletons) you + retrieve from the context will have the variable values injected + as they were when the context was loaded. + + + + + <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 the following lines: + + joan_name=Joan Harris +joan_age=35 + + You can use the ${joan_name} and + ${joan_age} variables in your object definitions + if you configure the following variable source: + + <object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core"> + <property name="Location" value="~\application.properties" /> <!-- specify a single ... --> + <property name="Locations" value="~\file1.properties,~\file2.properties" /> <!-- or multiple locations --> + <property name="IgnoreMissingResources" value="true"/> +</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 + the next variable source(s) of the + VariablePlaceholderConfigurer. + + + Within PropertyFileVariableSources, + precedence rules differ from the configuration of + VariableSources in the + VariablePlaceholderConfigurer. When the same + property occurs more than once in a property file, the value of the + last entry will be used. Same goes for + specifying the same variable in more than one location in a single + PropertyFileVariableSource: the entry from the + last file will be used. + + + + <literal>ConfigurableVariableSource</literal> + + A ConfigurableVariableSource allows you to + define variables in-line 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 your application + myapp: + + myapp /roger_name:"Roger Sterling" /roger_age:57 + + The following variable source configuration allows you to use + ${roger_name} and ${roger_age} + as variables: + + <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 and freddy_age, + 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> + + + The key must be present in the registry when the + configuration is read, otherwise an + ObjectCreationException will be + thrown. + + + + + <literal>EnvironmentVariableSource</literal> + + You can configure an + EnvironmentVariableSource to retrieve variables + from environment variables available through .NET's + System.Environment class: + + <object type="Spring.Objects.Factory.Config.EnvironmentVariableSource, Spring.Core" /> + + + To resolve a variable named ${ken_name}, + the EnvironmentVariableSource will directly call + System.Environment.GetEnvironmentVariable("ken_name"). + + + + <literal>ConnectionStringsVariableSource</literal> + + Visual Studio has support for configuring database connection + strings in a connectionStrings section in your + application configuration file. You can retrieve these connections + as variables by configuring a + ConnectionStringsVariableSource: + + <object type="Spring.Objects.Factory.Config.ConnectionStringsVariableSource, Spring.Core" /> + + Assuming the following connection strings 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 user interface, your connection will be named similar + to MyApp.Properties.Settings.myConnection and + the corresponding variable name for the connection string would + become + MyApp.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 implementation. Look at the source code of + the current implementations for some inspiration if you go that + route. To register your own custom implementation, simply configure + VariablePlaceholderConfigurer to refer to your + class. +