Introduction

The DotNetExtras.Common library simplifies common general-purpose operations, such as retrieving error information from the immediate and inner exceptions, simple JSON serialization and deserialization, generation of tokenized strings from collections, deep object cloning and comparison, setting object properties and getting property values using compound (nested) property names, and more. For the detailed description of the library API, code samples, and usage scenarios, see the API documentation section.

Overview

The DotNetExtras.Common library groups the utility classes and extension methods under the following namespaces:

  • DotNetExtras.Common: Implements non-specific, most frequently used operations.

  • DotNetExtras.Common.Enums: Defines useful attributes and extension methods applicable to the enum types.

  • DotNetExtras.Common.Exceptions: Offers useful exception classes and extension methods.

  • DotNetExtras.Common.Extensions: Provides extension methods for most frequently used operations.

  • DotNetExtras.Common.Json: Handles JSON operations.

  • DotNetExtras.Common.RegularExpressions: Defines common regular expression patterns that can be used for validating email addresses, GUIDs, IDs, etc.

Here are some operations that you may find useful grouped by namespaces.

DotNetExtras.Common namespace

The NameOf class offers methods that extend the functionality of the built-in nameof operator. Use them to reference the full or partial name of a variable, class, or property using the original or forced camelCase notation. The PrimaryAssembly class allows you to easily access the properties of the primary application assembly, such as the assembly title, version, company, copyright, and more.

NameOf examples
using DotNetExtras.Common;
...
// Prints: Some.Type.Property.SubProperty
Console.WriteLine(NameOf.Full(nameof(Some.Type.Property.SubProperty)));

// Prints: some.type.property.subProperty
Console.WriteLine(NameOf.Full(nameof(Some.Type.Property.SubProperty), true));

// Prints: Property.SubProperty
Console.WriteLine(NameOf.Long(someObject.Property.SubProperty)));

// Prints: property.subProperty
Console.WriteLine(NameOf.Long(someObject.Property.SubProperty), true));

// Prints: SubProperty
Console.WriteLine(NameOf.Short(someObject.Property.SubProperty)));

