scottdorman / cadru

A Microsoft .NET Framework toolkit

Cadru

What is Cadru?

Cadru is a collection of NuGet packages containing new APIs and extensions to the core .NET Framework to help complete your developer toolbox. It is designed to be cross-platform and targets .NET Standard 2.1.

What's in it?

Cadru is made up of the following packages:

Cadru.AspNetCore

Provides ASP.NET Core middleware and other extensions for request and/response logging.

Cadru.AspNetCore.Mvc

Provides additional support for working with ASP.NET Core, such as custom view location expanders, support for IMetadataAware, and rendering enumerated types as SelectLists based on a UiHint attribute, and extensions to make working with state management a bit simpler.

Cadru.AspNetCore.Mvc.TagHelpers

Provides additional ASP.NET Core TagHelpers.

Cadru.Build.Tasks

Provides additional MSBuild tasks and is used to support assembly-build-versioning.

Cadru.Caching

Provides a standard implementation for creating and using cache keys.

Cadru.Collections

Provides additional collection classes and extensions.

Cadru.Contracts

Provides static classes for representing program contracts as preconditions in a way that's compatible with System.Diagnostics.Contracts.

Cadru.Core

Provides common extensions and new APIs for the .NET Framework.

Cadru.Data

Provides a standard way to read Excel data and fixed width files.

Cadru.Data.Annotations

Provides common data annotation attributes.

Cadru.Data.Dapper

Provides a common database context and predicates for use with Dapper.

Cadru.Environment

Provides support for determining framework versions, IIS version, and feature detection.

Cadru.Extensions.FileProviders

Additional file providers and support for working with physical files and directories.

Cadru.Net.Http

Provides transient error detection strategies for adding retry logic into your HttpClient calls and a UrlBuilder to help simplify building complex URLs.

Cadru.Net.NetworkInformation

Provides access to network information and notification of network status changes.

Cadru.Polly

Provides support for working with Polly policies, including a strategy for resilient database queries.

Cadru.Postal

Provides classes for generating email using ASP.NET MVC Razor views.

Cadru.Scim

Support for creating System for Cross-domain Identity Management (SCIM) filters.

Cadru.UnitTest.Framework

Provides additional assert capabilities for MS Test.

The following packages have been retired. They are still available on NuGet, but shouldn't be used.

• Cadru.TransientFaultHandling - This package has been retired and should be replaced with *Cadru.Polly.
• Cadru.Net - This package is renamed to *Cadru.Net.Http
• Cadru.Core.Windows - This package is retired, and features migrated to Cadru.Environment, Cadru.IO, and Cadru.Net.NetworkInformation as appropriate.
• Cadru.IO - This package will eventually be retired and replaced with Cadru.Extensions.FileProviders.

What's next for Cadru?

The most significant update planned will be support for .NET 5 when it releases in November. Until then, there are a handful of known tasks still left. See the Cadru 5.0 milestone for more details. There are only a few issues in there right now, but I will be adding more over time.

Why another library?

Although Cadru was released as an open source framework in July 2013, some of the APIs it contains were created as early as 2003 and have been used in a variety of real world solutions. These are things that I kept having to rewrite in the apps I was building. Rather than continuing to rewrite them, I decided to encapsulate them in a library and make it broadly available. Although Cadru grew from app development, I have rewritten everything with a focus on being an API rather than a jumbled collection of utilities. That means everything is (hopefully) well documented, cleanly written, and easy to use.

Documentation

There are also a lot of unit tests that show how to use the APIs which can be a good starting place as well. (My goal is to as be as close to 100% code coverage as possible. Obviously, that will always be a work in progress.)

The long-term goal is to put the documentation online somewhere (probably as wiki pages hosted in the repository), but I don't have a time frame for when that will be complete. Until then, the source code is fully commented using XML documentation comments to provide IntelliSense support in Visual Studio.

Bugs and feature requests

Do you have a bug or a feature request? Please use the issue tracker and search for existing and closed issues. If your problem or request isn't addressed yet, go ahead and open a new issue.

Contributing

You can also get involved and fork the repository to submit your own pull requests. (More detailed contributor guidelines will be available soon.)

Versioning

For transparency and to maintain backward compatibility (as much as possible), Cadru uses the Semantic Versioning guidelines.

Creators

• Scott Dorman (@sdorman) - for the initial conception of the toolkit and core contributor.

Copyright and license

Code and documentation copyright 2001-2020 Scott Dorman. Code is licensed under the Microsoft Public License, use it as you wish (but please provide some credit somewhere in your app.) Documentation is released under Creative Commons.

cadru's Issues

Add a Partition method for enumerables

Add a method which partitions an enumerable into a collection of smaller enumerable collections all of a certain size. This is different from Slice, which returns a segment, in that

