Move MSBuild initialization from MSBuildTestBase to MSBuildAssemblyResolver (#277)

* Move MSBuild init from MSBuildTestBase to MSBuildAssemblyResolver
* Clean up README for locating MSBuild

Author: MattKotsenas

README.md

@@ -91,10 +91,39 @@ The above extension method would add the following item:
   </MyCustomType>
 </ItemGroup>
 ```
+
 ## Resolving MSBuild
-This API does not redistribute MSBuild and so it must be located at run-time.  There are three ways to do this:
 
-1. If your project is a unit test, have your test class inherit from [MSBuildTestBase](https://github.com/jeffkl/MSBuildProjectCreator/blob/main/src/MSBuildProjectCreator/MSBuildTestBase.cs)
+This API does not redistribute MSBuild and so it must be located at run-time. There are two locators to be aware of:
+
+1. `MSBuildAssemblyResolver.Register()` provided in this package
+2. `MSBuildLocator.RegisterDefaults()` in the [MSBuildLocator](https://docs.microsoft.com/en-us/visualstudio/msbuild/updating-an-existing-application?view=vs-2019#use-microsoftbuildlocator) package
+
+In either case, you need to register before running any MSBuild operations. There are three main ways to ensure registration:
+
+### 1. Module initializer (preferred)
+
+If you're targeting C# 9.0+ / .NET 5+, use a [module initializer](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/module-initializers).
+MSBuild assemblies will be automatically located when your assembly is loaded:
+
+```C#
+using System.Runtime.CompilerServices;
+
+internal static class MyModuleInitializer
+{
+    [ModuleInitializer]
+    internal static void InitializeMSBuild()
+    {
+        MSBuildAssemblyResolver.Register();
+    }
+}
+```
+
+### 2. Inherit from MSBuildTestBase
+
+If you're unable or don't want to use a module initializer and your project is a unit test, have your test class inherit
+from [MSBuildTestBase](https://github.com/jeffkl/MSBuildProjectCreator/blob/main/src/MSBuildProjectCreator/MSBuildTestBase.cs):
+
 ```C#
 /// <summary>
 /// A base class for all unit tests that inherits from MSBuildTestBase.
@@ -111,24 +140,17 @@ public class MyTest : MyTestBase
 {
 }
 ```
-2. Attach the [assembly resolve event handler](https://docs.microsoft.com/en-us/dotnet/standard/assembly/resolve-loads) to [MSBuildAssemblyResolver.AssemblyResolve](https://github.com/jeffkl/MSBuildProjectCreator/blob/main/src/MSBuildProjectCreator/MSBuildAssemblyResolver.cs)
 
-``` C#
-public static class MyApp
-{
-    public static MyApp()
-    {
-        AppDomain.CurrentDomain.AssemblyResolve += MSBuildAssemblyResolver.AssemblyResolve;
-    }
-}
-```
-3. Use [MSBuildLocator](https://docs.microsoft.com/en-us/visualstudio/msbuild/updating-an-existing-application?view=vs-2019#use-microsoftbuildlocator) to register an instance of MSBuild.
+### 3. Use a static constructor
+
+Add a static constructor and call the registration API:
+
 ```C#
 public static class MyApp
 {
     public static MyApp()
     {
-        MSBuildLocator.RegisterDefaults();
+        MSBuildAssemblyResolver.Register();
     }
 }
 ```

src/Microsoft.Build.Utilities.ProjectCreation/MSBuildAssemblyResolver.cs

@@ -7,6 +7,9 @@
 using System.IO;
 using System.Linq;
 using System.Reflection;
+#if NET6_0_OR_GREATER
+using System.Runtime.Loader;
+#endif
 
 namespace Microsoft.Build.Utilities.ProjectCreation
 {
@@ -19,6 +22,21 @@ public static partial class MSBuildAssemblyResolver
 
         private static readonly ConcurrentDictionary<string, Lazy<Assembly?>> LoadedAssemblies = new ConcurrentDictionary<string, Lazy<Assembly?>>(StringComparer.OrdinalIgnoreCase);
 
+        private static readonly Lazy<object> RegisterLazy = new Lazy<object>(() =>
+        {
+            Environment.SetEnvironmentVariable("MSBUILD_EXE_PATH", MSBuildExePath);
+            Environment.SetEnvironmentVariable("MSBuildExtensionsPath", DotNetSdksPath);
+            Environment.SetEnvironmentVariable("MSBuildSDKsPath", string.IsNullOrWhiteSpace(DotNetSdksPath) ? null : Path.Combine(DotNetSdksPath, "Sdks"));
+
+#if NET6_0_OR_GREATER
+            AssemblyLoadContext.Default.Resolving += AssemblyResolve;
+#else
+            AppDomain.CurrentDomain.AssemblyResolve += AssemblyResolve;
+#endif
+
+            return new object();
+        });
+
         /// <summary>
         /// Gets the path to the .NET SDKs.
         /// </summary>
@@ -34,6 +52,11 @@ public static partial class MSBuildAssemblyResolver
         /// </summary>
         public static string? MSBuildExePath => MSBuildDirectoryLazy.Value.MSBuildExePath;
 
+        /// <summary>
+        /// Register to resolve MSBuild related assemblies automatically.
+        /// </summary>
+        public static void Register() => _ = RegisterLazy.Value;
+
         private static Assembly? AssemblyResolve(AssemblyName requestedAssemblyName, Func<string, Assembly?> assemblyLoader)
         {
             if (SearchPaths == null)

src/Microsoft.Build.Utilities.ProjectCreation/MSBuildTestBase.cs

@@ -2,30 +2,20 @@
 //
 // Licensed under the MIT license.
 
-using System;
-using System.IO;
-#if NET6_0_OR_GREATER
-using System.Runtime.Loader;
-#endif
-
 namespace Microsoft.Build.Utilities.ProjectCreation
 {
     /// <summary>
-    /// Provides a base class for unit test classes that use MSBuild.  This class resolves MSBuild related assemblies automatically.
+    /// Provides a base class for unit test classes that use MSBuild. This class resolves MSBuild related assemblies automatically.
     /// </summary>
+    /// <remarks>
+    /// Prefer calling <see cref="MSBuildAssemblyResolver.Register"/> from a <c>ModuleInitalizerAttribute</c> if your target framework
+    /// supports one. This base class is provided for backwards compatibility with older versions of .NET.
+    /// </remarks>
     public abstract class MSBuildTestBase
     {
         static MSBuildTestBase()
         {
-            Environment.SetEnvironmentVariable("MSBUILD_EXE_PATH", MSBuildAssemblyResolver.MSBuildExePath);
-            Environment.SetEnvironmentVariable("MSBuildExtensionsPath", MSBuildAssemblyResolver.DotNetSdksPath);
-            Environment.SetEnvironmentVariable("MSBuildSDKsPath", string.IsNullOrWhiteSpace(MSBuildAssemblyResolver.DotNetSdksPath) ? null : Path.Combine(MSBuildAssemblyResolver.DotNetSdksPath, "Sdks"));
-
-#if NET6_0_OR_GREATER
-            AssemblyLoadContext.Default.Resolving += MSBuildAssemblyResolver.AssemblyResolve;
-#else
-            AppDomain.CurrentDomain.AssemblyResolve += MSBuildAssemblyResolver.AssemblyResolve;
-#endif
+            MSBuildAssemblyResolver.Register();
         }
     }
 }

src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net472/PublicAPI.Shipped.txt

@@ -293,6 +293,7 @@ static Microsoft.Build.Utilities.ProjectCreation.ExtensionMethods.ToArrayWithSin
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.AssemblyResolve(object? sender, System.ResolveEventArgs! args) -> System.Reflection.Assembly?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.DotNetSdksPath.get -> string?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.MSBuildExePath.get -> string?
+static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.Register() -> void
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.SearchPaths.get -> string![]?
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(string! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(System.IO.DirectoryInfo! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!

src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net6.0/PublicAPI.Shipped.txt

@@ -293,6 +293,7 @@ static Microsoft.Build.Utilities.ProjectCreation.ExtensionMethods.ToArrayWithSin
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.AssemblyResolve(System.Runtime.Loader.AssemblyLoadContext! assemblyLoadContext, System.Reflection.AssemblyName! requestedAssemblyName) -> System.Reflection.Assembly?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.DotNetSdksPath.get -> string?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.MSBuildExePath.get -> string?
+static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.Register() -> void
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.SearchPaths.get -> string![]?
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(string! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(System.IO.DirectoryInfo! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!

src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net7.0/PublicAPI.Shipped.txt

@@ -293,6 +293,7 @@ static Microsoft.Build.Utilities.ProjectCreation.ExtensionMethods.ToArrayWithSin
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.AssemblyResolve(System.Runtime.Loader.AssemblyLoadContext! assemblyLoadContext, System.Reflection.AssemblyName! requestedAssemblyName) -> System.Reflection.Assembly?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.DotNetSdksPath.get -> string?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.MSBuildExePath.get -> string?
+static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.Register() -> void
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.SearchPaths.get -> string![]?
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(string! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(System.IO.DirectoryInfo! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!

src/Microsoft.Build.Utilities.ProjectCreation/PublicAPI/net8.0/PublicAPI.Shipped.txt

@@ -293,6 +293,7 @@ static Microsoft.Build.Utilities.ProjectCreation.ExtensionMethods.ToArrayWithSin
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.AssemblyResolve(System.Runtime.Loader.AssemblyLoadContext! assemblyLoadContext, System.Reflection.AssemblyName! requestedAssemblyName) -> System.Reflection.Assembly?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.DotNetSdksPath.get -> string?
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.MSBuildExePath.get -> string?
+static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.Register() -> void
 static Microsoft.Build.Utilities.ProjectCreation.MSBuildAssemblyResolver.SearchPaths.get -> string![]?
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(string! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!
 static Microsoft.Build.Utilities.ProjectCreation.PackageFeed.Create(System.IO.DirectoryInfo! rootPath) -> Microsoft.Build.Utilities.ProjectCreation.PackageFeed!