From: <jer...@us...> - 2007-04-01 18:18:22
|
Revision: 35 http://structuremap.svn.sourceforge.net/structuremap/?rev=35&view=rev Author: jeremydmiller Date: 2007-04-01 11:18:16 -0700 (Sun, 01 Apr 2007) Log Message: ----------- Adding NDoc style comments to the DSL classes Modified Paths: -------------- trunk/Source/StructureMap/Configuration/DSL/ChildInstanceExpression.cs trunk/Source/StructureMap/Configuration/DSL/CreatePluginFamilyExpression.cs trunk/Source/StructureMap/Configuration/DSL/InstanceDefaultExpression.cs trunk/Source/StructureMap/Configuration/DSL/InstanceExpression.cs trunk/Source/StructureMap/Configuration/DSL/LiteralExpression.cs trunk/Source/StructureMap/Configuration/DSL/ProfileExpression.cs trunk/Source/StructureMap/Configuration/DSL/PropertyExpression.cs trunk/Source/StructureMap/Configuration/DSL/PrototypeExpression.cs trunk/Source/StructureMap/Configuration/DSL/Registry.cs trunk/Source/StructureMap/Configuration/DSL/ScanAssembliesExpression.cs trunk/Source/StructureMap/Configuration/DSL/UserControlExpression.cs trunk/Source/StructureMap/StructureMapConfiguration.cs Modified: trunk/Source/StructureMap/Configuration/DSL/ChildInstanceExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/ChildInstanceExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/ChildInstanceExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -4,6 +4,10 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Part of the Fluent Interface, represents a nonprimitive argument to a + /// constructure function + /// </summary> public class ChildInstanceExpression : IExpression { private readonly InstanceExpression _instance; @@ -28,7 +32,11 @@ _childType = childType; } - + /// <summary> + /// Use a previously configured and named instance for the child + /// </summary> + /// <param name="instanceKey"></param> + /// <returns></returns> public InstanceExpression IsNamedInstance(string instanceKey) { MemoryInstanceMemento child = MemoryInstanceMemento.CreateReferencedInstanceMemento(instanceKey); @@ -37,6 +45,11 @@ return _instance; } + /// <summary> + /// Start the definition of a child instance by defining the concrete type + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public InstanceExpression IsConcreteType<T>() { Type pluggedType = typeof (T); @@ -78,6 +91,12 @@ set { _childType = value; } } + /// <summary> + /// Registers a configured instance to use as the argument to the parent's + /// constructor + /// </summary> + /// <param name="child"></param> + /// <returns></returns> public InstanceExpression Is(InstanceExpression child) { if (child.PluggedType != null && _childType != null) Modified: trunk/Source/StructureMap/Configuration/DSL/CreatePluginFamilyExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/CreatePluginFamilyExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/CreatePluginFamilyExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -8,6 +8,9 @@ { public delegate void AlterPluginFamilyDelegate(PluginFamily family); + /// <summary> + /// Represents the parameters for creating instances of a given Type + /// </summary> public class CreatePluginFamilyExpression : IExpression { private Type _pluginType; @@ -42,6 +45,11 @@ graph.Assemblies.Add(assembly); } + /// <summary> + /// Sets the default instance of a Type to the definition represented by builder + /// </summary> + /// <param name="builder"></param> + /// <returns></returns> public CreatePluginFamilyExpression TheDefaultIs(IMementoBuilder builder) { builder.ValidatePluggability(_pluginType); @@ -57,6 +65,13 @@ return this; } + /// <summary> + /// Convenience method that sets the default concrete type of the PluginType. Type T + /// can only accept types that do not have any primitive constructor arguments. + /// StructureMap has to know how to construct all of the constructor argument types. + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public CreatePluginFamilyExpression TheDefaultIsConcreteType<T>() { ExpressionValidator.ValidatePluggabilityOf(typeof (T)).IntoPluginType(_pluginType); @@ -70,6 +85,12 @@ return this; } + /// <summary> + /// Sets the object creation of the instances of the PluginType. For example: PerRequest, + /// Singleton, ThreadLocal, HttpContext, or Hybrid + /// </summary> + /// <param name="scope"></param> + /// <returns></returns> public CreatePluginFamilyExpression CacheBy(InstanceScope scope) { _alterations.Add(delegate(PluginFamily family) @@ -81,6 +102,10 @@ return this; } + /// <summary> + /// Convenience method to mark a PluginFamily as a Singleton + /// </summary> + /// <returns></returns> public CreatePluginFamilyExpression AsSingletons() { _alterations.Add( Modified: trunk/Source/StructureMap/Configuration/DSL/InstanceDefaultExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/InstanceDefaultExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/InstanceDefaultExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -3,6 +3,9 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Use to express the instance of a PluginType for the containing Profile + /// </summary> public class InstanceDefaultExpression { private readonly Type _pluginType; @@ -16,6 +19,11 @@ _parent = parent; } + /// <summary> + /// Use a named, preconfigured instance as the default instance for this profile + /// </summary> + /// <param name="instanceKey"></param> + /// <returns></returns> public ProfileExpression UseNamedInstance(string instanceKey) { _instanceKey = instanceKey; @@ -46,6 +54,11 @@ } } + /// <summary> + /// Define the default instance of the PluginType for the containing Profile + /// </summary> + /// <param name="mementoBuilder"></param> + /// <returns></returns> public ProfileExpression Use(IMementoBuilder mementoBuilder) { _mementoBuilder = mementoBuilder; Modified: trunk/Source/StructureMap/Configuration/DSL/InstanceExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/InstanceExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/InstanceExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -3,6 +3,9 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Used to define an Instance in code + /// </summary> public class InstanceExpression : MementoBuilder<InstanceExpression> { private Type _pluggedType; @@ -53,12 +56,24 @@ } + /// <summary> + /// Start the definition of a primitive argument to a constructor argument + /// </summary> + /// <param name="propertyName"></param> + /// <returns></returns> public PropertyExpression WithProperty(string propertyName) { return new PropertyExpression(this, _memento, propertyName); } - + /// <summary> + /// Starts the definition of a child instance specifying the argument name + /// in the case of a constructor function that consumes more than one argument + /// of type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="propertyName"></param> + /// <returns></returns> public ChildInstanceExpression Child<T>(string propertyName) { ChildInstanceExpression child = new ChildInstanceExpression(this, _memento, propertyName); @@ -68,6 +83,11 @@ return child; } + /// <summary> + /// Start the definition of a child instance for type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public ChildInstanceExpression Child<T>() { string propertyName = findPropertyName<T>(); @@ -104,7 +124,9 @@ return new InstanceTypeExpression(this); } - + /// <summary> + /// Helper class to capture the actual concrete type of an Instance + /// </summary> public class InstanceTypeExpression { private readonly InstanceExpression _parent; @@ -114,12 +136,22 @@ _parent = parent; } + /// <summary> + /// Use type T for the concrete type of an instance + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public InstanceExpression UsingConcreteType<T>() { _parent._pluggedType = typeof (T); return _parent; } + /// <summary> + /// Use a named Plugin type denoted by a [Pluggable("Key")] attribute + /// </summary> + /// <param name="concreteKey"></param> + /// <returns></returns> public InstanceExpression UsingConcreteTypeNamed(string concreteKey) { _parent._memento.ConcreteKey = concreteKey; Modified: trunk/Source/StructureMap/Configuration/DSL/LiteralExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/LiteralExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/LiteralExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -3,6 +3,10 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Small helper class to represent an object to be plugged into a PluginType as is + /// </summary> + /// <typeparam name="T"></typeparam> public class LiteralExpression<T> : MementoBuilder<LiteralExpression<T>> { private readonly T _target; Modified: trunk/Source/StructureMap/Configuration/DSL/ProfileExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/ProfileExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/ProfileExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -3,6 +3,9 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Expression class to help define a runtime Profile + /// </summary> public class ProfileExpression : IExpression { private readonly string _profileName; @@ -28,6 +31,11 @@ } } + /// <summary> + /// Starts the definition of the default instance for the containing Profile + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public InstanceDefaultExpression For<T>() { InstanceDefaultExpression defaultExpression = new InstanceDefaultExpression(typeof (T), this); Modified: trunk/Source/StructureMap/Configuration/DSL/PropertyExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/PropertyExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/PropertyExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -2,6 +2,9 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Defines the value of a primitive argument to a constructur argument + /// </summary> public class PropertyExpression { private readonly InstanceExpression _instance; @@ -15,12 +18,23 @@ _propertyName = propertyName; } + /// <summary> + /// Sets the value of the constructor argument + /// </summary> + /// <param name="propertyValue"></param> + /// <returns></returns> public InstanceExpression EqualTo(object propertyValue) { _memento.SetProperty(_propertyName, propertyValue.ToString()); return _instance; } + /// <summary> + /// Sets the value of the constructor argument to the key/value in the + /// AppSettings + /// </summary> + /// <param name="appSettingKey"></param> + /// <returns></returns> public InstanceExpression EqualToAppSetting(string appSettingKey) { string propertyValue = ConfigurationManager.AppSettings[appSettingKey]; Modified: trunk/Source/StructureMap/Configuration/DSL/PrototypeExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/PrototypeExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/PrototypeExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -3,6 +3,10 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Sets up a Prototype instance of type T + /// </summary> + /// <typeparam name="T"></typeparam> public class PrototypeExpression<T> : MementoBuilder<PrototypeExpression<T>> { private readonly T _prototype; Modified: trunk/Source/StructureMap/Configuration/DSL/Registry.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/Registry.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/Registry.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -48,7 +48,12 @@ ConfigurePluginGraph(_graph); } - + /// <summary> + /// Direct StructureMap to build instances of type T, and look for concrete classes + /// marked with the [Pluggable] attribute that implement type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public CreatePluginFamilyExpression BuildInstancesOf<T>() { CreatePluginFamilyExpression expression = new CreatePluginFamilyExpression(typeof (T)); @@ -64,6 +69,11 @@ return new InstanceManager(_graph); } + /// <summary> + /// Starts an instance definition of type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public InstanceExpression.InstanceTypeExpression AddInstanceOf<T>() { InstanceExpression expression = new InstanceExpression(typeof (T)); @@ -71,22 +81,45 @@ return expression.TypeExpression(); } + /// <summary> + /// Convenience method to start the definition of an instance of type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public static InstanceExpression.InstanceTypeExpression Instance<T>() { InstanceExpression expression = new InstanceExpression(typeof (T)); return expression.TypeExpression(); } + /// <summary> + /// Convenience method to register a prototype instance + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="prototype"></param> + /// <returns></returns> public static PrototypeExpression<T> Prototype<T>(T prototype) { return new PrototypeExpression<T>(prototype); } + /// <summary> + /// Convenience method to register a preconfigured instance of type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="instance"></param> + /// <returns></returns> public static LiteralExpression<T> Object<T>(T instance) { return new LiteralExpression<T>(instance); } + /// <summary> + /// Registers a preconfigured instance + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="target"></param> + /// <returns></returns> public LiteralExpression<T> AddInstanceOf<T>(T target) { LiteralExpression<T> literal = new LiteralExpression<T>(target); @@ -95,6 +128,12 @@ return literal; } + /// <summary> + /// Add a preconfigured instance as a Prototype + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="prototype"></param> + /// <returns></returns> public PrototypeExpression<T> AddPrototypeInstanceOf<T>(T prototype) { PrototypeExpression<T> expression = new PrototypeExpression<T>(prototype); @@ -103,11 +142,22 @@ return expression; } + /// <summary> + /// convenience method for a UserControl + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="url"></param> + /// <returns></returns> public static UserControlExpression LoadUserControlFrom<T>(string url) { - return new UserControlExpression(typeof(T), url); + return new UserControlExpression(typeof (T), url); } + /// <summary> + /// Starts the definition of a new Profile + /// </summary> + /// <param name="profileName"></param> + /// <returns></returns> public ProfileExpression CreateProfile(string profileName) { ProfileExpression expression = new ProfileExpression(profileName); @@ -131,9 +181,15 @@ return (type.GetConstructor(new Type[0]) != null); } + /// <summary> + /// Registers a UserControl as an instance + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="url"></param> + /// <returns></returns> public UserControlExpression LoadControlFromUrl<T>(string url) { - UserControlExpression expression = new UserControlExpression(typeof(T), url); + UserControlExpression expression = new UserControlExpression(typeof (T), url); addExpression(expression); return expression; Modified: trunk/Source/StructureMap/Configuration/DSL/ScanAssembliesExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/ScanAssembliesExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/ScanAssembliesExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -6,6 +6,10 @@ namespace StructureMap.Configuration.DSL { + /// <summary> + /// Expression that directs StructureMap to scan the named assemblies + /// for [PluginFamily] and [Plugin] attributes + /// </summary> public class ScanAssembliesExpression : IExpression { private List<AssemblyGraph> _assemblies = new List<AssemblyGraph>(); Modified: trunk/Source/StructureMap/Configuration/DSL/UserControlExpression.cs =================================================================== --- trunk/Source/StructureMap/Configuration/DSL/UserControlExpression.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/Configuration/DSL/UserControlExpression.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -1,6 +1,4 @@ using System; -using System.Collections.Generic; -using System.Text; using StructureMap.Graph; namespace StructureMap.Configuration.DSL @@ -44,4 +42,4 @@ // no-op } } -} +} \ No newline at end of file Modified: trunk/Source/StructureMap/StructureMapConfiguration.cs =================================================================== --- trunk/Source/StructureMap/StructureMapConfiguration.cs 2007-03-30 14:26:24 UTC (rev 34) +++ trunk/Source/StructureMap/StructureMapConfiguration.cs 2007-04-01 18:18:16 UTC (rev 35) @@ -1,6 +1,5 @@ using System; using System.Collections.Generic; -using System.Configuration; using System.IO; using System.Xml; using StructureMap.Configuration; @@ -48,7 +47,10 @@ return configPath; } - + /// <summary> + /// Clears StructureMapConfiguration of all configuration options. Returns StructureMap + /// to only using the default StructureMap.config file for configuration. + /// </summary> public static void ResetAll() { _collection = new ConfigurationParserCollection(); @@ -58,6 +60,10 @@ _startUp = null; } + /// <summary> + /// Builds a PluginGraph object for the current configuration. Used by ObjectFactory. + /// </summary> + /// <returns></returns> public static PluginGraph GetPluginGraph() { if (_startUp != null) @@ -73,33 +79,48 @@ { if (_pullConfigurationFromAppConfig) { - _collection.IncludeNode(delegate() - { - - return StructureMapConfigurationSection.GetStructureMapConfiguration(); - }); + _collection.IncludeNode( + delegate() { return StructureMapConfigurationSection.GetStructureMapConfiguration(); }); } ConfigurationParser[] parsers = _collection.GetParsers(); return new PluginGraphBuilder(parsers, _registries.ToArray()); } + /// <summary> + /// Creates a PluginGraphReport that details the current configuration along with any problems found with the configuration. + /// The PluginGraphReport can be used to troubleshoot problems with the StructureMap configuration. + /// </summary> + /// <returns></returns> public static PluginGraphReport GetDiagnosticReport() { PluginGraphBuilder builder = createBuilder(); return builder.Report; } + /// <summary> + /// Directs StructureMap to include Xml configuration information from a separate file + /// </summary> + /// <param name="filename"></param> public static void IncludeConfigurationFromFile(string filename) { _collection.IncludeFile(filename); } + /// <summary> + /// Register a FetchNodeDelegate delegate to retrieve a <StructureMap> + /// node to include Xml configuration + /// </summary> + /// <param name="fetcher"></param> public static void IncludeConfigurationFrom(FetchNodeDelegate fetcher) { _collection.IncludeNode(fetcher); } + /// <summary> + /// Programmatically adds a <StructureMap> node containing Xml configuration + /// </summary> + /// <param name="node"></param> public static void IncludeConfigurationFromNode(XmlNode node) { _collection.IncludeNode( @@ -107,6 +128,10 @@ ); } + /// <summary> + /// Flag to enable or disable the usage of the default StructureMap.config + /// If set to false, StructureMap will not look for a StructureMap.config file + /// </summary> public static bool UseDefaultStructureMapConfigFile { get { return _collection.UseDefaultFile; } @@ -124,6 +149,10 @@ } } + /// <summary> + /// Programmatically determine Assembly's to be scanned for attribute configuration + /// </summary> + /// <returns></returns> public static ScanAssembliesExpression ScanAssemblies() { ScanAssembliesExpression expression = new ScanAssembliesExpression(); @@ -132,51 +161,77 @@ return expression; } + /// <summary> + /// Direct StructureMap to create instances of Type T + /// </summary> + /// <typeparam name="T">The Type to build</typeparam> + /// <returns></returns> public static CreatePluginFamilyExpression BuildInstancesOf<T>() { return _registry.BuildInstancesOf<T>(); } + /// <summary> + /// Adds a new configured instance of Type T + /// </summary> + /// <typeparam name="T"></typeparam> + /// <returns></returns> public static InstanceExpression.InstanceTypeExpression AddInstanceOf<T>() { return _registry.AddInstanceOf<T>(); } - public static InstanceExpression.InstanceTypeExpression Instance<T>() - { - return Registry.Instance<T>(); - } - public static PrototypeExpression<T> Prototype<T>(T prototype) - { - return new PrototypeExpression<T>(prototype); - } - - public static LiteralExpression<T> Object<T>(T instance) - { - return new LiteralExpression<T>(instance); - } - + /// <summary> + /// Adds a preconfigured instance of Type T to StructureMap. When this instance is requested, + /// StructureMap will always return the original object. + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="target"></param> + /// <returns></returns> public static LiteralExpression<T> AddInstanceOf<T>(T target) { return _registry.AddInstanceOf(target); } + /// <summary> + /// Adds a Prototype (GoF) instance of Type T. The actual prototype object must implement the + /// ICloneable interface. When this instance of T is requested, StructureMap will + /// return a cloned copy of the originally registered prototype object. + /// </summary> + /// <typeparam name="T"></typeparam> + /// <param name="prototype"></param> + /// <returns></returns> public static PrototypeExpression<T> AddPrototypeInstanceOf<T>(T prototype) { return _registry.AddPrototypeInstanceOf(prototype); } + /// <summary> + /// Starts the definition of a configuration Profile. + /// </summary> + /// <param name="profileName"></param> + /// <returns></returns> public static ProfileExpression CreateProfile(string profileName) { return _registry.CreateProfile(profileName); } + /// <summary> + /// Directs StructureMap to use a Registry class to construct the + /// PluginGraph + /// </summary> + /// <param name="registry"></param> public static void AddRegistry(Registry registry) { _registries.Add(registry); } + /// <summary> + /// Controls the reporting and diagnostics of StructureMap on + /// startup + /// </summary> + /// <returns></returns> public static IStartUp OnStartUp() { if (_startUp == null) @@ -186,5 +241,26 @@ return _startUp; } + + public static void TheDefaultProfileIs(string profileName) + { + DefaultProfileExpression expression = new DefaultProfileExpression(profileName); + _registry.addExpression(expression); + } + + internal class DefaultProfileExpression : IExpression + { + private readonly string _profileName; + + public DefaultProfileExpression(string profileName) + { + _profileName = profileName; + } + + public void Configure(PluginGraph graph) + { + graph.DefaultManager.DefaultProfileName = _profileName; + } + } } } \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |