Destructurama.Attributed 4.0.0

dotnet add package Destructurama.Attributed --version 4.0.0
NuGet\Install-Package Destructurama.Attributed -Version 4.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Destructurama.Attributed" Version="4.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Destructurama.Attributed --version 4.0.0
#r "nuget: Destructurama.Attributed, 4.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Destructurama.Attributed as a Cake Addin
#addin nuget:?package=Destructurama.Attributed&version=4.0.0

// Install Destructurama.Attributed as a Cake Tool
#tool nuget:?package=Destructurama.Attributed&version=4.0.0

Destructurama.Attributed

License

codecov Nuget Nuget

GitHub Release Date GitHub commits since latest release (by date) Size

GitHub contributors Activity Activity Activity

Run unit tests Publish preview to GitHub registry Publish release to Nuget registry CodeQL analysis

This package makes it possible to manipulate how objects are logged to Serilog using attributes.

Installation

Install from NuGet:

Install-Package Destructurama.Attributed

Usage

Modify logger configuration:

using Destructurama;
...
var log = new LoggerConfiguration()
  .Destructure.UsingAttributes()
  ...

1. Changing a property name

Apply the LogWithName attribute:

<a id='snippet-logwithname'></a>

public class PersonalData
{
    [LogWithName("FullName")]
    public string? Name { get; set; }
}

<sup><a href='/src/Destructurama.Attributed.Tests/LogWithNameAttributeTests.cs#L64-L70' title='Snippet source file'>snippet source</a> | <a href='#snippet-logwithname' title='Start of snippet'>anchor</a></sup>

2. Ignoring a property

Apply the NotLogged attribute:

<a id='snippet-logincommand'></a>

public class LoginCommand
{
    public string? Username { get; set; }

    [NotLogged]
    public string? Password { get; set; }
}

<sup><a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L29-L37' title='Snippet source file'>snippet source</a> | <a href='#snippet-logincommand' title='Start of snippet'>anchor</a></sup>

When the object is passed using {@...} syntax the attributes will be consulted.

<a id='snippet-logcommand'></a>

var command = new LoginCommand { Username = "logged", Password = "not logged" };
_log.Information("Logging in {@Command}", command);

<sup><a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L44-L47' title='Snippet source file'>snippet source</a> | <a href='#snippet-logcommand' title='Start of snippet'>anchor</a></sup>

3. Ignoring a property if it has default value

Apply the NotLoggedIfDefault attribute:

public class LoginCommand
{
  public string Username { get; set; }

  [NotLoggedIfDefault]
  public string Password { get; set; }

  [NotLoggedIfDefault]
  public DateTime TimeStamp { get; set; }
}

4. Ignoring a property if it has null value

Apply the NotLoggedIfNull attribute:

public class LoginCommand
{
  /// <summary>
  /// `null` value results in removed property
  /// </summary>
  [NotLoggedIfNull]
  public string Username { get; set; }

  /// <summary>
  /// Can be applied with [LogMasked] or [LogReplaced] attributes
  /// `null` value results in removed property
  /// "123456789" results in "***"
  /// </summary>
  [NotLoggedIfNull]
  [LogMasked]
  public string Password { get; set; }

  /// <summary>
  /// Attribute has no effect on non-reference and non-nullable types
  /// </summary>
  [NotLoggedIfNull]
  public int TimeStamp { get; set; }
}

Ignore null properties can be globally applied during logger configuration without need to apply attributes:

var log = new LoggerConfiguration()
  .Destructure.UsingAttributes(x => x.IgnoreNullProperties = true)
  ...

5. Treating types and properties as scalars

To prevent destructuring of a type or property at all, apply the LogAsScalar attribute.

6. Masking a string property

Apply the LogMasked attribute with various settings:

  • Text: If set, the property value will be set to this text.
  • ShowFirst: Shows the first x characters in the property value.
  • ShowLast: Shows the last x characters in the property value.
  • PreserveLength: If set, it will swap out each character with the default value. Note that this property will be ignored if Text has been set to custom value.

Note that masking also works for properties of type IEnumerable<string> or derived from it, for example, string[] or List<string>.

Examples

<a id='snippet-customizedmaskedlogs'></a>

public class CustomizedMaskedLogs
{
    /// <summary>
    /// 123456789 results in "***"
    /// </summary>
    [LogMasked]
    public string? DefaultMasked { get; set; }

