/// <summary>Log a deprecation warning.</summary>
/// <param name="source">The friendly mod name which used the deprecated code.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? "<unknown>", nounPhrase, version))
{
return;
}
// build message
string message = $"{source ?? "An unknown mod"} uses deprecated code ({nounPhrase}).";
if (source == null)
{
message += $"{Environment.NewLine}{Environment.StackTrace}";
}
// log message
switch (severity)
{
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 '{severity}'");
}
}
/*********
** Public methods
*********/
/// <summary>Construct an instance.</summary>
/// <param name="modName">The affected mod's display name.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="level">The deprecation level for the affected code.</param>
public DeprecationWarning(string modName, string nounPhrase, string version, DeprecationLevel level)
{
this.ModName = modName;
this.NounPhrase = nounPhrase;
this.Version = version;
this.Level = level;
}
/*********
** Public methods
*********/
/// <summary>Construct an instance.</summary>
/// <param name="modName">The affected mod's display name.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="level">The deprecation level for the affected code.</param>
/// <param name="stackTrace">The stack trace when the deprecation warning was raised.</param>
public DeprecationWarning(string modName, string nounPhrase, string version, DeprecationLevel level, string stackTrace)
{
this.ModName = modName;
this.NounPhrase = nounPhrase;
this.Version = version;
this.Level = level;
this.StackTrace = stackTrace;
}
/// <summary>Log a deprecation warning.</summary>
/// <param name="source">The friendly mod name which used the deprecated code.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? this.GetSourceNameFromStack() ?? "<unknown>", nounPhrase, version))
{
return;
}
// queue warning
this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity, Environment.StackTrace));
}
/// <summary>Log a deprecation warning.</summary>
/// <param name="source">The friendly mod name which used the deprecated code.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? "<unknown>", nounPhrase, version))
{
return;
}
// queue warning
this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity));
}
/// <summary>Log a deprecation warning.</summary>
/// <param name="source">The friendly mod name which used the deprecated code.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? "<unknown>", nounPhrase, version))
{
return;
}
// show SMAPI 2.0 meta-warning
if (this.MarkWarned("SMAPI", "SMAPI 2.0 meta-warning", "2.0"))
{
this.Monitor.Log("Some mods may stop working in SMAPI 2.0 (but they'll work fine for now). Try updating mods with 'deprecated code' warnings; if that doesn't remove the warnings, let the mod authors know about this message or see http://stardewvalleywiki.com/Modding:SMAPI_2.0 for details.", LogLevel.Warn);
}
// build message
string message = $"{source ?? "An unknown mod"} uses deprecated code ({nounPhrase}).";
if (source == null)
{
message += $"{Environment.NewLine}{Environment.StackTrace}";
}
// log message
switch (severity)
{
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 '{severity}'");
}
}
/// <summary>Log a deprecation warning.</summary>
/// <param name="source">The friendly mod name which used the deprecated code.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? "<unknown>", nounPhrase, version))
{
return;
}
// build message
string message = source != null
? $"{source} used {nounPhrase}, which is deprecated since SMAPI {version}."
: $"An unknown mod used {nounPhrase}, which is deprecated since SMAPI {version}.";
message += severity != DeprecationLevel.PendingRemoval
? " This will break in a future version of SMAPI."
: " It will be removed soon, so the mod will break if it's not updated.";
if (source == null)
{
message += $"{Environment.NewLine}{Environment.StackTrace}";
}
// log message
switch (severity)
{
case DeprecationLevel.Notice:
this.Monitor.Log(message, LogLevel.Trace);
break;
case DeprecationLevel.Info:
this.Monitor.Log(message, LogLevel.Warn);
break;
case DeprecationLevel.PendingRemoval:
this.Monitor.Log(message, LogLevel.Warn);
break;
default:
throw new NotImplementedException($"Unknown deprecation level '{severity}'");
}
}
/// <summary>A placeholder method used to track deprecated code for which a separate warning will be shown.</summary>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public void PlaceholderWarn(string version, DeprecationLevel severity)
{
}
/// <summary>Log a deprecation warning.</summary>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <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);
}
/****
** Deprecation
****/
/// <summary>Log a deprecation warning for mods using an event.</summary>
/// <param name="deprecationManager">The deprecation manager to extend.</param>
/// <param name="handlers">The event handlers.</param>
/// <param name="nounPhrase">A noun phrase describing what is deprecated.</param>
/// <param name="version">The SMAPI version which deprecated it.</param>
/// <param name="severity">How deprecated the code is.</param>
public static void WarnForEvent(this DeprecationManager deprecationManager, Delegate[] handlers, string nounPhrase, string version, DeprecationLevel severity)
{
if (handlers == null || !handlers.Any())
{
return;
}
foreach (Delegate handler in handlers)
{
string modName = InternalExtensions.ModRegistry.GetModFrom(handler) ?? "an unknown mod"; // suppress stack trace for unknown mods, not helpful here
deprecationManager.Warn(modName, nounPhrase, version, severity);
}
}
