add BundleExtraAssemblies package option for new .NET 5 reference model

docs/technical/mod-package.md

@@ -39,10 +39,9 @@ change how these work):
 
 * **Copy files into the `Mods` folder:**  
   The package automatically copies your mod's DLL and PDB files, `manifest.json`, [`i18n`
-  files](https://stardewvalleywiki.com/Modding:Translations) (if any), the `assets` folder (if
+  files](https://stardewvalleywiki.com/Modding:Translations) (if any), and the `assets` folder (if
-  any), and [build output](https://stackoverflow.com/a/10828462/262123) into your game's `Mods`
+  any) into the `Mods` folder when you rebuild the code, with a subfolder matching the mod's project
-  folder when you rebuild the code, with a subfolder matching the mod's project name. That lets you
+  name. That lets you try the mod in-game right after building it.
-  try the mod in-game right after building it.
 
 * **Create release zip:**  
   The package adds a zip file in your project's `bin` folder when you rebuild the code, in the
@@ -189,11 +188,63 @@ The folder path where the release zip is created (defaults to the project's `bin
   <th>effect</th>
 </tr>
 <tr>
-<td><code>CopyModReferencesToBuildOutput</code></td>
+<td><code>BundleExtraAssemblies</code></td>
 <td>
 
-Whether to copy game and framework DLLs into the mod folder (default `false`). This is useful for
+**Most mods should not change this option.**
-unit test projects, but not needed for mods that'll be run through SMAPI.
+
+By default (when this is _not_ enabled), only the mod files [normally considered part of the
+mod](#Features) will be added to the release `.zip` and copied into the `Mods` folder (i.e.
+"deployed"). That includes the assembly files (`*.dll`, `*.pdb`, and `*.xml`) for your mod project,
+but any other DLLs won't be deployed.
+
+Enabling this option will add _all_ dependencies to the build output, then deploy _some_ of them
+depending on the comma-separated value(s) you set:
+
+<table>
+<tr>
+  <th>option</th>
+  <th>result</th>
+</tr>
+<tr>
+<td><code>ThirdParty</code></td>
+<td>
+
+Assembly files which don't match any other category.
+
+</td>
+</tr>
+<tr>
+<td><code>System</code></td>
+<td>
+
+Assembly files whose names start with `Microsoft.*` or `System.*`.
+
+</td>
+</tr>
+<tr>
+<td><code>Game</code></td>
+<td>
+
+Assembly files which are part of MonoGame, SMAPI, or Stardew Valley.
+
+</td>
+</tr>
+<tr>
+<td><code>All</code></td>
+<td>
+
+Equivalent to `System, Game, ThirdParty`.
+
+</td>
+</tr>
+</table>
+
+Most mods should omit the option. Some mods may need `ThirdParty` if they bundle third-party DLLs
+with their mod. The other options are mainly useful for unit tests.
+
+When enabling this option, you should **manually review which files get deployed** and use the
+`IgnoreModFilePaths` or `IgnoreModFilePatterns` options to exclude files as needed.
 
 </td>
 </tr>
@@ -327,16 +378,15 @@ The configuration will check your custom path first, then fall back to the defau
 still compile on a different computer).
 
 ### How do I change which files are included in the mod deploy/zip?
