From fd136d34c5d4fbfc708eabf82a5eb9396d8a4756 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 14 Apr 2022 23:11:41 -0400 Subject: track full mod & stack metadata in queued deprecation warnings --- src/SMAPI/Constants.cs | 2 +- src/SMAPI/Framework/Content/AssetInfo.cs | 4 +-- src/SMAPI/Framework/DeprecationManager.cs | 33 +++++++++++-------------- src/SMAPI/Framework/DeprecationWarning.cs | 17 ++++++++----- src/SMAPI/Framework/ModHelpers/CommandHelper.cs | 2 +- src/SMAPI/Framework/ModHelpers/ContentHelper.cs | 17 +++++-------- src/SMAPI/Framework/ModHelpers/ModHelper.cs | 2 +- src/SMAPI/Framework/SCore.cs | 6 ++--- src/SMAPI/Utilities/PerScreen.cs | 2 +- 9 files changed, 41 insertions(+), 44 deletions(-) diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs index fd2b813a..d40b97f4 100644 --- a/src/SMAPI/Constants.cs +++ b/src/SMAPI/Constants.cs @@ -83,7 +83,7 @@ namespace StardewModdingAPI get { SCore.DeprecationManager.Warn( - source: SCore.DeprecationManager.GetSourceNameFromStack(), + source: SCore.DeprecationManager.GetModFromStack(), nounPhrase: $"{nameof(Constants)}.{nameof(Constants.ExecutionPath)}", version: "3.14.0", severity: DeprecationLevel.Notice diff --git a/src/SMAPI/Framework/Content/AssetInfo.cs b/src/SMAPI/Framework/Content/AssetInfo.cs index 0f0e9bf3..16b71487 100644 --- a/src/SMAPI/Framework/Content/AssetInfo.cs +++ b/src/SMAPI/Framework/Content/AssetInfo.cs @@ -32,7 +32,7 @@ namespace StardewModdingAPI.Framework.Content get { SCore.DeprecationManager.Warn( - source: SCore.DeprecationManager.GetSourceNameFromStack(), + source: SCore.DeprecationManager.GetModFromStack(), nounPhrase: $"{nameof(IAssetInfo)}.{nameof(IAssetInfo.AssetName)}", version: "3.14.0", severity: DeprecationLevel.Notice @@ -68,7 +68,7 @@ namespace StardewModdingAPI.Framework.Content public bool AssetNameEquals(string path) { SCore.DeprecationManager.Warn( - source: SCore.DeprecationManager.GetSourceNameFromStack(), + source: SCore.DeprecationManager.GetModFromStack(), nounPhrase: $"{nameof(IAssetInfo)}.{nameof(IAssetInfo.AssetNameEquals)}", version: "3.14.0", severity: DeprecationLevel.Notice diff --git a/src/SMAPI/Framework/DeprecationManager.cs b/src/SMAPI/Framework/DeprecationManager.cs index 44b0ba2f..c80fdce7 100644 --- a/src/SMAPI/Framework/DeprecationManager.cs +++ b/src/SMAPI/Framework/DeprecationManager.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Diagnostics; using System.Linq; namespace StardewModdingAPI.Framework @@ -35,34 +36,33 @@ namespace StardewModdingAPI.Framework this.ModRegistry = modRegistry; } - /// Get the source name for a mod from its unique ID. - public string? GetSourceNameFromStack() + /// Get a mod for the closest assembly registered as a source of deprecation warnings. + /// Returns the source name, or null if no registered assemblies were found. + public IModMetadata? GetModFromStack() { - return this.ModRegistry.GetFromStack()?.DisplayName; + return this.ModRegistry.GetFromStack(); } - /// Get the source name for a mod from its unique ID. + /// Get a mod from its unique ID. /// The mod's unique ID. - public string? GetSourceName(string modId) + public IModMetadata? GetMod(string modId) { - return this.ModRegistry.Get(modId)?.DisplayName; + return this.ModRegistry.Get(modId); } /// Log a deprecation warning. - /// The friendly mod name which used the deprecated code. + /// The mod which used the deprecated code, if known. /// A noun phrase describing what is deprecated. /// The SMAPI version which deprecated it. /// How deprecated the code is. - public void Warn(string? source, string nounPhrase, string version, DeprecationLevel severity) + public void Warn(IModMetadata? source, string nounPhrase, string version, DeprecationLevel severity) { - source ??= this.GetSourceNameFromStack() ?? ""; - // ignore if already warned if (!this.MarkWarned(source, nounPhrase, version)) return; // queue warning - this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity, Environment.StackTrace)); + this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity, new StackTrace(skipFrames: 1))); } /// A placeholder method used to track deprecated code for which a separate warning will be shown. @@ -104,7 +104,7 @@ namespace StardewModdingAPI.Framework else { this.Monitor.Log(message, level); - this.Monitor.Log(warning.StackTrace, LogLevel.Debug); + this.Monitor.Log(warning.StackTrace.ToString(), LogLevel.Debug); } } @@ -116,16 +116,13 @@ namespace StardewModdingAPI.Framework ** Private methods *********/ /// Mark a deprecation warning as already logged. - /// The friendly name of the assembly which used the deprecated code. + /// The mod which used the deprecated code. /// A noun phrase describing what is deprecated (e.g. "the Extensions.AsInt32 method"). /// The SMAPI version which deprecated it. /// Returns whether the deprecation was successfully marked as warned. Returns false if it was already marked. - private bool MarkWarned(string source, string nounPhrase, string version) + private bool MarkWarned(IModMetadata? source, string nounPhrase, string version) { - if (string.IsNullOrWhiteSpace(source)) - throw new InvalidOperationException("The deprecation source cannot be empty."); - - string key = $"{source}::{nounPhrase}::{version}"; + string key = $"{source?.DisplayName ?? ""}::{nounPhrase}::{version}"; if (this.LoggedDeprecations.Contains(key)) return false; this.LoggedDeprecations.Add(key); diff --git a/src/SMAPI/Framework/DeprecationWarning.cs b/src/SMAPI/Framework/DeprecationWarning.cs index 5201b06c..1e83f679 100644 --- a/src/SMAPI/Framework/DeprecationWarning.cs +++ b/src/SMAPI/Framework/DeprecationWarning.cs @@ -1,3 +1,5 @@ +using System.Diagnostics; + namespace StardewModdingAPI.Framework { /// A deprecation warning for a mod. @@ -6,8 +8,11 @@ namespace StardewModdingAPI.Framework /********* ** Accessors *********/ - /// The affected mod's display name. - public string ModName { get; } + /// The affected mod. + public IModMetadata? Mod { get; } + + /// Get the display name for the affected mod. + public string ModName => this.Mod?.DisplayName ?? ""; /// A noun phrase describing what is deprecated. public string NounPhrase { get; } @@ -19,21 +24,21 @@ namespace StardewModdingAPI.Framework public DeprecationLevel Level { get; } /// The stack trace when the deprecation warning was raised. - public string StackTrace { get; } + public StackTrace StackTrace { get; } /********* ** Public methods *********/ /// Construct an instance. - /// The affected mod's display name. + /// The affected mod. /// A noun phrase describing what is deprecated. /// The SMAPI version which deprecated it. /// The deprecation level for the affected code. /// The stack trace when the deprecation warning was raised. - public DeprecationWarning(string modName, string nounPhrase, string version, DeprecationLevel level, string stackTrace) + public DeprecationWarning(IModMetadata? mod, string nounPhrase, string version, DeprecationLevel level, StackTrace stackTrace) { - this.ModName = modName; + this.Mod = mod; this.NounPhrase = nounPhrase; this.Version = version; this.Level = level; diff --git a/src/SMAPI/Framework/ModHelpers/CommandHelper.cs b/src/SMAPI/Framework/ModHelpers/CommandHelper.cs index 319922a9..e430fb1c 100644 --- a/src/SMAPI/Framework/ModHelpers/CommandHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/CommandHelper.cs @@ -36,7 +36,7 @@ namespace StardewModdingAPI.Framework.ModHelpers public bool Trigger(string name, string[] arguments) { SCore.DeprecationManager.Warn( - source: SCore.DeprecationManager.GetSourceName(this.ModID), + source: SCore.DeprecationManager.GetMod(this.ModID), nounPhrase: $"{nameof(IModHelper)}.{nameof(IModHelper.ConsoleCommands)}.{nameof(ICommandHelper.Trigger)}", version: "3.8.1", severity: DeprecationLevel.Notice diff --git a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs index 7cffcee1..534ac138 100644 --- a/src/SMAPI/Framework/ModHelpers/ContentHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ContentHelper.cs @@ -29,9 +29,6 @@ namespace StardewModdingAPI.Framework.ModHelpers /// A content manager for this mod which manages files from the mod's folder. private readonly ModContentManager ModContentManager; - /// The friendly mod name for use in errors. - private readonly string ModName; - /// Encapsulates monitoring and logging. private readonly IMonitor Monitor; @@ -60,7 +57,7 @@ namespace StardewModdingAPI.Framework.ModHelpers get { SCore.DeprecationManager.Warn( - source: this.ModName, + source: this.Mod, nounPhrase: $"{nameof(IContentHelper)}.{nameof(IContentHelper.AssetLoaders)}", version: "3.14.0", severity: DeprecationLevel.Notice @@ -76,7 +73,7 @@ namespace StardewModdingAPI.Framework.ModHelpers get { SCore.DeprecationManager.Warn( - source: this.ModName, + source: this.Mod, nounPhrase: $"{nameof(IContentHelper)}.{nameof(IContentHelper.AssetEditors)}", version: "3.14.0", severity: DeprecationLevel.Notice @@ -94,18 +91,16 @@ namespace StardewModdingAPI.Framework.ModHelpers /// SMAPI's core content logic. /// The absolute path to the mod folder. /// The mod using this instance. - /// The friendly mod name for use in errors. /// Encapsulates monitoring and logging. /// Simplifies access to private code. - public ContentHelper(ContentCoordinator contentCore, string modFolderPath, IModMetadata mod, string modName, IMonitor monitor, Reflector reflection) + public ContentHelper(ContentCoordinator contentCore, string modFolderPath, IModMetadata mod, IMonitor monitor, Reflector reflection) : base(mod) { string managedAssetPrefix = contentCore.GetManagedAssetPrefix(mod.Manifest.UniqueID); this.ContentCore = contentCore; this.GameContentManager = contentCore.CreateGameContentManager(managedAssetPrefix + ".content"); - this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, modName, modFolderPath, this.GameContentManager); - this.ModName = modName; + this.ModContentManager = contentCore.CreateModContentManager(managedAssetPrefix, this.Mod.DisplayName, modFolderPath, this.GameContentManager); this.Monitor = monitor; this.Reflection = reflection; } @@ -128,12 +123,12 @@ namespace StardewModdingAPI.Framework.ModHelpers return this.ModContentManager.LoadExact(assetName, useCache: false); default: - throw new SContentLoadException($"{this.ModName} failed loading content asset '{key}' from {source}: unknown content source '{source}'."); + throw new SContentLoadException($"{this.Mod.DisplayName} failed loading content asset '{key}' from {source}: unknown content source '{source}'."); } } catch (Exception ex) when (ex is not SContentLoadException) { - throw new SContentLoadException($"{this.ModName} failed loading content asset '{key}' from {source}.", ex); + throw new SContentLoadException($"{this.Mod.DisplayName} failed loading content asset '{key}' from {source}.", ex); } } diff --git a/src/SMAPI/Framework/ModHelpers/ModHelper.cs b/src/SMAPI/Framework/ModHelpers/ModHelper.cs index 4eb91f05..5b450c36 100644 --- a/src/SMAPI/Framework/ModHelpers/ModHelper.cs +++ b/src/SMAPI/Framework/ModHelpers/ModHelper.cs @@ -32,7 +32,7 @@ namespace StardewModdingAPI.Framework.ModHelpers get { SCore.DeprecationManager.Warn( - source: SCore.DeprecationManager.GetSourceName(this.ModID), + source: SCore.DeprecationManager.GetMod(this.ModID), nounPhrase: $"{nameof(IModHelper)}.{nameof(IModHelper.Content)}", version: "3.14.0", severity: DeprecationLevel.Notice diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs index 814ac56f..990fe5ea 100644 --- a/src/SMAPI/Framework/SCore.cs +++ b/src/SMAPI/Framework/SCore.cs @@ -1598,7 +1598,7 @@ namespace StardewModdingAPI.Framework if (metadata.Mod is IAssetEditor editor) { SCore.DeprecationManager.Warn( - source: metadata.DisplayName, + source: metadata, nounPhrase: $"{nameof(IAssetEditor)}", version: "3.14.0", severity: DeprecationLevel.Notice @@ -1610,7 +1610,7 @@ namespace StardewModdingAPI.Framework if (metadata.Mod is IAssetLoader loader) { SCore.DeprecationManager.Warn( - source: metadata.DisplayName, + source: metadata, nounPhrase: $"{nameof(IAssetLoader)}", version: "3.14.0", severity: DeprecationLevel.Notice @@ -1846,7 +1846,7 @@ namespace StardewModdingAPI.Framework ICommandHelper commandHelper = new CommandHelper(mod, this.CommandManager); CaseInsensitivePathCache relativePathCache = this.ContentCore.GetCaseInsensitivePathCache(mod.DirectoryPath); #pragma warning disable CS0612 // deprecated code - ContentHelper contentHelper = new(contentCore, mod.DirectoryPath, mod, mod.DisplayName, monitor, this.Reflection); + ContentHelper contentHelper = new(contentCore, mod.DirectoryPath, mod, monitor, this.Reflection); #pragma warning restore CS0612 GameContentHelper gameContentHelper = new(contentCore, mod, mod.DisplayName, monitor, this.Reflection); IModContentHelper modContentHelper = new ModContentHelper(contentCore, mod.DirectoryPath, mod, mod.DisplayName, gameContentHelper.GetUnderlyingContentManager(), relativePathCache, this.Reflection); diff --git a/src/SMAPI/Utilities/PerScreen.cs b/src/SMAPI/Utilities/PerScreen.cs index ba4f3325..6c2e436b 100644 --- a/src/SMAPI/Utilities/PerScreen.cs +++ b/src/SMAPI/Utilities/PerScreen.cs @@ -96,7 +96,7 @@ namespace StardewModdingAPI.Utilities if (!nullExpected) { SCore.DeprecationManager.Warn( - SCore.DeprecationManager.GetSourceNameFromStack(), + SCore.DeprecationManager.GetModFromStack(), $"calling the {nameof(PerScreen)} constructor with null", "3.14.0", DeprecationLevel.Notice -- cgit