feat(jobs): add MsBuildProperty for escaped MSBuild properties

docs/articles/guides/troubleshooting.md

@@ -45,7 +45,7 @@ How to troubleshoot the build process:
 The recommended order of solving build issues:
 
 1. Change the right settings in your project file which defines benchmarks to get it working.
-2. Customize the `Job` settings using available options like `job.WithCustomBuildConfiguration($name)`or `job.With(new Argument[] { new MsBuildArgument("/p:SomeProperty=Value")})`.
+2. Customize the `Job` settings using available options like `job.WithCustomBuildConfiguration($name)` or `job.WithArguments(new Argument[] { new MsBuildArgument("/p:SomeProperty=Value") })`. For list-like MSBuild properties that contain special characters (for example, `DefineConstants=TEST1;TEST2`), use `MsBuildProperty` (it escapes the value for you): `job.WithArguments(new Argument[] { new MsBuildProperty("DefineConstants", "TEST1", "TEST2") })`.
 3. Implement your own `IToolchain` and generate and build all the right things in your way (you can use existing Builders and Generators and just override some methods to change specific behaviour).
 4. Report a bug in BenchmarkDotNet repository.
 
@@ -94,4 +94,3 @@ public void Setup()
 ### One of the above, but with a Debug build
 
 By default, BDN builds everything in Release. But debugging Release builds even with full symbols might be non-trivial. To enforce BDN to build the benchmark in Debug please use `DebugBuildConfig` and then attach the debugger.
-

src/BenchmarkDotNet/Jobs/Argument.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Text;
 using JetBrains.Annotations;
 
 namespace BenchmarkDotNet.Jobs
@@ -47,6 +48,96 @@ public MonoArgument(string value) : base(value)
     [PublicAPI]
     public class MsBuildArgument : Argument
     {
+        private readonly string? displayValue;
+
         public MsBuildArgument(string value) : base(value) { }
+
+        public MsBuildArgument(string value, bool escapeSpecialCharacters) : base(escapeSpecialCharacters ? EscapeSpecialCharacters(value) : value)
+        {
+            if (escapeSpecialCharacters)
+                displayValue = value;
+        }
+
+        public override string ToString() => displayValue ?? base.ToString();
+
+        internal static string EscapeSpecialCharacters(string value)
+        {
+            if (value is null)
+                throw new ArgumentNullException(nameof(value));
+
+            var builder = new StringBuilder(value.Length);
+            foreach (var character in value)
+            {
+                switch (character)
+                {
+                    // See: https://learn.microsoft.com/en-us/visualstudio/msbuild/special-characters-to-escape
+                    case '%':
+                        builder.Append("%25");
+                        break;
+                    case '$':
+                        builder.Append("%24");
+                        break;
+                    case '@':
+                        builder.Append("%40");
+                        break;
+                    case '(':
+                        builder.Append("%28");
+                        break;
+                    case ')':
+                        builder.Append("%29");
+                        break;
+                    case ';':
+                        builder.Append("%3B");
+                        break;
+                    case '?':
+                        builder.Append("%3F");
+                        break;
+                    case '*':
+                        builder.Append("%2A");
+                        break;
+                    default:
+                        builder.Append(character);
+                        break;
+                }
+            }
+
+            return builder.ToString();
+        }
+    }
+
+    /// <summary>
+    /// An MSBuild property argument (<c>/p:name=value</c>).
+    /// It escapes MSBuild special characters in the value (for example, semicolons) so that
+    /// list-like values can be passed without manual encoding.
+    /// </summary>
+    [PublicAPI]
+    public class MsBuildProperty : MsBuildArgument
+    {
+        public MsBuildProperty(string name, params string[] values)
+            : base(CreateArgumentTextRepresentation(name, values), escapeSpecialCharacters: true)
+        {
+        }
+
+        private static string CreateArgumentTextRepresentation(string name, string[] values)
+        {
+            if (string.IsNullOrWhiteSpace(name))
+                throw new ArgumentException("Property name must be non-empty.", nameof(name));
+
+            if (values is null)
+                throw new ArgumentNullException(nameof(values));
+
+            for (int i = 0; i < values.Length; i++)
+                if (values[i] is null)
+                    throw new ArgumentException("Property values can not contain null.", nameof(values));
+
+            string value = values.Length switch
+            {
+                0 => string.Empty,
+                1 => values[0],
+                _ => string.Join(";", values)
+            };
+
+            return $"/p:{name}={value}";
+        }
     }