// Prints: subProperty
Console.WriteLine(NameOf.Short(someObject.Property.SubProperty), true));
PrimaryAssembly examples
using DotNetExtras.Common;
...
// Assuming the following .csproj setting for the assembly:
// <PropertyGroup>
//   <AssemblyName>MyApp</AssemblyName>
//   <Version>1.0.8</Version>
//   <Title>$(AssemblyName)</Title>
//   <Copyright>© 2023 MyCompany</Copyright>
// </PropertyGroup>
// Print the version and the copyright message such as: MyApp v1.0.8 © 2023 MyCompany
Console.WriteLine($"{PrimaryAssembly.Title} v{PrimaryAssembly.Version} {PrimaryAssembly.Copyright}");
CodeContext examples
using DotNetExtras.Common;
...
public class SomeClass
{
  public void SomeMethod()
  {
    // Prints: Class: SomeClass, Method: SomeMethod
    Console.WriteLine($"Class: {CodeContext.GetClassName(this)}, Method: {CodeContext.GetMethodName(this)}");
  }
}
```

DotNetExtras.Common.Exceptions namespace

The exception extension methods allow you to retrieve the immediate and all inner exception messages in a neatly formatted string.

Exception examples
using DotNetExtras.Common.Exceptions;
...
// Print exception messages from the immediate and all inner exceptions.
try
{
  try
  {
    throw new Exception("Cannot do that");
  }
  catch (Exception ex)
  {
    throw new Exception("Failed to do this", ex);
  }
}
catch (Exception ex)
{
  // Prints: Failed to do this. Cannot do that.
  Console.WriteLine(ex.GetMessages());
}

DotNetExtras.Common.Extensions namespace

This namespace groups various extension methods applicable to different data types.

IEnumerable extensions examples
using DotNetExtras.Common.Extensions;
...
List<string> strings = ["one", "two", "tree"];
int[] numbers = [1, 2, 3];

// Prints: Strings: one, two, three.
Console.WriteLine("Strings: " + strings.ToCsv() + ".");

// Prints: Strings: one;two;three.
Console.WriteLine("Strings: " + strings.ToCsv(";") + ".");

// Prints: Numbers: 1|2|3.
Console.WriteLine("Numbers: " + numbers.ToCsv("|") + ".");
String extensions examples
using DotNetExtras.Common.Extensions;
...
// Prints: Raul Alvaro Lucia
Console.WriteLine("Raúl Álvaro Lucía".ToAscii());

// Prints: Gocke Ugur
Console.WriteLine("Gökçe Uğur".ToAscii());

// Prints: Sign [タクミ]
Console.WriteLine("Sign [タクミ]".ToAscii());

// Prints: Sign []
Console.WriteLine("Sign [タクミ]".ToAscii(true));

// Prints: Sign [???]
Console.WriteLine("Sign [タクミ]".ToAscii(true, '?'));
Object extensions examples
using DotNetExtras.Common.Extensions;
...
// Defines name parts.
public class Name
{
  public string GivenName { get; set; } = string.Empty;
  public string Surname { get; set; } = string.Empty;
}
...
// Defines user object.
public class User
{
  public Name Name { get; set; } = new Name();
}
...
// Demo code.
User user = new();

// Set the nested property value using a compound property name.
user.SetPropertyValue("Name.Surname", "Johnson");

// Get a nested property value using a compound property name.
string surname = user.GetPropertyValue<string>("Name.Surname");
...
user = new();
bool isEmpty;

isEmpty = user.IsEmpty(); // true
user.Name = new()
{
  GivenName = "Alice";
}
isEmpty = user.IsEmpty(); // false
...
User userA = new()
{
  Name = new()
  {
    GivenName = "Alice",
    Surname = "Johnson"
  }
};

User userB = new()
{
  Name = new()
  {
    GivenName = "Alice",
  }
};
...
// Compare two objects for partial equivalence.
userB.IsPartialEquivalentOf(userA)); // true
userA.IsPartialEquivalentOf(userB)); // false

// Compare two objects for equivalence.
userB.IsEquivalentOf(userA)); // false
userA.IsEquivalentOf(userB)); // false

// Fix the discrepancy.
userB.Name.Surname = "Johnson";

// Compare two objects for partial equivalence.
userB.IsPartialEquivalentOf(userA)); // true
userA.IsPartialEquivalentOf(userB)); // true

// Compare two objects for equivalence.
userB.IsEquivalentOf(userA)); // true
userA.IsEquivalentOf(userB)); // true

DotNetExtras.Common.Json namespace

The JsonExtensions class implements extension methods for converting objects to and from JSON strings using the System.Text.Json (STJ) serialization methods.

JSON serialization and deserialization examples
using DotNetExtras.Common.Json;
...
User user = new()
{
  Name = new()
  {
    GivenName = "Alice",
    Surname = "Johnson"
  }
};
...
string json = user.ToJson();

user = json.FromJson<User>();

DotNetExtras.Common.Enums namespace

This namespace groups enum-specific classes and operations.

Using enum metadata attributes and extension methods
using DotNetExtras.Common.Enums;
...
public enum Something

  [Description("Description 1")]
  [Abbreviation("ABBR1")]
  [ShortName("Short1")]
  Value1,

  [Description("Description 2")]
  [Abbreviation("ABBR2")]
  [ShortName("Short2")]
  Value2,
}
...
Something something = Something.Value1;

// Prints: Description 1
Console.WriteLine(something.ToDescription());

// Prints: ABBR1
Console.WriteLine(something.ToAbbreviation());

// Prints: Short1
Console.WriteLine(something.ToShortName());

More

For more examples of available functionality, see the unit test project.

See Also