Project migration and multi-targeting: Fixes and improvements

- Now compiling for .NET Framework 4.0, 4.6.1, and 4.7.2; .NET Standard 2.0 and 2.1; .NET 5.0
- Build script: Implemented analysis of unit test coverage using `JetBrains dotCover`
- Addressed compatibility issues in:
  - `OmnifactotumArrayExtensions`
  - `OmnifactotumAssemblyExtensions`
  - `OmnifactotumCollectionExtensions`
  - `OmnifactotumDictionaryExtensions`
  - `OmnifactotumGenericObjectExtensions`
  - `OmnifactotumOperationContextExtensions`
- Addressed compatibility issues in:
  - `ColoredConsoleTraceListener`
  - `KeyValuePair` (static helper)
  - `ReadOnlyDictionary<TKey, TValue>`
  - `WinEventLog`
- Minor fixes/improvements in:
  - `OmnifactotumDateTimeOffsetExtensions`
- Added new classes:
  - `OmnifactotumKeyValuePair`
  - `ReadOnlyItemCollection` (read-only wrapper for ICollection<T>)
- Implemented fixes and improvements in the test project and tests for proper multi-targeting
- Added tests for:
  - `KeyValuePair`
- Updated build scripts and related configuration files
- Updated `README.md`
- Updated Release Notes (also, converted to Markdown)
- Updated JetBrains Annotations in `Omnifactotum.Annotations`
- Partial support of Nullable Reference Types:
  - `OmnifactotumGenericObjectExtensions.EnsureNotNull`
- Applied `PureAttribute`, `InstantHandleAttribute`, and `NoEnumerationAttribute` annotations in certain appropriate cases
- Made the class `OmnifactotumRepresentationConstants` public (formerly `OmnifactotumConstants`)

.editorconfig

@@ -8,6 +8,32 @@ insert_final_newline = false
 trim_trailing_whitespace = true
 max_line_length = 140
 
+# .NET
+dotnet_diagnostic.IDE0022.severity = none
+dotnet_diagnostic.IDE0066.severity = none
+dotnet_diagnostic.IDE0079.severity = none
+
 [*.{config,cs,csproj,css,DotSettings,js,json,nuspec,ps1,resx,scss,settings,sln,ts,tt,xml}]
 charset = utf-8-bom
 end_of_line = crlf
+
+[*.md]
+charset = utf-8-bom
+end_of_line = crlf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+max_line_length = off
+trim_trailing_whitespace = true
+
+[*.sln]
+indent_style = tab
+
+[*.yml]
+charset = utf-8
+end_of_line = crlf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+max_line_length = off
+trim_trailing_whitespace = true

.gitignore

