using System; using System.Collections.Generic; using System.Linq; namespace StardewModdingAPI.Framework { /// Manages deprecation warnings. internal class DeprecationManager { /********* ** Properties *********/ /// The deprecations which have already been logged (as 'mod name::noun phrase::version'). private readonly HashSet LoggedDeprecations = new HashSet(StringComparer.InvariantCultureIgnoreCase); /// Encapsulates monitoring and logging for a given module. private readonly IMonitor Monitor; /// Tracks the installed mods. private readonly ModRegistry ModRegistry; /// The queued deprecation warnings to display. private readonly IList QueuedWarnings = new List(); /********* ** Public methods *********/ /// Construct an instance. /// Encapsulates monitoring and logging for a given module. /// Tracks the installed mods. public DeprecationManager(IMonitor monitor, ModRegistry modRegistry) { this.Monitor = monitor; this.ModRegistry = modRegistry; } /// Log a deprecation warning. /// A noun phrase describing what is deprecated. /// The SMAPI version which deprecated it. /// How deprecated the code is. public void Warn(string nounPhrase, string version, DeprecationLevel severity) { this.Warn(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version, severity); } /// Log a deprecation warning. /// The friendly mod name which used the deprecated code. /// 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) { // ignore if already warned if (!this.MarkWarned(source ?? "", nounPhrase, version)) return; // queue warning this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity)); } /// Print any queued messages. public void PrintQueued() { foreach (DeprecationWarning warning in this.QueuedWarnings.OrderBy(p => p.ModName).ThenBy(p => p.NounPhrase)) { // build message string message = $"{warning.ModName ?? "An unknown mod"} uses deprecated code ({warning.NounPhrase} is deprecated since SMAPI {warning.Version})."; if (warning.ModName == null) message += $"{Environment.NewLine}{Environment.StackTrace}"; // log message switch (warning.Level) { case DeprecationLevel.Notice: this.Monitor.Log(message, LogLevel.Trace); break; case DeprecationLevel.Info: this.Monitor.Log(message, LogLevel.Debug); break; case DeprecationLevel.PendingRemoval: this.Monitor.Log(message, LogLevel.Warn); break; default: throw new NotSupportedException($"Unknown deprecation level '{warning.Level}'."); } } this.QueuedWarnings.Clear(); } /// Mark a deprecation warning as already logged. /// 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. public bool MarkWarned(string nounPhrase, string version) { return this.MarkWarned(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version); } /// Mark a deprecation warning as already logged. /// The friendly name of the assembly 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. public bool MarkWarned(string source, string nounPhrase, string version) { if (string.IsNullOrWhiteSpace(source)) throw new InvalidOperationException("The deprecation source cannot be empty."); string key = $"{source}::{nounPhrase}::{version}"; if (this.LoggedDeprecations.Contains(key)) return false; this.LoggedDeprecations.Add(key); return true; } } }