Merge branch 'release/1.1.0'

.gitignore

@@ -337,4 +337,5 @@ ASALocalRun/
 .localhistory/
 
 # BeatPulse healthcheck temp database
-healthchecksdb
+healthchecksdb
+/TA.Utils.Logging.Nlog/TA.Utils.Logging.Nlog.xml

.vscode/launch.json

@@ -0,0 +1,7 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": []
+}

.vscode/tasks.json

@@ -0,0 +1,37 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "command": "dotnet",
+            "type": "shell",
+            "args": [
+                "build",
+                "/property:GenerateFullPaths=true",
+                "/consoleloggerparameters:NoSummary"
+            ],
+            "group": "build",
+            "presentation": {
+                "reveal": "silent"
+            },
+            "problemMatcher": "$msCompile"
+        },
+        {
+            "label": "clean",
+            "command": "dotnet",
+            "type": "shell",
+            "args": [
+                "clean",
+                "/property:GenerateFullPaths=true",
+                "/consoleloggerparameters:NoSummary"
+            ],
+            "group": "build",
+            "presentation": {
+                "reveal": "silent"
+            },
+            "problemMatcher": []
+        }
+    ]
+}

Push-Packages.ps1

@@ -2,6 +2,12 @@
 # Assumes that the API key for the relevant feeds has been installed in NuGet.
 # Searches the current directory and child directories recursively.
 
+param (
+    [string]$ApiKey = $null
+    )
+
+if ($ApiKey) { $setApiKey = "-ApiKey " + $ApiKey }
+
 $packageFeed = "https://www.myget.org/F/tigra-astronomy/api/v2/package"
 $symbolFeed = "https://www.myget.org/F/tigra-astronomy/api/v3/index.json"
 
@@ -11,10 +17,10 @@ foreach ($package in $releasePackages)
 {
     if ($package.Name -like "*.snupkg")
     {
-        NuGet.exe push -Source $symbolFeed $package
+        NuGet.exe push -Source $symbolFeed $package $setApiKey
     }
     else
     {
-        NuGet.exe push -Source $packageFeed $package
+        NuGet.exe push -Source $packageFeed $package $setApiKey
     }
 }

TA.Utils.Core/AsyncExtensions.cs

@@ -36,6 +36,7 @@ public static async Task<T> WithCancellation<T>(this Task<T> task, CancellationT
         /// <summary>
         ///     Configures a task to schedule its completion on any available thread. Use this when awaiting
         ///     tasks in a user interface thread to avoid deadlock issues.
+        ///     This is the recommended best practice for library writers.
         /// </summary>
         /// <typeparam name="TResult">The type of the result.</typeparam>
         /// <param name="task">The task to configure.</param>
@@ -48,6 +49,7 @@ public static ConfiguredTaskAwaitable<TResult> ContinueOnAnyThread<TResult>(this
         /// <summary>
         ///     Configures a task to schedule its completion on any available thread. Use this when awaiting
         ///     tasks in a user interface thread to avoid deadlock issues.
+        ///     This is the recommended best practice for library writers.
         /// </summary>
         /// <param name="task">The task to configure.</param>
         /// <returns>An awaitable object that may schedule continuation on any thread.</returns>
@@ -66,9 +68,29 @@ public static ConfiguredTaskAwaitable ContinueOnAnyThread(this Task task)
         /// <param name="task">The task.</param>
         /// <returns>ConfiguredTaskAwaitable.</returns>
         /// <seealso cref="ContinueOnAnyThread" />
+        [Obsolete("Use ContinueInCurrentContext() instead")]
         public static ConfiguredTaskAwaitable ContinueOnCurrentThread(this Task task)
             {
             return task.ConfigureAwait(continueOnCapturedContext: true);
             }
+
+        /// <summary>
+        ///     Configures a task awaiter to schedule continuation on the captured synchronization context.
+        ///     What happens next depends on the current synchronization context.
+        ///     In a Single Threaded Apartment (STA thread) such as a UI thread, the continuation should
+        ///     execute on the same thread. However in a free threaded context, the continuation can
+        ///     still happen on a different thread. This can be risky when the awaiter is a single
+        ///     threaded apartment (STA) thread. If the awaiter blocks waiting for the task, then
+        ///     the continuation may never execute, preventign completion and resulting in deadlock.
+        ///     Use with care.
+        /// </summary>
+        /// <param name="task">The task.</param>
+        /// <returns>ConfiguredTaskAwaitable.</returns>
+        /// <seealso cref="ContinueOnAnyThread" />
+
+        public static ConfiguredTaskAwaitable ContinueInCurrentContext(this Task task)
+            {
+            return task.ConfigureAwait(continueOnCapturedContext: true);
+            }
         }
     }

TA.Utils.Core/Diagnostics/DegenerateLogBuilder.cs