@@ -1,5 +1,5 @@
-**/bin/*
-**/binTests/*
+**/.out/*
+**/.temp/*
 **/obj/*
 **/packages/*
 **/.vs/*

README.md

@@ -3,6 +3,10 @@ Provides own *helper* and *functional* classes as well as *extension methods* fo
 
 **Note**: `Factotum` is a Latin word literally meaning "do everything" (that is, a *handyman* or *Jack-of-all-trades*).
 
+### Release Notes
+
+- [Release Notes](./src/Omnifactotum.ReleaseNotes.md)
+
 ### Status and Statistics
 - [![Build status](https://ci.appveyor.com/api/projects/status/8kcys4vgvk1cd1gg?svg=true)](https://ci.appveyor.com/project/HarinezumiSama/omnifactotum)
 
@@ -17,24 +21,24 @@ Provides own *helper* and *functional* classes as well as *extension methods* fo
 ### The *non-exaustive* list of .NET classes covered
 
 - Reflection
-  - [**`Assembly`**](https://docs.microsoft.com/en-us/dotnet/api/?term=system.reflection.assembly) extension methods
-  - [**`ICustomAttributeProvider`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Reflection.ICustomAttributeProvider) extension methods (`ICustomAttributeProvider` is implemented by [**`Assembly`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Reflection.Assembly), [**`MethodInfo`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Reflection.MethodInfo), [**`PropertyInfo`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Reflection.PropertyInfo), [**`Type`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Type) etc.)
-  - [**`MethodBase`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Reflection.MethodBase) extension methods
-  - [**`Type`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Type) extension methods
-- Array (**`T[]`**) and collection ([**`IEnumerable<T>`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Collections.Generic.IEnumerable%3CT%3E) and [**`ICollection<T>`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Collections.Generic.ICollection%3CT%3E)) extension methods
-- [**`DateTime`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.DateTime) extension methods
-- [**`DateTimeOffset`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.DateTimeOffset) extension methods
-- [**`Dictionary<TKey, TValue>`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Collections.Generic.Dictionary%3CTKey%2CTValue%3E) extension methods
-- [**`IDisposable`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.IDisposable) extension methods
-- [**`Enum`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Enum) extension methods
-- [**`Exception`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Exception) extension methods
-- [**`Expression<TDelegate>`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Linq.Expressions.Expression%3CTDelegate%3E) extension methods
-- Arbitrary [**`Object`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Object) generic extension methods
+  - [**`Assembly`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.assembly) extension methods
+  - [**`ICustomAttributeProvider`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.icustomattributeprovider) extension methods (`ICustomAttributeProvider` is implemented by [**`Assembly`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.assembly), [**`MethodInfo`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.methodinfo), [**`PropertyInfo`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.propertyinfo), [**`Type`**](https://docs.microsoft.com/en-us/dotnet/api/system.type) etc.)
+  - [**`MethodBase`**](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.methodbase) extension methods
+  - [**`Type`**](https://docs.microsoft.com/en-us/dotnet/api/system.type) extension methods
+- Array (**`T[]`**) and collection ([**`IEnumerable<T>`**](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ienumerable-1) and [**`ICollection<T>`**](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.icollection-1)) extension methods
+- [**`DateTime`**](https://docs.microsoft.com/en-us/dotnet/api/system.datetime) extension methods
+- [**`DateTimeOffset`**](https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset) extension methods
+- [**`Dictionary<TKey, TValue>`**](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.dictionary-2) extension methods
+- [**`IDisposable`**](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable) extension methods
+- [**`Enum`**](https://docs.microsoft.com/en-us/dotnet/api/system.enum) extension methods
+- [**`Exception`**](https://docs.microsoft.com/en-us/dotnet/api/system.exception) extension methods
+- [**`Expression<TDelegate>`**](https://docs.microsoft.com/en-us/dotnet/api/system.linq.expressions.expression-1) extension methods
+- Arbitrary [**`Object`**](https://docs.microsoft.com/en-us/dotnet/api/system.object) generic extension methods
 - Math extension methods for numeric types
-- [**`Nullable<Boolean> (bool?)`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Nullable%3CT%3E) extension methods
-- [**`ISet`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.Collections.Generic.ISet%3CT%3E) extension methods
-- [**`String`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.String) extension methods
-- [**`TimeSpan`**](https://docs.microsoft.com/en-us/dotnet/api/?term=System.TimeSpan) extension methods
+- [**`Nullable<Boolean> (bool?)`**](https://docs.microsoft.com/en-us/dotnet/api/system.nullable-1) extension methods
+- [**`ISet`**](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.iset-1) extension methods
+- [**`String`**](https://docs.microsoft.com/en-us/dotnet/api/system.string) extension methods
+- [**`TimeSpan`**](https://docs.microsoft.com/en-us/dotnet/api/system.timespan) extension methods
 
 ### The *non-exaustive* list of own helper classes
 
@@ -51,8 +55,21 @@ Provides own *helper* and *functional* classes as well as *extension methods* fo
 - `EnumFixedSizeDictionary<TKey, TValue>`
 - `FixedSizeDictionary<TKey, TValue>`
 - `KeyedEqualityComparer<T, TKey>`
-- `ReadOnlyDictionary<TKey, TValue>` <sub><sup>(.NET Framework 4.0 target only; [`System.Collections.ObjectModel.ReadOnlyDictionary<TKey, TValue>`](https://docs.microsoft.com/en-us/dotnet/api/system.collections.objectmodel.readonlydictionary-2?view=net-5.0) is available as of .NET Framework 4.5+)</sup></sub>
+- `ReadOnlyDictionary<TKey, TValue>`
+  - **NOTE**: `.NET Framework 4.0` only; as of `.NET Framework 4.5+` [`System.Collections.ObjectModel.ReadOnlyDictionary<TKey, TValue>`](https://docs.microsoft.com/en-us/dotnet/api/system.collections.objectmodel.readonlydictionary-2?view=netframework-4.5) is available. 
+- `ReadOnlyItemCollection<T>` (the read-only wrapper for [`ICollection<T>`](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.icollection-1))
 - `ReadOnlySet<T>`
 - `ValueRange<T>`
 - `VirtualTreeNode<T>` and `VirtualTreeNodeRoot<T>`
-- `WeakReferenceBasedCache<TKey, TValue>`
+- `WeakReferenceBasedCache<TKey, TValue>`
+
+### Dealing with Compatibility Issues
+
+Due to certain inconsistencies between `.NET Standard 2.0` and `.NET Core 2.x`, you may need to apply one or more workarounds as described below when using **`Omnifactotum`** with your projects compiled for `.NET Standard 2.0` or `.NET Core 2.x` **-or-** a mix of `.NET Standard 2.0` and/or `.NET Core 2.x` and/or `.NET Framework 4.x`:
+
+| Omnifactotum's Class or Method | Workaround |
+| :----------------------------- | :--------- |
+| `System.Collections.Generic.KeyValuePair` | Use [`Omnifactotum.OmnifactotumKeyValuePair`](./src/Omnifactotum/OmnifactotumKeyValuePair.cs). |
+| <code>[OmnifactotumCollectionExtensions](./src/Omnifactotum/ExtensionMethods/OmnifactotumCollectionExtensions.cs).ToHashSet(...)</code> | Use static method invocation instead of extension method invocation. That is: `OmnifactotumCollectionExtensions.ToHashSet(collection)` instead of `collection.ToHashSet()`. |
+| <code>[OmnifactotumDictionaryExtensions](./src/Omnifactotum/ExtensionMethods/OmnifactotumDictionaryExtensions.cs).GetValueOrDefault</code> | Use static method invocation instead of extension method invocation. That is: `OmnifactotumDictionaryExtensions.GetValueOrDefault(dictionary)` instead of `dictionary.GetValueOrDefault()`. |
+

appveyor.yml

@@ -1,34 +1,83 @@
-version: 0.4.{build}
+version: 'Build #{build} [{branch}]'
 pull_requests:
   do_not_increment_build_number: true
 branches:
   only:
   - master
+  - develop
+  - /feature\/.*/
 skip_tags: true
 image: Visual Studio 2019
