Merge pull request #52 from Zastai/use-trace-source

Switch to a `TraceSource` for debug output
Zastai · Dec 17, 2023 · 9c280dc · 9c280dc
2 parents c9b23b5 + 6fa14e9
commit 9c280dc
Show file tree

Hide file tree

Showing 4 changed files with 94 additions and 10 deletions.
diff --git a/MetaBrainz.MusicBrainz.CoverArt/CoverArt.cs b/MetaBrainz.MusicBrainz.CoverArt/CoverArt.cs
@@ -56,6 +56,9 @@ public class CoverArt : IDisposable {
   /// </remarks>
   public const int MaxImageSize = 512 * 1024 * 1024;
 
+  /// <summary>The trace source (named 'MetaBrainz.MusicBrainz.CoverArt') used by this class.</summary>
+  public static readonly TraceSource TraceSource = new("MetaBrainz.MusicBrainz.CoverArt", SourceLevels.Off);
+
   /// <summary>The URL included in the user agent for requests as part of this library's information.</summary>
   public const string UserAgentUrl = "https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt";
 
@@ -732,22 +735,25 @@ private static async Task<IRelease> ParseReleaseAsync(HttpResponseMessage respon
   }
 
   private async Task<HttpResponseMessage> PerformRequestAsync(string address, CancellationToken cancellationToken) {
-    Debug.Print($"[{DateTime.UtcNow}] CAA REQUEST: GET {this.BaseUri}{address}");
-    var client = this.Client;
+    var ts = CoverArt.TraceSource;
+    ts.TraceEvent(TraceEventType.Verbose, 1, "CAA REQUEST: GET {0}{1}", this.BaseUri, address);
     var request = new HttpRequestMessage(HttpMethod.Get, address);
-    var response = await client.SendAsync(request, cancellationToken).ConfigureAwait(false);
-    Debug.Print($"[{DateTime.UtcNow}] => RESPONSE: {(int) response.StatusCode}/{response.StatusCode} '{response.ReasonPhrase}' " +
-                $"(v{response.Version})");
-    Debug.Print($"[{DateTime.UtcNow}] => HEADERS: {TextUtils.FormatMultiLine(response.Headers.ToString())}");
-    Debug.Print($"[{DateTime.UtcNow}] => CONTENT: {response.Content.Headers.ContentType}, " +
-                $"{response.Content.Headers.ContentLength ?? 0} byte(s))");
+    var response = await this.Client.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    if (ts.Switch.ShouldTrace(TraceEventType.Verbose)) {
+      ts.TraceEvent(TraceEventType.Verbose, 2, "RESPONSE: {0}/{1} '{2}' (v{3})", (int) response.StatusCode, response.StatusCode,
+                    response.ReasonPhrase, response.Version);
+      ts.TraceEvent(TraceEventType.Verbose, 3, "HEADERS: {0}", TextUtils.FormatMultiLine(response.Headers.ToString()));
+      ts.TraceEvent(TraceEventType.Verbose, 4, "CONTENT: {0}, {1} byte(s))", response.Content.Headers.ContentType,
+                             response.Content.Headers.ContentLength ?? 0);
+    }
     try {
       return await response.EnsureSuccessfulAsync(cancellationToken).ConfigureAwait(false);
     }
     catch (HttpError error) {
       if (!string.IsNullOrEmpty(error.Content) && error.ContentHeaders?.ContentType?.MediaType == "text/html") {
-        // The contents seems to be of the form:
-        //   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+        // The contents seem to be of the form:
+        //   <!doctype html>
+        //   <html lang=en>
         //   <title>404 Not Found</title>
         //   <h1>Not Found</h1>
         //   <p>No cover art found for release 968db8b7-c519-43e5-bb45-9f244c92b670</p>

diff --git a/README.md b/README.md
@@ -6,7 +6,81 @@ An attempt has been made to keep the same basic class hierarchy.
 
 [CI-S]: https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt/actions/workflows/build.yml/badge.svg
 [CI-L]: https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt/actions/workflows/build.yml
+
 [NuGet-S]: https://img.shields.io/nuget/v/MetaBrainz.MusicBrainz.CoverArt
 [NuGet-L]: https://www.nuget.org/packages/MetaBrainz.MusicBrainz.CoverArt
 
 [api-reference]: https://musicbrainz.org/doc/Cover_Art_Archive/API
+
+## Debugging
+
+The `CoverArt` class provides a `TraceSource` that can be used to
+configure debug output; its name is `MetaBrainz.MusicBrainz.CoverArt`.
+
+### Configuration
+
+#### In Code
+
+In code, you can enable tracing like follows:
+
+```cs
+// Use the default switch, turning it on.
+CoverArt.TraceSource.Switch.Level = SourceLevels.All;
+
+// Alternatively, use your own switch so multiple things can be
+// enabled/disabled at the same time.
+var mySwitch = new TraceSwitch("MyAppDebugSwitch", "All");
+CoverArt.TraceSource.Switch = mySwitch;
+
+// By default, there is a single listener that writes trace events to
+// the debug output (typically only seen in an IDE's debugger). You can
+// add (and remove) listeners as desired.
+var listener = new ConsoleTraceListener {
+  Name = "MyAppConsole",
+  TraceOutputOptions = TraceOptions.DateTime | TraceOptions.ProcessId,
+};
+CoverArt.TraceSource.Listeners.Clear();
+CoverArt.TraceSource.Listeners.Add(listener);
+```
+
+#### In Configuration
+
+Starting from .NET 7 your application can also be set up to read tracing
+configuration from the application configuration file. To do so, the
+application needs to add the following to its startup code:
+
+```cs
+System.Diagnostics.TraceConfiguration.Register();
+```
+
+(Provided by the `System.Configuration.ConfigurationManager` package.)
+
+The application config file can then have a `system.diagnostics` section
+where sources, switches and listeners can be configured.
+
+```xml
+<configuration>
+  <system.diagnostics>
+    <sharedListeners>
+      <add name="console" type="System.Diagnostics.ConsoleTraceListener" traceOutputOptions="DateTime,ProcessId" />
+    </sharedListeners>
+    <sources>
+      <source name="MetaBrainz.MusicBrainz.CoverArt" switchName="MetaBrainz.MusicBrainz.CoverArt">
+        <listeners>
+          <add name="console" />
+          <add name="caa-log" type="System.Diagnostics.TextWriterTraceListener" initializeData="caa.log" />
+        </listeners>
+      </source>
+    </sources>
+    <switches>
+      <add name="MetaBrainz.MusicBrainz.CoverArt" value="All" />
+    </switches>
+  </system.diagnostics>
+</configuration>
+```
+
+## Release Notes
+
+These are available [on GitHub][release-notes].
+
+[release-notes]: https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt/releases
diff --git a/public-api/MetaBrainz.MusicBrainz.CoverArt.net6.0.cs.md b/public-api/MetaBrainz.MusicBrainz.CoverArt.net6.0.cs.md
@@ -16,6 +16,8 @@ public class CoverArt : System.IDisposable {
 
   public const int MaxImageSize = 536870912;
 
+  public static readonly System.Diagnostics.TraceSource TraceSource;
+
   public const string UserAgentUrl = "https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt";
 
   System.Uri BaseUri {

diff --git a/public-api/MetaBrainz.MusicBrainz.CoverArt.net8.0.cs.md b/public-api/MetaBrainz.MusicBrainz.CoverArt.net8.0.cs.md
@@ -16,6 +16,8 @@ public class CoverArt : System.IDisposable {
 
   public const int MaxImageSize = 536870912;
 
+  public static readonly System.Diagnostics.TraceSource TraceSource;
+
   public const string UserAgentUrl = "https://github.com/Zastai/MetaBrainz.MusicBrainz.CoverArt";
 
   System.Uri BaseUri {