    /// <summary>
    /// [123456789,123456789,123456789] results in [***,***,***]
    /// </summary>
    [LogMasked]
    public string[]? DefaultMaskedArray { get; set; }

    /// <summary>
    /// 123456789 results in "*********"
    /// </summary>
    [LogMasked(PreserveLength = true)]
    public string? DefaultMaskedPreserved { get; set; }

    /// <summary>
    /// "" results in "***"
    /// </summary>
    [LogMasked]
    public string? DefaultMaskedNotPreservedOnEmptyString { get; set; }

    /// <summary>
    ///  123456789 results in "#"
    /// </summary>
    [LogMasked(Text = "_REMOVED_")]
    public string? CustomMasked { get; set; }

    /// <summary>
    ///  123456789 results in "#"
    /// </summary>
    [LogMasked(Text = "")]
    public string? CustomMaskedWithEmptyString { get; set; }

    /// <summary>
    ///  123456789 results in "#########"
    /// </summary>
    [LogMasked(Text = "#", PreserveLength = true)]
    public string? CustomMaskedPreservedLength { get; set; }

    /// <summary>
    ///  123456789 results in "123******"
    /// </summary>
    [LogMasked(ShowFirst = 3)]
    public string? ShowFirstThreeThenDefaultMasked { get; set; }

    /// <summary>
    /// 123456789 results in "123******"
    /// </summary>
    [LogMasked(ShowFirst = 3, PreserveLength = true)]
    public string? ShowFirstThreeThenDefaultMaskedPreservedLength { get; set; }

    /// <summary>
    /// 123456789 results in "***789"
    /// </summary>
    [LogMasked(ShowLast = 3)]
    public string? ShowLastThreeThenDefaultMasked { get; set; }

    /// <summary>
    /// 123456789 results in "******789"
    /// </summary>
    [LogMasked(ShowLast = 3, PreserveLength = true)]
    public string? ShowLastThreeThenDefaultMaskedPreservedLength { get; set; }

    /// <summary>
    ///  123456789 results in "123REMOVED"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3)]
    public string? ShowFirstThreeThenCustomMask { get; set; }

    /// <summary>
    ///  123456789 results in "123_REMOVED_"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, PreserveLength = true)]
    public string? ShowFirstThreeThenCustomMaskPreservedLengthIgnored { get; set; }

    /// <summary>
    ///  123456789 results in "_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowLast = 3)]
    public string? ShowLastThreeThenCustomMask { get; set; }

    /// <summary>
    ///  123456789 results in "_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowLast = 3, PreserveLength = true)]
    public string? ShowLastThreeThenCustomMaskPreservedLengthIgnored { get; set; }

    /// <summary>
    /// 123456789 results in "123***789"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3)]
    public string? ShowFirstAndLastThreeAndDefaultMaskInTheMiddle { get; set; }

    /// <summary>
    /// 123456789 results in "123456789", no mask applied
    /// </summary>
    [LogMasked(ShowFirst = -1, ShowLast = -1)]
    public string? ShowFirstAndLastInvalidValues { get; set; }

    /// <summary>
    /// 123456789 results in "123***789"
    /// </summary>
    [LogMasked(ShowFirst = 3, ShowLast = 3, PreserveLength = true)]
    public string? ShowFirstAndLastThreeAndDefaultMaskInTheMiddlePreservedLength { get; set; }

    /// <summary>
    ///  123456789 results in "123_REMOVED_789"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, ShowLast = 3)]
    public string? ShowFirstAndLastThreeAndCustomMaskInTheMiddle { get; set; }

    /// <summary>
    ///  123456789 results in "123_REMOVED_789". PreserveLength is ignored"
    /// </summary>
    [LogMasked(Text = "_REMOVED_", ShowFirst = 3, ShowLast = 3, PreserveLength = true)]
    public string? ShowFirstAndLastThreeAndCustomMaskInTheMiddlePreservedLengthIgnored { get; set; }
}

<sup><a href='/src/Destructurama.Attributed.Tests/MaskedAttributeTests.cs#L8-L133' title='Snippet source file'>snippet source</a> | <a href='#snippet-customizedmaskedlogs' title='Start of snippet'>anchor</a></sup>

7. Masking a string property with regular expressions

Apply the LogReplaced attribute on a string to apply a RegEx replacement during Logging.

