XML comments and PostBuildAction

README.md

@@ -23,10 +23,11 @@ Install-Package BuilderGenerator
 After installation, create a partial class to define your builder in. Decorate it with the ```BuilderFor``` attribute, specifying the type of class that the builder is meant to build (e.g. ```[BuilderFor(typeof(Foo))]```. Define any factory and helper methods in this partial class. Meanwhile, another partial class definition will be auto-generated which contains all the "boring" parts such as the backing fields and "with" methods.
 
 ## Version History ##
-- v3.0.3-alpha
+- v3.0.7
   - Properties marked as Obsolete are ignored by the Builders
   - The "Object" property is now named for the Builder's target class
   - Solved the "Duplicate Definition" problem (41)
+  - PostBuildAction replaces PostProcess method
 
 - v2.4.0
     - Test code reorganization

docs/index.md

@@ -4,11 +4,16 @@ This NuGet package automates the generation of object builders for testing. It g
 
 With the v3.0 release, there are a few important breaking changes.
 
-Integration tests for .NET 6 & 7 has been dropped. Like all source generators, the Builder generator targets .netstandard 2.0, and should work with any modern .NET version, so this change only affects developers contributing to the project itself.
+Builders previously exposed an "Object" property and accompanying "WithObject" method to allow you to directly set the instance to be returned from the builder. This is not a common scenario. It's also uncommon for a class to have a property called "Object", but it _does_ occasionally happen. In version 3, the object property and its With method are now named for the Builder's target class. A `FooBuilder` class will now have a property called `Foo` and associated `WithFoo` methods. Otherwise, this functionality is unchanged.
 
-Builders previously exposed an "Object" property and accompanying "WithObject" method to allow you to directly set the instance to be returned from the builder. This is not a common scenario. It's also uncommon for a class to have a property called "Object", but it _does_ occasionally happen. In version 3, the object property and its With method are now named for the Builder's target class. A `FooBuilder` will now have a property called `Foo`, and a `WithFoo` method. Otherwise, this functionality is unchanged.
+Builders previously had a virtual "PostProcess" method on the base class which could be overridden to perform additional operations the first time the builder's `Build` method is called. Unlike the other properties, there was previously no way to override the `PostProcess` method. Any difference in behavior from one factory method to another had to be written directly into the `PostProcess` method itself. In version 3, this single method has been replaced with a new `WithPostBuildAction` method that takes an Action and returns a reference to the Builder so that it chains just like any other "With" method. This allows a factory method like "Typical" to throw out and replace the post-build action established by a lower level like "Simple". To migrate existing `PostProcess` actions, just add a call to `WithPostBuildAction` that calls your existing `PostProcess` method, and remove its `override` keyword.
 
-Builders now ignore properties marked with the `Obsolete` attribute by default, although this can be overridden in the `BuilderForAttribute` constructor if needed.
+Builders now ignore properties marked with the `Obsolete` attribute by default, although this can be overridden with the `includeObsolete` parameter to the `BuilderForAttribute` constructor if needed. This is similar to the existing `includeInternals` parameter.
+
+## Contributors
+Thank you to the following developers for their contributions to the project.
+- Michiel van Oosterhout for the Object -> ClassName suggestion.
+- lucavoit for his PR to copy XML comment header contents to the builder With methods.
 
 ## Installation
 

src/BuilderGenerator.Core/Builder.cs

@@ -8,8 +8,4 @@ public abstract class Builder<T> where T : class
     /// <summary>Builds the object instance.</summary>
     /// <returns>The constructed object.</returns>
     public abstract T Build();
-
-    protected virtual void PostProcess(T value)
-    {
-    }
 }

src/BuilderGenerator.Tests.Integration.Net60.PackageRef/BuilderGenerator.Tests.Integration.Net60.PackageRef.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="BuilderGenerator" Version="3.0.5-alpha" />
+    <PackageReference Include="BuilderGenerator" Version="3.0.7" />
     <PackageReference Include="NUnit" Version="[3.14.0, 4.0.0)" />
     <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />

src/BuilderGenerator.Tests.Integration.Net60.PackageRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net60.ProjectRef/Tests/OrderBuilderTests.cs

@@ -20,11 +20,17 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
 