int[] numbers = { 0, 30, 20, 15, 90, 85, 40, 75 };
var partitions = numbers.Partition(3).ToArray();

Assert.AreEqual(3, partitions.Length);
CollectionAssert.AreEqual(new[] { 0, 30, 20 }, partitions[0].ToArray());
CollectionAssert.AreEqual(new[] { 15, 90, 85 }, partitions[1].ToArray());
CollectionAssert.AreEqual(new[] { 40, 75 }, partitions[2].ToArray());

Build failing

https://ci.appveyor.com/project/scottdorman/cadru/builds/31867495

HttpExtensions needs a CreateMessage method

A CreateMessage extension method on HttpClient needs to be created so that a MessageRequest can be created with query string parameters. This allows a MessageRequest, and more specifically the Uri of the request to be easily created with query string parameters to get around the limitations of Uri and the HttpClient.GetAsync method.

Add a Range(T) class.

Add a class which allows easy creation of a range of values. The range should be similar to a mathematical interval and should be able to include or exclude either endpoint (using standard interval notation), provide intersection and union operations, and be enumerable using a default enumeration function or a custom function.

Add DateTime and DateTimeOffset extension to format as relative string

Add a new extension method to DateTime and DateTimeOffset that returns a string representation of the date as a relative string.

For example, DateTime.Today.ToRelativeDateString() should return Today, 12:00 AM, DateTime.Today.AddDays(-1).ToRelativeDateString() should return Yesterday and so on.

Drop support for CsvReader

While CsvReader had a good run, it makes more sense to use a dedicated CSV parser that is up to date. We're dropping the CsvReader, and all it's associated classes, in favor of using something like CsvHelper or TinyCsvParser

Add DateTime and DateTimeOffset extension for Tomorrow and Yesterday

Even though it's simple to just use .AddDays(1) or .AddDays(-1), that isn't as easily recognizable in context as Tomorrow() or Yesterday().

Existing query string parameters should be preserved.

When adding query string parameters to a UriBuilder's QueryParameters dictionary, any existing parameters should be preserved.

The QueryStringParametersDictionary should gain an additional constructor which allows an existing query string to be passed in. The Query property should also be settable.

Build failing due to C# language version in AppVeyor

The Cadru.Data.Dapper project needs the <LangVersion>latest</LangVersion> element to be added.

The RelativeDateFormattingOptions enum should be renamed

This enum is not a Flags enum and should be renamed to RelativeDateFormatting. This is a breaking change.

Add a conditional Where filter for enumerables.

Add a version of the Where filter methods on an enumerable which take a bool which can control if the filter is applied or not.

Add a method to check if two dates are between two other dates.

Add an extension method for DateTime and DateTimeOffset which checks if the current date is between two other dates, optionally including the time as part of the check.

Add HasCustomAttribute extension

Add an extension method HasCustomAttribute to Cadru.Core\Extensions\TypeExtensions which simplifies testing a type to test if it contains a custom attribute.

ExcelDataReader throwing a NullReferenceException

When the ExcelDataReader tries to access a field that is a nullable DateTime field and the original value comes in as an empty string, the parsing fails and throws a NullReferenceException rather than returning a null value.

Rewrite Cadru.Postal

Rewrite Cadru.Postal to support the Razor SDK.

QueryStringParametersDictionary needs an AddRange method

What's the difference between enumerable.IsEmpty() and enumerable.Any() ?

Build failing on Cadru.AspNetCore

https://ci.appveyor.com/project/scottdorman/cadru/builds/31867403

Refactor Cadru.AspNetCore namespaces

The namespaces in Cadru.AspNetCore still refer to it as Cadru.AspNet and need to be refactored to more closely match the Microsoft.AspNetCore namespaces.

Fix NuGet Warning NU5125

The 'licenseUrl' element will be deprecated. Consider using the 'license' element instead.

Add an ExceptionAssert method to verify the inner exception.

The ExceptionAssert class should have a way to verify that the inner exception of a given exception is of a certain type.

Add methods to Enum(T) and EnumExtensions to get a description.

Enum should have methods to retrieve the value of an EnumDescription attribute applied to an Enum member. It should also have a method which returns a collection of descriptions.

Similarly, the GetDescription method in EnumExtensions should be updated to behave in a similar manner as the one in Enum.

Add a strongly typed Enum helper class.

The standard Enum class in the framework provides a strongly typed TryParse method but not a strongly typed Parse method. Add a strongly typed Enum<T> class which provides a strongly typed Parse method and pass-through methods for the other methods of Enum (and strongly type those that can be).

Add an extension to determine if a type implements an interface