@@ -0,0 +1,66 @@
+// This file is part of the TA.Ascom.ReactiveCommunications project
+//
+// Copyright © 2015-2020 Tigra Astronomy, all rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+// documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so. The Software comes with no warranty of any kind.
+// You make use of the Software entirely at your own risk and assume all liability arising from your use thereof.
+//
+// File: DegenerateLogBuilder.cs  Last modified: 2020-07-14@09:03 by Tim Long
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+
+namespace TA.Utils.Core.Diagnostics
+    {
+    /// <summary>
+    /// A degenerate log builder that does nothing and produces no output.
+    /// Can be used as a default log builder when logging is disabled.
+    /// Implements the <see cref="TA.Utils.Core.Diagnostics.IFluentLogBuilder" />
+    /// </summary>
+    /// <seealso cref="TA.Utils.Core.Diagnostics.IFluentLogBuilder" />
+    public sealed class DegenerateLogBuilder : IFluentLogBuilder
+        {
+        /// <inheritdoc />
+        public IFluentLogBuilder Exception(Exception exception) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder LoggerName(string loggerName) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Message(string message) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Message(string format, params object[] args) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Message(IFormatProvider provider, string format, params object[] args) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Property(string name, object value) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Properties(IDictionary<string, object> properties) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder TimeStamp(DateTime timeStamp) => this;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder StackTrace(StackTrace stackTrace, int userStackFrame) => this;
+
+        /// <inheritdoc />
+        public void Write(string callerMemberName = null, string callerFilePath = null,
+            int callerLineNumber = default) { }
+
+        /// <inheritdoc />
+        public void WriteIf(Func<bool> condition, string callerMemberName = null, string callerFilePath = null,
+            int callerLineNumber = default) { }
+
+        /// <inheritdoc />
+        public void WriteIf(bool condition, string callerMemberName = null, string callerFilePath = null,
+            int callerLineNumber = default) { }
+        }
+    }

TA.Utils.Core/Diagnostics/DegenerateLoggerService.cs

@@ -0,0 +1,43 @@
+// This file is part of the TA.Ascom.ReactiveCommunications project
+// 
+// Copyright © 2015-2020 Tigra Astronomy, all rights reserved.
+// 
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+// documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so. The Software comes with no warranty of any kind.
+// You make use of the Software entirely at your own risk and assume all liability arising from your use thereof.
+// 
+// File: DegenerateLoggerService.cs  Last modified: 2020-07-14@09:02 by Tim Long
+
+namespace TA.Utils.Core.Diagnostics
+    {
+    /// <summary>
+    ///     This is the default logging service used if non is supplied by the user. The service does
+    ///     nothing and produces no output. It is essentially "logging disabled".
+    /// </summary>
+    public sealed class DegenerateLoggerService : ILog
+        {
+        private static IFluentLogBuilder builder = new DegenerateLogBuilder();
+        /// <inheritdoc />
+        public IFluentLogBuilder Trace(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Debug(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Info(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Warn(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Error(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public IFluentLogBuilder Fatal(string callerFilePath = null) => builder;
+
+        /// <inheritdoc />
+        public void Shutdown() { }
+        }
+    }

TA.Utils.Core/Diagnostics/IFluentLogBuilder.cs

@@ -0,0 +1,96 @@
+// This file is part of the TA.Ascom.ReactiveCommunications project
+//
+// Copyright © 2015-2020 Tigra Astronomy, all rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+// documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+// the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so. The Software comes with no warranty of any kind.
+// You make use of the Software entirely at your own risk and assume all liability arising from your use thereof.
+//
+// File: IFluentLogBuilder.cs  Last modified: 2020-07-14@07:01 by Tim Long
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace TA.Utils.Core.Diagnostics
+    {
+    /// <summary>
+    /// Fluent Log Builder
+    /// </summary>
+    public interface IFluentLogBuilder
+        {
+        /// <summary>
+        /// Add an exception to the log entry.
+        /// </summary>
+        IFluentLogBuilder Exception(Exception exception);
+
+        /// <summary>
+        /// Set the log (source) name. By default, this is the name of the source file.
+        /// </summary>
+        IFluentLogBuilder LoggerName(string loggerName);
+
+        /// <summary>
+        /// Sets the message template for the log entry.
+        /// The message may be a simple plain text string,
+        /// it may contain numbered substitution tokens like string.Format,
+        /// or it may contain named substitution tokens enclosed in {braces}
+        /// </summary>
+        IFluentLogBuilder Message(string message);
+
+        /// <summary>
+        /// Sets the message template and property values for the log entry.
+        /// The format string may use numbered positional placeholders like string.Format,
+        /// or it may contain named substitution tokens enclosed in {braces}.
+        /// </summary>
+        IFluentLogBuilder Message(string format, params object[] args);
+
+        /// <summary>
+        /// Sets the message template and property values for the log entry.
+        /// The format provider will be used when rendering the property values.
+        /// </summary>
+        IFluentLogBuilder Message(IFormatProvider provider, string format, params object[] args);
+
+        /// <summary>
+        /// Adds a named property and value pair to the log entry.
+        /// </summary>
+        IFluentLogBuilder Property(string name, object value);
+
+        /// <summary>
+        /// Adds a collection of property/value pairs to the log entry.
+        /// </summary>
+        IFluentLogBuilder Properties(IDictionary<string,object> properties);
+
+        /// <summary>
+        /// Sets the time stamp of the log entry.
+        /// If not set, the log entry will be timed at the moment Write() was called.
+        /// </summary>
+        IFluentLogBuilder TimeStamp(DateTime timeStamp);
+
+        /// <summary>
+        /// Adds a stack trace to the log entry.
+        /// </summary>
+        IFluentLogBuilder StackTrace(StackTrace stackTrace, int userStackFrame);
+
+        /// <summary>
+        /// Writes the log entry.
+        /// </summary>
+        void Write([CallerMemberName] string callerMemberName = null, [CallerFilePath] string callerFilePath = null,
+            [CallerLineNumber] int callerLineNumber = default);
+
+        /// <summary>
+        /// Writes the log entry if the supplied predicate is true.
+        /// </summary>
+        void WriteIf(Func<bool> condition, [CallerMemberName] string callerMemberName = null,
+            [CallerFilePath] string callerFilePath = null, [CallerLineNumber] int callerLineNumber = default);
+
+        /// <summary>
+        /// Writes the log entry if the boolean condition is true.
+        /// </summary>
+        void WriteIf(bool condition, [CallerMemberName] string callerMemberName = null,
+            [CallerFilePath] string callerFilePath = null, [CallerLineNumber] int callerLineNumber = default);
+        }
+    }