Add onboarding helper RandomlyForceCacheMissBitMask

Author: johnterickson

README.md

@@ -59,7 +59,7 @@ These settings are common across all plugins, although different implementations
 | `$(MSBuildCacheMaxConcurrentCacheContentOperations)` | `int` | 64 | The maximum number of cache operations to perform concurrently |
 | `$(MSBuildCacheLocalCacheRootPath)` | `string` | "\MSBuildCache" (in repo's drive root) | Base directory to use for the local cache. |
 | `$(MSBuildCacheLocalCacheSizeInMegabytes)` | `int` | 102400 (100 GB) | The maximum size in megabytes of the local cache |
-| `$(MSBuildCacheRandomlyForceCacheMissPercentage)` | `int` | 0 | The percentage of cache hits to force to be treated as cache misses.  Useful for testing. |
+| `$(MSBuildCacheRandomlyForceCacheMissBitMask)` | `int` | 0 | Force a cache miss if the all the specified bits in project hash are set. Because the project hash is stable given the same inputs, building the same commit with the same bitmask will cause the same projects to be forced to miss. For example, 1, 2, 4, 8,... will each cause ~50% cache misses they are represented by one bit.  Since they are different bits, changing from 1 to 2 will cause a different set of ~50% to miss. 3, 5, 6, ... will each cause ~25%. 7, 15, .. will each cause ~12%. Useful for testing to simulate natural cache misses. |
 | `$(MSBuildCacheIgnoredInputPatterns)` | `Glob[]` |  | Files which are part of the repo which should be ignored for cache invalidation |
 | `$(MSBuildCacheIgnoredOutputPatterns)` | `Glob[]` | `*.assets.cache; *assemblyreference.cache` | Files to ignore for output collection into the cache. Note that if output are ignored, the replayed cache entry will not have these files. This should be used for intermediate outputs which are not properly portable |
 | `$(MSBuildCacheIdenticalDuplicateOutputPatterns)` | `Glob[]` | | Files to allow duplicate outputs, with identical content, across projects. Projects which produce files at the same path with differing content will still produce an error. Note: this setting should be used sparingly as it impacts performance |

src/Common.Tests/PluginSettingsTests.cs

@@ -95,10 +95,10 @@ public void LocalCacheSizeInMegabytesSetting()
             new[] { 123u, 456u, 789u });
 
     [TestMethod]
-    public void RandomlyForceCacheMissPercentageSetting()
+    public void RandomlyForceCacheMissBitMaskSetting()
         => TestBasicSetting(
-            nameof(PluginSettings.RandomlyForceCacheMissPercentage),
-            pluginSettings => pluginSettings.RandomlyForceCacheMissPercentage,
+            nameof(PluginSettings.RandomlyForceCacheMissBitMask),
+            pluginSettings => pluginSettings.RandomlyForceCacheMissBitMask,
             new[] { 0u, 10u, 100u });
 
     private static IEnumerable<object[]> GlobTestData

src/Common/MSBuildCachePluginBase.cs

@@ -349,14 +349,15 @@ private async Task<CacheResult> GetCacheResultInnerAsync(BuildRequestData buildR
             return CacheResult.IndicateNonCacheHit(CacheResultType.CacheMiss);
         }
 
-        if (Settings.RandomlyForceCacheMissPercentage > 0)
+        if (Settings.RandomlyForceCacheMissBitMask != 0)
         {
             // use a hash of the project id so that it is repeatable
 #pragma warning disable CA1850 // ComputeHash is not in net472
             using SHA256 hasher = SHA256.Create();
             byte[] projectHash = hasher.ComputeHash(Encoding.UTF8.GetBytes(nodeContext.Id));
+            uint hashInt = BitConverter.ToUInt32(projectHash, 0);
 #pragma warning restore CA1850
-            if (BitConverter.ToUInt32(projectHash, 0) % 100 < Settings.RandomlyForceCacheMissPercentage)
+            if ((hashInt & Settings.RandomlyForceCacheMissBitMask) == Settings.RandomlyForceCacheMissBitMask)
             {
                 Interlocked.Increment(ref _cacheMissCount);
                 return CacheResult.IndicateNonCacheHit(CacheResultType.CacheMiss);

src/Common/PluginSettings.cs

@@ -81,7 +81,7 @@ public string LocalCacheRootPath
 
     public uint LocalCacheSizeInMegabytes { get; init; } = 102400; // 100GB
 
-    public uint RandomlyForceCacheMissPercentage { get; init; }
+    public uint RandomlyForceCacheMissBitMask { get; init; }
 
     public IReadOnlyCollection<Glob> IgnoredInputPatterns { get; init; } = Array.Empty<Glob>();
 

src/Common/build/Microsoft.MSBuildCache.Common.targets

@@ -10,7 +10,7 @@
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheMaxConcurrentCacheContentOperations</MSBuildCacheGlobalPropertiesToIgnore>
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheLocalCacheRootPath</MSBuildCacheGlobalPropertiesToIgnore>
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheLocalCacheSizeInMegabytes</MSBuildCacheGlobalPropertiesToIgnore>
-    <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheRandomlyForceCacheMissPercentage</MSBuildCacheGlobalPropertiesToIgnore>
+    <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheRandomlyForceCacheMissBitMask</MSBuildCacheGlobalPropertiesToIgnore>
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheIgnoredInputPatterns</MSBuildCacheGlobalPropertiesToIgnore>
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheIgnoredOutputPatterns</MSBuildCacheGlobalPropertiesToIgnore>
     <MSBuildCacheGlobalPropertiesToIgnore>$(MSBuildCacheGlobalPropertiesToIgnore);MSBuildCacheIdenticalDuplicateOutputPatterns</MSBuildCacheGlobalPropertiesToIgnore>
@@ -30,7 +30,7 @@
       <MaxConcurrentCacheContentOperations>$(MSBuildCacheMaxConcurrentCacheContentOperations)</MaxConcurrentCacheContentOperations>
       <LocalCacheRootPath>$(MSBuildCacheLocalCacheRootPath)</LocalCacheRootPath>
       <LocalCacheSizeInMegabytes>$(MSBuildCacheLocalCacheSizeInMegabytes)</LocalCacheSizeInMegabytes>
-      <RandomlyForceCacheMissPercentage>$(MSBuildCacheRandomlyForceCacheMissPercentage)</RandomlyForceCacheMissPercentage>
+      <RandomlyForceCacheMissBitMask>$(MSBuildCacheRandomlyForceCacheMissBitMask)</RandomlyForceCacheMissBitMask>
       <IgnoredInputPatterns>$(MSBuildCacheIgnoredInputPatterns)</IgnoredInputPatterns>
       <IgnoredOutputPatterns>$(MSBuildCacheIgnoredOutputPatterns)</IgnoredOutputPatterns>
       <IdenticalDuplicateOutputPatterns>$(MSBuildCacheIdenticalDuplicateOutputPatterns)</IdenticalDuplicateOutputPatterns>