Although types support a GetInterfaces() method and a GetInterface() method (which isn't available to PCLs), there isn't an easy way to simply determine if a type implements a given interface.

Remove "magic strings" from Cadru.Data.Dapper.

Improve SQL generation in Cadru.Data.Dapper predicates

Some of the Contracts.Requires methods still generate CA1062 warnings

The methods in Contracts.Requires should satisfy CA1062 (validate parameters of publicly accessible methods) but some of them don't have the necessary [ValidatedNotNull] attribute so it recognizes that the parameter being passed in is properly being validated.

Additional unit tests

Merge Cadru.IO into Cadru.Extensions.FileProviders

Combine remaining functionality in Cadru.IO into Cadru.Extensions.FileProviders and retire it.

Add boolean extensions for upper/lower case

Add a ReverseComparisonComparer(T) class.

Add a new ComparisonComparer(T) that reverses the comparison operation.

Expand literals used by TryParseAsBoolean

The BoleanExtensions.TryParseAsBoolean extension method currently only supports the following literals:

• False - false, f, no, n
• True - true, t, yes, y

The literals should be expanded to:

• False - false, f, no, n, 0, na, n/a
• True - true, t, yes, y, 1

Add additional overloads for LeftSubstring and RightSubstring

The LeftSubstring and RightSubstring methods should have additional overloads for extracting a substring indexed by char that allows the indexing character value to be excluded or included. The default should be that the character is included.

Should be able to call UrlBuilder with a URL that has existing query string parameters

When creating a new UrlBuilder using a URI string that already has a query string, the resulting URL no longer contains the query string.

For example, the following code will create a UrlBuilder whose Query property is empty. It should contain "?foo=bar".

var query = "http://example.com/?foo=bar";
var builder = new UrlBuilder(query);

Add addtional string extensions

The additional string extension methods need to be added:

• bool EndsWithAny(this string source, IEnumerable<string> values)
• bool EndsWithAny(this string source, IEnumerable<string> values, StringComparison comparisonType)
• bool EqualsAny(this string source, IEnumerable<string> values)
• bool EqualsAny(this string source, IEnumerable<string> values, StringComparison comparisonType)
• bool StartsWithAny(this string source, IEnumerable<string> values)
• bool StartsWithAny(this string source, IEnumerable<string> values, StringComparison comparisonType)

Cleanup code analysis warnings

Some unit tests are failing

Some of the Cadru.Core unit tests are failing due to a missing string resource.

Add support for an "IN" operator for predicates in Cadru.Data.Dapper.

Create an IEqualityComparer{T} from a lambda

Some LINQ expressions, like Distinct don't accept lambdas but rather expect an instance of an IEqualityComparer<T>. It would be nice to provide a class that can encapsulate creating an IEqualityComparer<T> that uses a key selector function that can be passed in line to those LINQ expressions which expect one.

Cadru.Data.Tests failing

The unit test in Cadru.Data.Tests is failing because it relies on a local file. Need to figure out how to do this through AppVeyor.

Add/Create a documentation site

Investigate using docfx to create static API documentation.

Add an easy way to retrieve localized strings.

Localization attributes, such as DisplayAttribute provide an easy mechanism to retrieve a localized value, but DisplayAttribute is sealed and the LocalizableString class is internal. Provide something similar to LocalizableString so other attributes can be made localization aware easily.

Add HttpMessage serializers

Useful for debugging and logging purposes, add Json serializers for HttpResponseMessage and HttpRequestMessage.

AppVeyor build number is hard-coded in version.props.

Add a Slice method for enumerables.

Add a method which returns a slice (or segment) of an enumerable based on a starting and ending index.

CountryCodes enum needs display attributes

The CountryCodes enum in Cadru.Core needs Display, EnumDescription, and UIHint attributes. This requires updating the projects to support .NET Standard 1.1 as the minimum.

AppVeyor builds failing

The AppVeyor builds are failing because it's not targeting C#6. The .sln file has # Visual Studio 14 header (not # Visual Studio 2013); otherwise AppVeyor will force MSBuild 12.0.

Support more fluent unit test assertions

Update Cadru.UnitTest.Framework to support using more fluent extension methods on the standard MS Test Assert (and related) classes. This will keep unit testing code more consistent, so you don't have to know when to use a Cadru specific class (like ConditionAssert) to write code like

var int i1 = 5;
var int i2 = 4;
ConditionAssert.Greater(i1, i2);

Instead, just include the Cadru.UnitTest.Framework namespace and you can write it as

var int i1 = 5;
var int i2 = 4;
Assert.That.Greater(i1, i2);

Add contracts methods for IsType and IsEnum

The Requires and Assumes classes should provide methods to check if a parameter is of a given Type and if it is an Enum.

The QueryStringParametersDictionary tests should not be included in code coverage analysis

The test class QueryStringParametersDictionaryTests should have the ExcludeCodeCoverage attribute applied.