Fix comments, typos and add property validation to Microsoft.Extensions.Logging.AzureAppServices (#509)

Author: pakrym

src/Microsoft.Extensions.Logging.AzureAppServices/AzureAppServicesDiagnosticsSettings.cs

@@ -11,44 +11,152 @@ namespace Microsoft.Extensions.Logging.AzureAppServices
     /// </summary>
     public class AzureAppServicesDiagnosticsSettings
     {
+        private TimeSpan _blobCommitPeriod = TimeSpan.FromSeconds(5);
+        private int _blobBatchSize = 32;
+        private string _outputTemplate = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] {Message}{NewLine}{Exception}";
+        private int _retainedFileCountLimit = 2;
+        private int _fileSizeLimit = 10 * 1024 * 1024;
+        private string _blobName = "applicationLog.txt";
+        private TimeSpan? _fileFlushPeriod = TimeSpan.FromSeconds(1);
+        private int _backgroundQueueSize;
+
         /// <summary>
-        /// Gets or sets a strictly positive value representing the maximum log size in bytes. Once the log is full, no more message will be appended.
+        /// Gets or sets a strictly positive value representing the maximum log size in bytes.
+        /// Once the log is full, no more messages will be appended.
+        /// Defaults to <c>10MB</c>.
         /// </summary>
-        public int FileSizeLimit { get; set; } = 10 * 1024 * 1024;
+        public int FileSizeLimit
+        {
+            get { return _fileSizeLimit; }
+            set
+            {
+                if (value <= 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(FileSizeLimit)} must be positive.");
+                }
+                _fileSizeLimit = value;
+            }
+        }
 
         /// <summary>
         /// Gets or sets a strictly positive value representing the maximum retained file count.
+        /// Defaults to <c>2</c>.
         /// </summary>
-        public int RetainedFileCountLimit { get; set; } = 2;
+        public int RetainedFileCountLimit
+        {
+            get { return _retainedFileCountLimit; }
+            set
+            {
+                if (value <= 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(RetainedFileCountLimit)} must be positive.");
+                }
+                _retainedFileCountLimit = value;
+            }
+        }
 
         /// <summary>
         /// Gets or sets a message template describing the output messages.
+        /// Defaults to <c>"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] {Message}{NewLine}{Exception}"</c>.
         /// </summary>
-        public string OutputTemplate { get; set; } = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] {Message}{NewLine}{Exception}";
+        public string OutputTemplate
+        {
+            get { return _outputTemplate; }
+            set
+            {
+                if (string.IsNullOrWhiteSpace(value))
+                {
+                    throw new ArgumentException(nameof(value), $"{nameof(OutputTemplate)} must be non-empty string.");
+                }
+                _outputTemplate = value;
+            }
+        }
 
         /// <summary>
         /// Gets or sets a maximum number of events to include in a single blob append batch.
+        /// Defaults to <c>32</c>.
         /// </summary>
-        public int BlobBatchSize { get; set; } = 32;
+        public int BlobBatchSize
+        {
+            get { return _blobBatchSize; }
+            set
+            {
+                if (value <= 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(BlobBatchSize)} must be positive.");
+                }
+                _blobBatchSize = value;
+            }
+        }
 
         /// <summary>
         /// Gets or sets a time to wait between checking for blob log batches.
+        /// Defaults to 5 seconds.
         /// </summary>
-        public TimeSpan BlobCommitPeriod { get; set; } = TimeSpan.FromSeconds(5);
+        public TimeSpan BlobCommitPeriod
+        {
+            get { return _blobCommitPeriod; }
+            set
+            {
+                if (value < TimeSpan.Zero)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(BlobCommitPeriod)} must be positive.");
+                }
+                _blobCommitPeriod = value;
+            }
+        }
 
         /// <summary>
         /// Gets or sets the last section of log blob name.
+        /// Defaults to <c>"applicationLog.txt"</c>.
         /// </summary>