This is applicable in scenarios when a string contains both Sensitive and Non-Sensitive information. An example of this could be a string such as "Sensitive|NonSensitive". Then apply the attribute like the following snippet:

[LogReplaced(@"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)", "***|$2")]
public property Information { get; set; }

// Will log: "***|NonSensitive"

LogReplaced attribute is available with the following constructor:

LogReplaced(string pattern, string replacement)

Constructor arguments:

  • pattern: The pattern that should be applied on value.
  • replacement: The string that will be applied by RegEx.

Available properties:

  • Options: The RegexOptions that will be applied. Defaults to RegexOptions.None.
  • Timeout: A time-out interval to evaluate regular expression. Defaults to Regex.InfiniteMatchTimeout.

Examples

<a id='snippet-withregex'></a>

public class WithRegex
{
    private const string REGEX_WITH_VERTICAL_BARS = @"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)";

    /// <summary>
    /// 123|456|789 results in "***|456|789"
    /// </summary>
    [LogReplaced(REGEX_WITH_VERTICAL_BARS, "***|$2|$3")]
    public string? RegexReplaceFirst { get; set; }

    /// <summary>
    /// 123|456|789 results in "123|***|789"
    /// </summary>
    [LogReplaced(REGEX_WITH_VERTICAL_BARS, "$1|***|$3")]
    public string? RegexReplaceSecond { get; set; }
}

<sup><a href='/src/Destructurama.Attributed.Tests/Snippets.cs#L6-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-withregex' title='Start of snippet'>anchor</a></sup>

Benchmarks

The results are available here.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

NuGet packages (55)

Showing the top 5 NuGet packages that depend on Destructurama.Attributed:

Package Downloads
CG.SharedEntities

Package Description

MyJetWallet.Sdk.Service

Package Description

Serilog.Extras.Attributed The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Obsolete. Please install Destructurama.Attributed.

Libplanet.Net

A peer-to-peer networking layer based on Libplanet.

MarketingBox.Affiliate.Service.Client

Package Description

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on Destructurama.Attributed:

Repository Stars
ErsatzTV/ErsatzTV
Stream custom live channels using your own media
planetarium/libplanet
Blockchain in C#/.NET for on-chain, decentralized gaming
Texnomic/SecureDNS
Secure, Modern, Fully-Featured, All-In-One Cross-Architecture & Cross-Platform DNS Server Using .NET 7.0
GitTools/GitReleaseManager
Tool for creating and exporting releases for software applications hosted on GitHub
Version Downloads Last updated
4.0.0 475 2/27/2024
3.2.0 63,475 1/24/2024
3.1.0 1,412,995 6/22/2023
3.1.0-dev-00177 125 6/23/2023
3.1.0-dev-00175 89 6/22/2023
3.1.0-dev-00173 105 6/22/2023
3.1.0-dev-00172 109 6/22/2023
3.0.0 6,838,931 9/27/2021
3.0.0-dev-00139 211 11/2/2021
3.0.0-dev-00138 307 10/30/2021
3.0.0-dev-00131 219 9/27/2021
3.0.0-dev-00129 309 9/15/2021
3.0.0-dev-00128 251 8/26/2021
3.0.0-dev-00127 208 8/25/2021
3.0.0-dev-00060 46,814 3/24/2020
3.0.0-dev-00048 60,014 11/15/2019
2.0.1-dev-00037 155,874 5/12/2018
2.0.0 8,386,000 5/12/2018
2.0.0-dev-00033 992 4/15/2018
2.0.0-dev-00029 725 4/12/2018
2.0.0-dev-00028 804 4/12/2018
2.0.0-dev-00026 859 4/12/2018
1.2.0 112,490 2/9/2018
1.2.0-dev-00021 936 2/9/2018
1.2.0-dev-00019 795 2/9/2018
1.2.0-dev-00016 1,025 2/7/2018
1.2.0-dev-00013 819 2/2/2018
1.2.0-dev-00011 12,822 12/8/2017
1.1.0 339,242 5/24/2017
1.1.0-dev-00010 766 11/12/2017
1.1.0-dev-00007 742 7/29/2017
1.1.0-dev-00004 827 6/25/2017
1.1.0-dev-00001 764 5/24/2017
1.0.7 34,754 8/29/2016
1.0.6 1,201 8/18/2016
1.0.5 47,941 6/17/2015
1.0.4 5,853 4/1/2015
1.0.3 1,423 3/29/2015
1.0.2 132,292 3/29/2015