Context.State similar to Context.Items

Author: lbargaoanu

docs/13.0-Upgrade-Guide.md

@@ -16,4 +16,8 @@ Be sure to call `CreateMap` once for a source type, destination type pair. If yo
 
 ## ProjectTo runtime polymorphic mapping with Include/IncludeBase
 
-We consider this an off the beaten path feature and we don't expose it through `CreateProjection`. You can use [an extension method](https://github.com/AutoMapper/AutoMapper/search?l=C%23&q=Advanced) or `CreateMap`.
+We consider this an off the beaten path feature and we don't expose it through `CreateProjection`. You can use [an extension method](https://github.com/AutoMapper/AutoMapper/search?l=C%23&q=Advanced) or `CreateMap`.
+
+## `Context.State` similar to `Context.Items`
+
+The same pattern the framework uses to pass state to delegates. Note that `State` and `Items` are mutually exclusive per `Map` call.

docs/Custom-value-resolvers.md

@@ -127,6 +127,7 @@ This is how to setup the mapping for this custom resolver
 cfg.CreateMap<Source, Dest>()
     .ForMember(dest => dest.Foo, opt => opt.MapFrom((src, dest, destMember, context) => context.Items["Foo"]));
 ```
+Starting with version 13.0, you can use `context.State` instead, in a similar way. Note that `State` and `Items` are mutually exclusive per `Map` call.
 
 ### ForPath
 

src/AutoMapper/ApiCompatBaseline.txt

@@ -1,5 +1,8 @@
 Compat issues with assembly AutoMapper:
 CannotChangeAttribute : Attribute 'System.AttributeUsageAttribute' on 'AutoMapper.AutoMapAttribute' changed from '[AttributeUsageAttribute(1036, AllowMultiple=true)]' in the contract to '[AttributeUsageAttribute(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Struct, AllowMultiple=true)]' in the implementation.
+InterfacesShouldHaveSameMembers : Interface member 'public System.Object AutoMapper.IMappingOperationOptions.State' is present in the implementation but not in the contract.
+InterfacesShouldHaveSameMembers : Interface member 'public System.Object AutoMapper.IMappingOperationOptions.State.get()' is present in the implementation but not in the contract.
+InterfacesShouldHaveSameMembers : Interface member 'public void AutoMapper.IMappingOperationOptions.State.set(System.Object)' is present in the implementation but not in the contract.
 InterfacesShouldHaveSameMembers : Interface member 'public System.Collections.Generic.IReadOnlyCollection<AutoMapper.PropertyMapAction> AutoMapper.IProfileConfiguration.AllPropertyMapActions.get()' is present in the implementation but not in the contract.
 InterfacesShouldHaveSameMembers : Interface member 'public System.Collections.Generic.IReadOnlyCollection<System.Action<AutoMapper.PropertyMap, AutoMapper.IMemberConfigurationExpression>> AutoMapper.IProfileConfiguration.AllPropertyMapActions.get()' is present in the contract but not in the implementation.
 MembersMustExist : Member 'public System.Collections.Generic.IReadOnlyCollection<System.Action<AutoMapper.PropertyMap, AutoMapper.IMemberConfigurationExpression>> AutoMapper.IProfileConfiguration.AllPropertyMapActions.get()' does not exist in the implementation but it does exist in the contract.
@@ -17,4 +20,4 @@ CannotChangeAttribute : Attribute 'System.AttributeUsageAttribute' on 'AutoMappe
 CannotChangeAttribute : Attribute 'System.AttributeUsageAttribute' on 'AutoMapper.Configuration.Annotations.ValueConverterAttribute' changed from '[AttributeUsageAttribute(384)]' in the contract to '[AttributeUsageAttribute(AttributeTargets.Field | AttributeTargets.Property)]' in the implementation.
 CannotChangeAttribute : Attribute 'System.AttributeUsageAttribute' on 'AutoMapper.Configuration.Annotations.ValueResolverAttribute' changed from '[AttributeUsageAttribute(384)]' in the contract to '[AttributeUsageAttribute(AttributeTargets.Field | AttributeTargets.Property)]' in the implementation.
 TypeCannotChangeClassification : Type 'AutoMapper.Execution.TypeMapPlanBuilder' is a 'ref struct' in the implementation but is a 'struct' in the contract.
-Total Issues: 18
+Total Issues: 21

src/AutoMapper/Configuration/IMappingOperationOptions.cs

@@ -1,30 +1,31 @@
 namespace AutoMapper;
-
 using StringDictionary = Dictionary<string, object>;
 /// <summary>
 /// Options for a single map operation
 /// </summary>
 public interface IMappingOperationOptions
 {
     Func<Type, object> ServiceCtor { get; }
-
     /// <summary>
     /// Construct services using this callback. Use this for child/nested containers
     /// </summary>
     /// <param name="constructor"></param>
     void ConstructServicesUsing(Func<Type, object> constructor);
-
     /// <summary>
-    /// Add context items to be accessed at map time inside an <see cref="IValueResolver{TSource, TDestination, TMember}"/> or <see cref="ITypeConverter{TSource, TDestination}"/>
+    /// Add state to be accessed at map time inside an <see cref="IValueResolver{TSource, TDestination, TMember}"/> or <see cref="ITypeConverter{TSource, TDestination}"/>.
+    /// Mutually exclusive with <see cref="Items"/> per Map call.
     /// </summary>
-    Dictionary<string, object> Items { get; }
-
+    object State { get; set; }
+    /// <summary>
+    /// Add context items to be accessed at map time inside an <see cref="IValueResolver{TSource, TDestination, TMember}"/> or <see cref="ITypeConverter{TSource, TDestination}"/>.
+    /// Mutually exclusive with <see cref="State"/> per Map call.
+    /// </summary>
+    StringDictionary Items { get; }
     /// <summary>
     /// Execute a custom function to the source and/or destination types before member mapping
     /// </summary>
     /// <param name="beforeFunction">Callback for the source/destination types</param>
     void BeforeMap(Action<object, object> beforeFunction);
-
     /// <summary>
     /// Execute a custom function to the source and/or destination types after member mapping
     /// </summary>
@@ -38,7 +39,6 @@ public interface IMappingOperationOptions<TSource, TDestination> : IMappingOpera
     /// </summary>
     /// <param name="beforeFunction">Callback for the source/destination types</param>
     void BeforeMap(Action<TSource, TDestination> beforeFunction);
-
     /// <summary>
     /// Execute a custom function to the source and/or destination types after member mapping
     /// </summary>
@@ -47,10 +47,10 @@ public interface IMappingOperationOptions<TSource, TDestination> : IMappingOpera
 }
 public class MappingOperationOptions<TSource, TDestination> : IMappingOperationOptions<TSource, TDestination>
 {
-    private StringDictionary _items;
     public MappingOperationOptions(Func<Type, object> serviceCtor) => ServiceCtor = serviceCtor;
     public Func<Type, object> ServiceCtor { get; private set; }
-    public Dictionary<string, object> Items => _items ??= new StringDictionary();
+    public StringDictionary Items => (StringDictionary) (State ??= new StringDictionary());
+    public object State { get; set; }
     public Action<TSource, TDestination> BeforeMapAction { get; protected set; }
     public Action<TSource, TDestination> AfterMapAction { get; protected set; }
     public void BeforeMap(Action<TSource, TDestination> beforeFunction) => BeforeMapAction = beforeFunction;

src/AutoMapper/ResolutionContext.cs

@@ -15,7 +15,13 @@ internal ResolutionContext(IInternalRuntimeMapper mapper, IMappingOperationOptio
         _options = options;
     }
     /// <summary>
+    /// The state passed in the options of the Map call.
+    /// Mutually exclusive with <see cref="Items"/> per Map call.
+    /// </summary>
+    public object State => _options?.State;
+    /// <summary>
     /// The items passed in the options of the Map call.
+    /// Mutually exclusive with <see cref="State"/> per Map call.
     /// </summary>
     public Dictionary<string, object> Items
     {

src/UnitTests/ContextItems.cs

@@ -1,4 +1,30 @@
 namespace AutoMapper.UnitTests;
+public class When_mapping_with_context_state
+{
+    public class Source
+    {
+        public int Value { get; set; }
+    }
+    public class Dest
+    {
+        public int Value { get; set; }
+    }
+    public class ContextResolver : IMemberValueResolver<Source, Dest, int, int>
+    {
+        public int Resolve(Source src, Dest d, int source, int dest, ResolutionContext context) => source + (int)context.State;
+    }
+    [Fact]
+    public void Should_use_value_passed_in()
+    {
+        var config = new MapperConfiguration(cfg =>
+        {
+            cfg.CreateMap<Source, Dest>()
+                .ForMember(d => d.Value, opt => opt.MapFrom<ContextResolver, int>(src => src.Value));
+        });
+        var dest = config.CreateMapper().Map<Source, Dest>(new Source { Value = 5 }, opt => { opt.State = 10; });
+        dest.Value.ShouldBe(15);
+    }
+}
 public class Context_try_get_items : AutoMapperSpecBase
 {
     protected override MapperConfiguration CreateConfiguration() => new(c => c.CreateMap<int, int>().ConvertUsing((s, _, c) =>