-        public string BlobName { get; set; } = "applicationLog.txt";
+        public string BlobName
+        {
+            get { return _blobName; }
+            set
+            {
+                if (string.IsNullOrWhiteSpace(value))
+                {
+                    throw new ArgumentException(nameof(value), $"{nameof(BlobName)} must be non-empty string.");
+                }
+                _blobName = value;
+            }
+        }
 
         /// <summary>
-        /// Gets of sets the maximum size of the background log message queue.
+        /// Gets or sets the maximum size of the background log message queue or 0 for no limit.
+        /// After maximum queue size is reached log event sink would start blocking.
+        /// Defaults to <c>0</c>.
         /// </summary>
-        public int BackgroundQueueSize { get; set; }
+        public int BackgroundQueueSize
+        {
+            get { return _backgroundQueueSize; }
+            set
+            {
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(BackgroundQueueSize)} must be positive or 0.");
+                }
+                _backgroundQueueSize = value;
+            }
+        }
 
         /// <summary>
-        /// Gets or sets the period after which logs will be flushed to disk.
+        /// Gets or sets the period after which logs will be flushed to disk or
+        /// <c>null</c> if auto flushing is not required.
+        /// Defaults to 1 second.
         /// </summary>
-        public TimeSpan? FileFlushPeriod { get; set; } = TimeSpan.FromSeconds(1);
+        public TimeSpan? FileFlushPeriod
+        {
+            get { return _fileFlushPeriod; }
+            set
+            {
+                if (value < TimeSpan.Zero)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), $"{nameof(FileFlushPeriod)} must be positive.");
+                }
+                _fileFlushPeriod = value;
+            }
+        }
     }
 }

src/Microsoft.Extensions.Logging.AzureAppServices/Internal/AzureBlobSink.cs

@@ -54,11 +54,11 @@ public AzureBlobSink(Func<string, ICloudAppendBlob> blobReferenceFactory,
             }
             if (batchSizeLimit <= 0)
             {
-                throw new ArgumentOutOfRangeException(nameof(batchSizeLimit), $"{nameof(batchSizeLimit)} should be a positive number.");
+                throw new ArgumentOutOfRangeException(nameof(batchSizeLimit), $"{nameof(batchSizeLimit)} must be a positive number.");
             }
             if (period <= TimeSpan.Zero)
             {
-                throw new ArgumentOutOfRangeException(nameof(period), $"{nameof(period)} should be longer than zero.");
+                throw new ArgumentOutOfRangeException(nameof(period), $"{nameof(period)} must be longer than zero.");
             }
 
             _appName = appName;

src/Microsoft.Extensions.Logging.AzureAppServices/Internal/FileLoggerProvider.cs

@@ -40,11 +40,11 @@ public FileLoggerProvider(int fileSizeLimit, int retainedFileCountLimit, int bac
             }
             if (fileSizeLimit <= 0)
             {
-                throw new ArgumentOutOfRangeException(nameof(fileSizeLimit), $"{nameof(fileSizeLimit)} should be positive.");
+                throw new ArgumentOutOfRangeException(nameof(fileSizeLimit), $"{nameof(fileSizeLimit)} must be positive.");
             }
             if (retainedFileCountLimit <= 0)
             {
-                throw new ArgumentOutOfRangeException(nameof(retainedFileCountLimit), $"{nameof(retainedFileCountLimit)} should be positive.");
+                throw new ArgumentOutOfRangeException(nameof(retainedFileCountLimit), $"{nameof(retainedFileCountLimit)} must be positive.");
             }
 
             _fileSizeLimit = fileSizeLimit;

src/Microsoft.Extensions.Logging.AzureAppServices/project.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0-*",
-  "description": "Diagnostics logger for Azure WebApps",
+  "description": "Logger implementation to support Azure App Services 'Diagnostics logs' and 'Log stream' features.",
   "packOptions": {
     "tags": [
       "logging"