+configuration: Release
+platform: Any CPU
 shallow_clone: true
 nuget:
   disable_publish_on_pr: true
+matrix:
+  fast_finish: true
+environment:
+  CI_ARG_PRERELEASE_SUFFIX: '-internal'
+  CI_OUT_ARG_DEPLOYMENT_VERSION: ''
+for:
+  -
+    branches:
+      only:
+        - develop
+    environment:
+      CI_ARG_PRERELEASE_SUFFIX: '-prerelease'
+    deploy: off
+  -
+    branches:
+      only:
+        - /^feature\/.*/
+    deploy: off
+  -
+    branches:
+      only:
+        - master
+    environment:
+      CI_ARG_PRERELEASE_SUFFIX: ''
 build_script:
 - ps: >-
-    $Script:ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop
+    $Script:ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop;
 
+    Microsoft.PowerShell.Core\Set-StrictMode -Version 1;
 
-    & .\build.ps1 -Verbose
+
+    & .\build.ps1 `
+        -Verbose `
+        -BuildConfiguration $env:Configuration `
+        -BuildPlatform $env:Platform `
+        -EnableDotCover `
+        -AppveyorBuild `
+        -AppveyorSourceCodeRevisionId $env:APPVEYOR_REPO_COMMIT `
+        -AppveyorBuildNumber $env:APPVEYOR_BUILD_NUMBER `
+        -PrereleaseSuffix $env:CI_ARG_PRERELEASE_SUFFIX
 test: off
 artifacts:
-- path: bin\NuGet\*.nupkg
-  name: NuGet
-- path: bin\AnyCPU\**\*
-  name: bin
-- path: binTests\**\*
-  name: binTests
-deploy: off
+- path: .artifacts\**\*
+  name: Artifacts
+- path: src\.out\bin\AnyCPU\Release\Omnifactotum.Tests\TestResults
+  name: TestResults
+- path: src\.out\binCoverage\Omnifactotum.CoverageResult
+  name: Omnifactotum.CoverageResult
+deploy:
+- provider: GitHub
+  on:
+    branch: master
+  release: '$(CI_OUT_ARG_DEPLOYMENT_VERSION)'
+  description: '$(APPVEYOR_PROJECT_NAME) $(CI_OUT_ARG_DEPLOYMENT_VERSION)'
+  draft: true
+  prerelease: true
+  auth_token:
+    secure: IA0JpDs4+uNdYekaXOOeVdU0sOak2Tz6zwHP1QPjdiXF+JOaqLpGkYVLW928iuEX
+  artifact: Artifacts
 notifications:
 - provider: Email
   to:
   - [email protected]
-  subject: Omnifactotum Build [AppVeyor]
+  - '{{commitAuthorEmail}}'
+  subject: '[AppVeyor] {{projectName}} {{buildVersion}}: Build {{status}} ({{branch}} @ {{commitId}})'
   on_build_success: true
   on_build_failure: true
-  on_build_status_changed: false
+  on_build_status_changed: false

build.cmd

@@ -10,5 +10,5 @@ if not exist "%PS_ExePath%" (
     exit /b 127
 )
 
-"%PS_ExePath%" -ExecutionPolicy RemoteSigned -NonInteractive -Command "%~dpn0.ps1" %* -Verbose:$true
+"%PS_ExePath%" -ExecutionPolicy RemoteSigned -NonInteractive -Command "%~dpn0.ps1" %*
 exit /b %ERRORLEVEL%