-For custom files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123).
+* For normal files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123).
-(If your project references another mod, make sure the reference is [_not_ marked 'copy
+* For assembly files (`*.dll`, `*.exe`, `*.pdb`, or `*.xml`), see the
-local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).)
+  [`BundleExtraAssemblies` option](#configure).
-
+* To exclude a file which the package copies by default, see the [`IgnoreModFilePaths` or
-To exclude a file the package copies by default, see `IgnoreModFilePatterns` under
+  `IgnoreModFilePatterns` options](#configure).
-[_configure_](#configure).
 
 ### Can I use the package for non-mod projects?
-You can use the package in non-mod projects too (e.g. unit tests or framework DLLs). Just disable
+Yep, this works in unit tests and framework projects too. Just disable the mod-related package
-the mod-related package features (see [_configure_](#configure)):
+features (see [_configure_](#configure)):
 
 ```xml
 <EnableGameDebugging>false</EnableGameDebugging>
@@ -344,9 +394,9 @@ the mod-related package features (see [_configure_](#configure)):
 <EnableModZip>false</EnableModZip>
 ```
 
-If you need to copy the referenced DLLs into your build output, add this too:
+To copy referenced DLLs into your build output for unit tests, add this too:
 ```xml
-<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>
+<BundleExtraAssemblies>All</BundleExtraAssemblies>
 ```
 
 ## For SMAPI developers
@@ -363,18 +413,24 @@ when you compile it.
 
 ## Release notes
 ## Upcoming release
-* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. **Older versions are no longer supported.**
+* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. (Older versions are no longer supported.)
 * Added `IgnoreModFilePaths` option to ignore literal paths.
-* Removed the `GameExecutableName` and `GameFramework` build properties (since they now have the
+* Added `BundleExtraAssemblies` option to copy bundled DLLs into the mod zip/folder.
-  same value on all platforms).
+* Removed the `GameExecutableName` and `GameFramework` options (since they now have the same value
+  on all platforms).
+* Removed the `CopyModReferencesToBuildOutput` option (superseded by `BundleExtraAssemblies`).
 * Improved analyzer performance by enabling parallel execution.
 
 **Migration guide for mod authors:**
 1. See [_migrate to 64-bit_](https://stardewvalleywiki.com/Modding:Migrate_to_64-bit_on_Windows) and
    [_migrate to Stardew Valley 1.5.5_](https://stardewvalleywiki.com/Modding:Migrate_to_Stardew_Valley_1.5.5).
 2. Possible changes in your `.csproj` or `.targets` files:
-   * If you use `$(GameExecutableName)`, replace it with `Stardew Valley`.
+   * Replace `$(GameExecutableName)` with `Stardew Valley`.
-   * If you use `$(GameFramework)`, replace it with `MonoGame` and remove any XNA-specific logic.
+   * Replace `$(GameFramework)` with `MonoGame` and remove any XNA Framework-specific logic.
+   * Replace `<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>` with
+     `<BundleExtraAssemblies>Game</BundleExtraAssemblies>`.
+   * If you need to bundle extra DLLs besides your mod DLL, see the [`BundleExtraAssemblies`
+     documentation](#configure).
 
 ## 3.3.0
 Released 30 March 2021.

src/SMAPI.ModBuildConfig/DeployModTask.cs

@@ -18,6 +18,10 @@ namespace StardewModdingAPI.ModBuildConfig
         /*********
         ** Accessors
         *********/
+        /// <summary>The name (without extension or path) of the current mod's DLL.</summary>
+        [Required]
+        public string ModDllName { get; set; }
+
         /// <summary>The name of the mod folder.</summary>
         [Required]
         public string ModFolderName { get; set; }
@@ -52,6 +56,9 @@ namespace StardewModdingAPI.ModBuildConfig
         /// <summary>A comma-separated list of relative file paths to ignore when deploying or zipping the mod.</summary>
         public string IgnoreModFilePaths { get; set; }
 
+        /// <summary>A comma-separated list of <see cref="ExtraAssemblyTypes"/> values which indicate which extra DLLs to bundle.</summary>
+        public string BundleExtraAssemblies { get; set; }
+
 
         /*********
         ** Public methods
@@ -73,12 +80,15 @@ namespace StardewModdingAPI.ModBuildConfig
 
             try
             {
+                // parse extra DLLs to bundle
+                ExtraAssemblyTypes bundleAssemblyTypes = this.GetExtraAssembliesToBundleOption();
+
                 // parse ignore patterns
                 string[] ignoreFilePaths = this.GetCustomIgnoreFilePaths().ToArray();
                 Regex[] ignoreFilePatterns = this.GetCustomIgnorePatterns().ToArray();
 
                 // get mod info
-                ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip);
+                ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, this.ModDllName, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip);
 
                 // deploy mod files
                 if (this.EnableModDeploy)
@@ -139,6 +149,28 @@ namespace StardewModdingAPI.ModBuildConfig
             }
         }
 
+        /// <summary>Parse the extra assembly types which should be bundled with the mod.</summary>
+        private ExtraAssemblyTypes GetExtraAssembliesToBundleOption()
+        {
+            ExtraAssemblyTypes flags = ExtraAssemblyTypes.None;
+
+            if (!string.IsNullOrWhiteSpace(this.BundleExtraAssemblies))
+            {
+                foreach (string raw in this.BundleExtraAssemblies.Split(','))
+                {
+                    if (!Enum.TryParse(raw, out ExtraAssemblyTypes type))
+                    {
+                        this.Log.LogWarning($"[mod build package] Ignored invalid <{nameof(this.BundleExtraAssemblies)}> value '{raw}', expected one of '{string.Join("', '", Enum.GetNames(typeof(ExtraAssemblyTypes)))}'.");
+                        continue;
+                    }
+
+                    flags |= type;
+                }
+            }
+
+            return flags;
+        }
+
         /// <summary>Get the custom ignore patterns provided by the user.</summary>
         private IEnumerable<Regex> GetCustomIgnorePatterns()
         {

src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs

@@ -0,0 +1,21 @@
+using System;
+
+namespace StardewModdingAPI.ModBuildConfig.Framework
+{
+    /// <summary>An extra assembly type for the <see cref="DeployModTask.BundleExtraAssemblies"/> field.</summary>
+    [Flags]
+    internal enum ExtraAssemblyTypes
+    {
+        /// <summary>Don't include extra assemblies.</summary>
+        None = 0,
+
+        /// <summary>Assembly files which are part of MonoGame, SMAPI, or Stardew Valley.</summary>
+        Game = 1,
+
+        /// <summary>Assembly files whose names start with <c>Microsoft.*</c> or <c>System.*</c>.</summary>
+        System = 2,
+
+        /// <summary>Assembly files which don't match any other category.</summary>
+        ThirdParty = 4
+    }
+}

src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs

@@ -21,6 +21,45 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
         /// <summary>The files that are part of the package.</summary>
         private readonly IDictionary<string, FileInfo> Files;
 
+        /// <summary>The file extensions used by assembly files.</summary>
+        private readonly ISet<string> AssemblyFileExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ".dll",
+            ".exe",
+            ".pdb",
+            ".xml"
+        };
+
+        /// <summary>The DLLs which match the <see cref="ExtraAssemblyTypes.Game"/> type.</summary>
+        private readonly ISet<string> GameDllNames = new HashSet<string>
+        {
+            // SMAPI
+            "0Harmony",
+            "Mono.Cecil",
+            "Mono.Cecil.Mdb",
+            "Mono.Cecil.Pdb",
+            "MonoMod.Common",
+            "Newtonsoft.Json",
+            "StardewModdingAPI",
+            "SMAPI.Toolkit",
+            "SMAPI.Toolkit.CoreInterfaces",
+            "TMXTile",
+
+            // game + framework
+            "BmFont",
+            "FAudio-CS",
+            "GalaxyCSharp",
+            "GalaxyCSharpGlue",
+            "Lidgren.Network",
+            "MonoGame.Framework",
+            "SkiaSharp",
+            "Stardew Valley",
+            "StardewValley.GameData",
+            "Steamworks.NET",
+            "TextCopy",
+            "xTile"
+        };
+
 
         /*********
         ** Public methods
@@ -30,9 +69,11 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
         /// <param name="targetDir">The folder containing the build output.</param>
         /// <param name="ignoreFilePaths">The custom relative file paths provided by the user to ignore.</param>
         /// <param name="ignoreFilePatterns">Custom regex patterns matching files to ignore when deploying or zipping the mod.</param>
+        /// <param name="bundleAssemblyTypes">The extra assembly types which should be bundled with the mod.</param>
+        /// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
         /// <param name="validateRequiredModFiles">Whether to validate that required mod files like the manifest are present.</param>
         /// <exception cref="UserErrorException">The mod package isn't valid.</exception>
-        public ModFileManager(string projectDir, string targetDir, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, bool validateRequiredModFiles)
+        public ModFileManager(string projectDir, string targetDir, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, ExtraAssemblyTypes bundleAssemblyTypes, string modDllName, bool validateRequiredModFiles)
         {
             this.Files = new Dictionary<string, FileInfo>(StringComparer.OrdinalIgnoreCase);
 
@@ -48,7 +89,7 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
                 string relativePath = entry.Item1;
                 FileInfo file = entry.Item2;
 
-                if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns))
+                if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, modDllName))
                     this.Files[relativePath] = file;
             }
 
@@ -152,39 +193,70 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
         /// <param name="relativePath">The file's relative path in the package.</param>
         /// <param name="ignoreFilePaths">The custom relative file paths provided by the user to ignore.</param>
         /// <param name="ignoreFilePatterns">Custom regex patterns matching files to ignore when deploying or zipping the mod.</param>
-        private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns)
+        /// <param name="bundleAssemblyTypes">The extra assembly types which should be bundled with the mod.</param>
+        /// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
+        private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, ExtraAssemblyTypes bundleAssemblyTypes, string modDllName)
         {
-            bool IsAssemblyFile(string baseName)
+            // apply custom patterns
-            {
+            if (ignoreFilePaths.Any(p => p == relativePath) || ignoreFilePatterns.Any(p => p.IsMatch(relativePath)))
-                return
+                return true;
-                    this.EqualsInvariant(file.Name, $"{baseName}.dll")
-                    || this.EqualsInvariant(file.Name, $"{baseName}.pdb")
-                    || this.EqualsInvariant(file.Name, $"{baseName}.xnb");
-            }
 
-            return
+            // ignore unneeded files
+            {
+                bool shouldIgnore =
                     // release zips
                     this.EqualsInvariant(file.Extension, ".zip")
 
-                // unneeded *.deps.json (only SMAPI's top-level one is used)
+                    // *.deps.json (only SMAPI's top-level one is used)
                     || file.Name.EndsWith(".deps.json")
 
-                // dependencies bundled with SMAPI
-                || IsAssemblyFile("0Harmony")
-                || IsAssemblyFile("Newtonsoft.Json")
-                || IsAssemblyFile("Pathoschild.Stardew.ModTranslationClassBuilder") // not used at runtime
-
                     // code analysis files
                     || file.Name.EndsWith(".CodeAnalysisLog.xml", StringComparison.OrdinalIgnoreCase)
                     || file.Name.EndsWith(".lastcodeanalysissucceeded", StringComparison.OrdinalIgnoreCase)
 
+                    // translation class builder (not used at runtime)
+                    || (
+                        file.Name.StartsWith("Pathoschild.Stardew.ModTranslationClassBuilder")
+                        && this.AssemblyFileExtensions.Contains(file.Extension)
+                    )
+
                     // OS metadata files
                     || this.EqualsInvariant(file.Name, ".DS_Store")
-                || this.EqualsInvariant(file.Name, "Thumbs.db")
+                    || this.EqualsInvariant(file.Name, "Thumbs.db");
+                if (shouldIgnore)
+                    return true;
+            }
 
-                // custom ignore patterns
+            // check for bundled assembly types
-                || ignoreFilePaths.Any(p => p == relativePath)
+            // When bundleAssemblyTypes is set, *all* dependencies are copied into the build output but only those which match the given assembly types should be bundled.
-                || ignoreFilePatterns.Any(p => p.IsMatch(relativePath));
+            if (bundleAssemblyTypes != ExtraAssemblyTypes.None)
+            {
+                var type = this.GetExtraAssemblyType(file, modDllName);
+                if (type != ExtraAssemblyTypes.None && !bundleAssemblyTypes.HasFlag(type))
+                    return true;
+            }
+
+            return false;
+        }
+
+        /// <summary>Get the extra assembly type for a file, assuming that the user specified one or more extra types to bundle.</summary>
+        /// <param name="file">The file to check.</param>
+        /// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
+        private ExtraAssemblyTypes GetExtraAssemblyType(FileInfo file, string modDllName)
+        {
+            string baseName = Path.GetFileNameWithoutExtension(file.Name);
+            string extension = file.Extension;
+
+            if (baseName == modDllName || !this.AssemblyFileExtensions.Contains(extension))
+                return ExtraAssemblyTypes.None;
+
+            if (this.GameDllNames.Contains(baseName))
+                return ExtraAssemblyTypes.Game;
+
+            if (baseName.StartsWith("System.", StringComparison.OrdinalIgnoreCase) || baseName.StartsWith("Microsoft.", StringComparison.OrdinalIgnoreCase))
+                return ExtraAssemblyTypes.System;
+
+            return ExtraAssemblyTypes.ThirdParty;
         }
 
         /// <summary>Get whether a string is equal to another case-insensitively.</summary>

src/SMAPI.ModBuildConfig/build/smapi.targets

@@ -29,7 +29,10 @@
     <EnableModZip Condition="'$(EnableModZip)' == ''">true</EnableModZip>
     <EnableHarmony Condition="'$(EnableHarmony)' == ''">false</EnableHarmony>
     <EnableGameDebugging Condition="'$(EnableGameDebugging)' == ''">true</EnableGameDebugging>
-    <CopyModReferencesToBuildOutput Condition="'$(CopyModReferencesToBuildOutput)' == '' OR ('$(CopyModReferencesToBuildOutput)' != 'true' AND '$(CopyModReferencesToBuildOutput)' != 'false')">false</CopyModReferencesToBuildOutput>
+    <BundleExtraAssemblies Condition="'$(BundleExtraAssemblies)' == ''"></BundleExtraAssemblies>
+
+    <!-- coppy referenced DLLs into build output -->
+    <CopyLocalLockFileAssemblies Condition="$(BundleExtraAssemblies.Contains('ThirdParty')) OR $(BundleExtraAssemblies.Contains('Game')) OR $(BundleExtraAssemblies.Contains('System')) OR $(BundleExtraAssemblies.Contains('All'))">true</CopyLocalLockFileAssemblies>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(OS)' == 'Windows_NT' AND '$(EnableGameDebugging)' == 'true'">
@@ -45,17 +48,17 @@
   **********************************************-->
   <ItemGroup>
     <!-- game -->
-    <Reference Include="Stardew Valley" HintPath="$(GamePath)\Stardew Valley.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="Stardew Valley" HintPath="$(GamePath)\Stardew Valley.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
-    <Reference Include="StardewValley.GameData" HintPath="$(GamePath)\StardewValley.GameData.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="StardewValley.GameData" HintPath="$(GamePath)\StardewValley.GameData.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
-    <Reference Include="MonoGame.Framework" HintPath="$(GamePath)\MonoGame.Framework.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="MonoGame.Framework" HintPath="$(GamePath)\MonoGame.Framework.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
-    <Reference Include="xTile" HintPath="$(GamePath)\xTile.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="xTile" HintPath="$(GamePath)\xTile.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
 
     <!-- SMAPI -->
-    <Reference Include="StardewModdingAPI" HintPath="$(GamePath)\StardewModdingAPI.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="StardewModdingAPI" HintPath="$(GamePath)\StardewModdingAPI.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
-    <Reference Include="SMAPI.Toolkit.CoreInterfaces" HintPath="$(GamePath)\smapi-internal\SMAPI.Toolkit.CoreInterfaces.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="SMAPI.Toolkit.CoreInterfaces" HintPath="$(GamePath)\smapi-internal\SMAPI.Toolkit.CoreInterfaces.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
 
     <!-- Harmony -->
-    <Reference Include="0Harmony" Condition="'$(EnableHarmony)' == 'true'" HintPath="$(GamePath)\smapi-internal\0Harmony.dll" Private="$(CopyModReferencesToBuildOutput)" />
+    <Reference Include="0Harmony" Condition="'$(EnableHarmony)' == 'true'" HintPath="$(GamePath)\smapi-internal\0Harmony.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
   </ItemGroup>
 
 
@@ -81,6 +84,7 @@
   **********************************************-->
   <Target Name="AfterBuild">
     <DeployModTask
+      ModDllName="$(TargetName)"
       ModFolderName="$(ModFolderName)"
       ModZipPath="$(ModZipPath)"
 
@@ -92,6 +96,8 @@
       GameModsDir="$(GameModsPath)"
       IgnoreModFilePatterns="$(IgnoreModFilePatterns)"
       IgnoreModFilePaths="$(IgnoreModFilePaths)"
+
+      BundleExtraAssemblies="$(BundleExtraAssemblies)"
     />
   </Target>
 </Project>