-}
+}

tests/BenchmarkDotNet.IntegrationTests.ManualRunning/BenchmarkDotNet.IntegrationTests.ManualRunning.csproj

@@ -15,6 +15,10 @@
   <PropertyGroup Condition="'$(CustomProp)'=='true'">
     <DefineConstants>$(DefineConstants);CUSTOM_PROP</DefineConstants>
   </PropertyGroup>
+
+  <PropertyGroup Condition="'$(ExtraDefineConstants)'!=''">
+    <DefineConstants>$(DefineConstants);$(ExtraDefineConstants)</DefineConstants>
+  </PropertyGroup>
 
   <ItemGroup>
     <Compile Include="..\BenchmarkDotNet.IntegrationTests\BenchmarkTestExecutor.cs" Link="BenchmarkTestExecutor.cs" />
@@ -44,4 +48,4 @@
     </PackageReference>
   </ItemGroup>
   <Import Project="..\..\build\common.targets" />
-</Project>
+</Project>

tests/BenchmarkDotNet.IntegrationTests.ManualRunning/MsBuildArgumentTests.cs

@@ -48,6 +48,17 @@ public void MultipleProcessesAreBuiltWithCorrectProperties()
             CanExecute<PropertyDefine>(config);
         }
 
+        [Fact]
+        public void ProcessIsBuiltWithSemicolonSeparatedPropertyValues()
+        {
+            var config = ManualConfig.CreateEmpty()
+                .AddJob(Job.Dry
+                    .WithArguments([new MsBuildProperty("ExtraDefineConstants", "TEST1", "TEST2")])
+                );
+
+            CanExecute<ExtraDefineConstants>(config);
+        }
+
         public class PropertyDefine
         {
             private const bool customPropWasSet =
@@ -66,5 +77,18 @@ public void ThrowWhenWrong()
                 }
             }
         }
+
+        public class ExtraDefineConstants
+        {
+            [Benchmark]
+            public void ThrowWhenWrong()
+            {
+#if TEST1 && TEST2
+                return;
+#else
+                throw new InvalidOperationException("ExtraDefineConstants was not applied to the benchmark build.");
+#endif
+            }
+        }
     }
-}
+}

tests/BenchmarkDotNet.Tests/Jobs/MsBuildArgumentTests.cs

@@ -0,0 +1,35 @@
+using BenchmarkDotNet.Jobs;
+using Xunit;
+
+namespace BenchmarkDotNet.Tests.Jobs;
+
+public class MsBuildArgumentTests
+{
+    [Fact]
+    public void EscapeSpecialCharactersIsOptIn()
+    {
+        var argument = new MsBuildArgument("/p:DefineConstants=TEST1;TEST2");
+
+        Assert.Equal("/p:DefineConstants=TEST1;TEST2", argument.TextRepresentation);
+        Assert.Equal("/p:DefineConstants=TEST1;TEST2", argument.ToString());
+    }
+
+    [Fact]
+    public void EscapeSpecialCharactersEscapesAllMsBuildSpecialCharactersForCommandLine()
+    {
+        var argument = new MsBuildArgument("%$@();?*", escapeSpecialCharacters: true);
+
+        Assert.Equal("%25%24%40%28%29%3B%3F%2A", argument.TextRepresentation);
+        Assert.Equal("%$@();?*", argument.ToString());
+    }
+
+    [Fact]
+    public void MsBuildPropertyJoinsValuesWithSemicolonsAndEscapesThem()
+    {
+        var argument = new MsBuildProperty("DefineConstants", "TEST1", "TEST2");
+
+        Assert.Equal("/p:DefineConstants=TEST1%3BTEST2", argument.TextRepresentation);
+        Assert.Equal("/p:DefineConstants=TEST1;TEST2", argument.ToString());
+    }
+}
+