+    [Test]
+    public void PostBuildAction_was_called()
+    {
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
+    }
+
     [Test]
     public void Simple_does_not_populate_Items()
     {
@@ -67,6 +73,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x => x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net70.PackageRef/BuilderGenerator.Tests.Integration.Net70.PackageRef.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="BuilderGenerator" Version="3.0.5-alpha" />
+    <PackageReference Include="BuilderGenerator" Version="3.0.7" />
     <PackageReference Include="NUnit" Version="[3.14.0, 4.0.0)" />
     <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />

src/BuilderGenerator.Tests.Integration.Net70.PackageRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net70.ProjectRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net80.PackageRef/BuilderGenerator.Tests.Integration.Net80.PackageRef.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="BuilderGenerator" Version="3.0.5-alpha" />
+    <PackageReference Include="BuilderGenerator" Version="3.0.7" />
     <PackageReference Include="NUnit" Version="4.3.2" />
     <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />

src/BuilderGenerator.Tests.Integration.Net80.PackageRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net80.ProjectRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net90.PackageRef/BuilderGenerator.Tests.Integration.Net90.PackageRef.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="BuilderGenerator" Version="3.0.5-alpha" />
+    <PackageReference Include="BuilderGenerator" Version="3.0.7" />
     <PackageReference Include="NUnit" Version="4.3.2" />
     <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />

src/BuilderGenerator.Tests.Integration.Net90.PackageRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Integration.Net90.ProjectRef/Tests/OrderBuilderTests.cs

@@ -20,7 +20,7 @@ public class OrderBuilderTests
     public void OrderBuilder_can_set_properties()
     {
         _result.Id.ShouldBe(_id);
-        _result.InternalString.ShouldBe(_internalString);
+        _result.InternalString.ShouldBe(_internalString.ToUpper());
         _result.OrderDate.ShouldBe(_orderDate);
         _result.Status.ShouldBe(_status);
     }
@@ -67,6 +67,7 @@ public void SetUp()
             .WithInternalString(_internalString)
             .WithOrderDate(_orderDate)
             .WithStatus(_status)
+            .WithPostBuildAction(x=>x.InternalString = x.InternalString.ToUpper())
             .Build();
     }
 }

src/BuilderGenerator.Tests.Unit/BuilderGenerator.Tests.Unit.csproj

@@ -28,13 +28,6 @@
     <PackageReference Include="Shouldly" Version="4.3.0" />
   </ItemGroup>
 
-  <ItemGroup>
-    <Compile Remove="Examples\ClassWithInternals.cs" />
-    <Compile Remove="Examples\ClassWithoutInternals.cs" />
-    <EmbeddedResource Include="Examples\ClassWithInternals.cs" />
-    <EmbeddedResource Include="Examples\ClassWithoutInternals.cs" />
-  </ItemGroup>
-
   <ItemGroup>
     <Compile Update="Properties\Resources.Designer.cs">
       <DesignTime>True</DesignTime>
@@ -48,6 +41,15 @@
       <Generator>ResXFileCodeGenerator</Generator>
       <LastGenOutput>Resources.Designer.cs</LastGenOutput>
     </EmbeddedResource>
+
+    <Compile Remove="Examples\Example.cs" />
+    <EmbeddedResource Include="Examples\Example.cs" />
+
+    <Compile Remove="Examples\ExampleWithInternalProperties.cs" />
+    <EmbeddedResource Include="Examples\ExampleWithInternalProperties.cs" />
+
+    <Compile Remove="Examples\ExampleWithObsoleteProperties.cs" />
+    <EmbeddedResource Include="Examples\ExampleWithObsoleteProperties.cs" />
   </ItemGroup>
 
   <ItemGroup>

src/BuilderGenerator.Tests.Unit/Examples/Example.cs

@@ -0,0 +1,37 @@
+using System;
+
+namespace BuilderGenerator.Tests.Unit.Examples;
+
+/// <summary>An example class with various properties.</summary>
+public class Person
+{
+    /// <summary>
+    ///     The Person's first name.
+    /// </summary>
+    /// <remarks>This was a multi-line, indented summary in the original source code.</remarks>
+    public string FirstName { get; set; }
+
+    /// <summary>The Person's last name.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    public string LastName { get; set; }
+
+    /// <summary>A string property marked as obsolete to test the "includeObsolete" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    public string MiddleName { get; set; }
+
+    /// <summary>A string with internal accessibility to test the "includeInternals" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    internal string InternalString { get; set; }
+
+    /// <summary>A string with internal accessibility to test the "includeInternals" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    [Obsolete]
+    public string ObsoleteString { get; set; }
+}
+
+/// <summary>An example builder that includes neither internal nor obsolete properties.</summary>
+[BuilderFor(typeof(Person))]
+public partial class PersonBuilder
+{
+}
+

src/BuilderGenerator.Tests.Unit/Examples/ExampleWithInternalProperties.cs

@@ -0,0 +1,36 @@
+using System;
+
+namespace BuilderGenerator.Tests.Unit.Examples;
+
+/// <summary>An example class with various properties.</summary>
+public class Person
+{
+    /// <summary>
+    ///     The Person's first name.
+    /// </summary>
+    /// <remarks>This was a multi-line, indented summary in the original source code.</remarks>
+    public string FirstName { get; set; }
+
+    /// <summary>The Person's last name.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    public string LastName { get; set; }
+
+    /// <summary>A string property marked as obsolete to test the "includeObsolete" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    public string MiddleName { get; set; }
+
+    /// <summary>A string with internal accessibility to test the "includeInternals" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    internal string InternalString { get; set; }
+
+    /// <summary>A string with internal accessibility to test the "includeInternals" attribute parameter.</summary>
+    /// <remarks>This was a single-line summary in the original source code.</remarks>
+    [Obsolete]
+    public string ObsoleteString { get; set; }
+}
+
+/// <summary>An example builder that includes internal properties.</summary>
+[BuilderFor(typeof(Person), includeInternals: true)]
+public partial class PersonBuilderWithInternals
+{
+}