deprecate ConsoleCommands.Trigger method

docs/release-notes.md

@@ -14,6 +14,7 @@
 * For modders:
   * World events are now raised for the volcano levels.
   * Added `apply_save_fix` command to reapply a save migration in exceptional cases. This should be used with extreme care. Type `help apply_save_fix` for details.
+  * **Deprecation notice:** the `Helper.ConsoleCommands.Trigger` method is now deprecated and should no longer be used. See [integration APIs](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Integrations) for better mod integration options. It will eventually be removed in SMAPI 4.0.
 
 For the web UI:
   * Fixed edge cases in SMAPI log parsing.

src/SMAPI/Framework/DeprecationManager.cs

@@ -35,19 +35,17 @@ namespace StardewModdingAPI.Framework
             this.ModRegistry = modRegistry;
         }
 
-        /// <summary>Log a deprecation warning for the old-style events.</summary>
+        /// <summary>Get the source name for a mod from its unique ID.</summary>
-        public void WarnForOldEvents()
+        public string GetSourceNameFromStack()
         {
-            this.Warn("legacy events", "2.9", DeprecationLevel.PendingRemoval);
+            return this.ModRegistry.GetFromStack()?.DisplayName;
         }
 
-        /// <summary>Log a deprecation warning.</summary>
+        /// <summary>Get the source name for a mod from its unique ID.</summary>
-        /// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
+        /// <param name="modId">The mod's unique ID.</param>
-        /// <param name="version">The SMAPI version which deprecated it.</param>
+        public string GetSourceName(string modId)
-        /// <param name="severity">How deprecated the code is.</param>
-        public void Warn(string nounPhrase, string version, DeprecationLevel severity)
         {
-            this.Warn(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version, severity);
+            return this.ModRegistry.Get(modId)?.DisplayName;
         }
 
         /// <summary>Log a deprecation warning.</summary>
@@ -58,7 +56,7 @@ namespace StardewModdingAPI.Framework
         public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
         {
             // ignore if already warned
-            if (!this.MarkWarned(source ?? "<unknown>", nounPhrase, version))
+            if (!this.MarkWarned(source ?? this.GetSourceNameFromStack() ?? "<unknown>", nounPhrase, version))
                 return;
 
             // queue warning
@@ -111,21 +109,16 @@ namespace StardewModdingAPI.Framework
             this.QueuedWarnings.Clear();
         }
 
-        /// <summary>Mark a deprecation warning as already logged.</summary>
-        /// <param name="nounPhrase">A noun phrase describing what is deprecated (e.g. "the Extensions.AsInt32 method").</param>
-        /// <param name="version">The SMAPI version which deprecated it.</param>
-        /// <returns>Returns whether the deprecation was successfully marked as warned. Returns <c>false</c> if it was already marked.</returns>
-        public bool MarkWarned(string nounPhrase, string version)
-        {
-            return this.MarkWarned(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version);
-        }
 
+        /*********
+        ** Private methods
+        *********/
         /// <summary>Mark a deprecation warning as already logged.</summary>
         /// <param name="source">The friendly name of the assembly which used the deprecated code.</param>
         /// <param name="nounPhrase">A noun phrase describing what is deprecated (e.g. "the Extensions.AsInt32 method").</param>
         /// <param name="version">The SMAPI version which deprecated it.</param>
         /// <returns>Returns whether the deprecation was successfully marked as warned. Returns <c>false</c> if it was already marked.</returns>
-        public bool MarkWarned(string source, string nounPhrase, string version)
+        private bool MarkWarned(string source, string nounPhrase, string version)
         {
             if (string.IsNullOrWhiteSpace(source))
                 throw new InvalidOperationException("The deprecation source cannot be empty.");

src/SMAPI/Framework/ModHelpers/CommandHelper.cs

@@ -36,8 +36,16 @@ namespace StardewModdingAPI.Framework.ModHelpers
         }
 
         /// <inheritdoc />
+        [Obsolete]
         public bool Trigger(string name, string[] arguments)
         {
+            SCore.DeprecationManager.Warn(
+                source: SCore.DeprecationManager.GetSourceName(this.ModID),
+                nounPhrase: $"{nameof(IModHelper)}.{nameof(IModHelper.ConsoleCommands)}.{nameof(ICommandHelper.Trigger)}",
+                version: "3.8.1",
+                severity: DeprecationLevel.Notice
+            );
+
             return this.CommandManager.Trigger(name, arguments);
         }
     }