Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme with badges + format #77

Merged
merged 1 commit into from
Jan 21, 2024
Merged

Update readme with badges + format #77

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 55 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,37 @@
# <img src="/assets/icon.png" height="30px"> Destructurama.Attributed
# Destructurama.Attributed

[![Build status](https://ci.appveyor.com/api/projects/status/1tutmofqjb9wq627/branch/master?svg=true)](https://ci.appveyor.com/project/Destructurama/attributed)
[![NuGet Status](https://img.shields.io/nuget/v/Destructurama.Attributed.svg)](https://www.nuget.org/packages/Destructurama.Attributed/)
![License](https://img.shields.io/github/license/destructurama/attributed)

This package makes it possible to manipulate how objects are logged to [Serilog](https://serilog.net) using attributes.
[![codecov](https://codecov.io/gh/destructurama/attributed/branch/master/graph/badge.svg?token=0ZRHIUEQM4)](https://codecov.io/gh/destructurama/attributed)
[![Nuget](https://img.shields.io/nuget/dt/Destructurama.Attributed)](https://www.nuget.org/packages/Destructurama.Attributed)
[![Nuget](https://img.shields.io/nuget/v/Destructurama.Attributed)](https://www.nuget.org/packages/Destructurama.Attributed)

[![GitHub Release Date](https://img.shields.io/github/release-date/destructurama/attributed?label=released)](https://github.com/destructurama/attributed/releases)
[![GitHub commits since latest release (by date)](https://img.shields.io/github/commits-since/destructurama/attributed/latest?label=new+commits)](https://github.com/destructurama/attributed/commits/master)
![Size](https://img.shields.io/github/repo-size/destructurama/attributed)

[![GitHub contributors](https://img.shields.io/github/contributors/destructurama/attributed)](https://github.com/destructurama/attributed/graphs/contributors)
![Activity](https://img.shields.io/github/commit-activity/w/destructurama/attributed)
![Activity](https://img.shields.io/github/commit-activity/m/destructurama/attributed)
![Activity](https://img.shields.io/github/commit-activity/y/destructurama/attributed)

[![Run unit tests](https://github.com/destructurama/attributed/actions/workflows/test.yml/badge.svg)](https://github.com/destructurama/attributed/actions/workflows/test.yml)
[![Publish preview to GitHub registry](https://github.com/destructurama/attributed/actions/workflows/publish-preview.yml/badge.svg)](https://github.com/destructurama/attributed/actions/workflows/publish-preview.yml)
[![Publish release to Nuget registry](https://github.com/destructurama/attributed/actions/workflows/publish-release.yml/badge.svg)](https://github.com/destructurama/attributed/actions/workflows/publish-release.yml)
[![CodeQL analysis](https://github.com/destructurama/attributed/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/destructurama/attributed/actions/workflows/codeql-analysis.yml)

This package makes it possible to manipulate how objects are logged to [Serilog](https://serilog.net) using attributes.

## Enabling the module:
# Installation

Install from NuGet:

```powershell
Install-Package Destructurama.Attributed
```

# Usage

Modify logger configuration:

```csharp
Expand All @@ -24,14 +42,13 @@ var log = new LoggerConfiguration()
...
```


#### Changing a property name
## 1. Changing a property name

Apply the `LogWithName` attribute:

<!-- snippet: LogWithName -->
<a id='snippet-logwithname'></a>
```cs
```csharp
using Destructurama.Attributed;
...
public class PersonalData
Expand All @@ -43,14 +60,13 @@ public class PersonalData
<sup><a href='/test/Destructurama.Attributed.Tests/LogWithNameAttributedTests.cs#L37-L43' title='Snippet source file'>snippet source</a> | <a href='#snippet-logwithname' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->


## Ignoring a property
## 2. Ignoring a property

Apply the `NotLogged` attribute:

<!-- snippet: LoginCommand -->
<a id='snippet-logincommand'></a>
```cs
```csharp
using Destructurama.Attributed;
...
public class LoginCommand
Expand All @@ -68,14 +84,14 @@ When the object is passed using `{@...}` syntax the attributes will be consulted

<!-- snippet: LogCommand -->
<a id='snippet-logcommand'></a>
```cs
```csharp
var command = new LoginCommand { Username = "logged", Password = "not logged" };
log.Information("Logging in {@Command}", command);
```
<sup><a href='/test/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>
<!-- endSnippet -->

#### Ignoring a property if it has the default value
## 3. Ignoring a property if it has default value

Apply the `NotLoggedIfDefault` attribute:

Expand All @@ -92,65 +108,63 @@ public class LoginCommand
}
```

#### Ignoring a property if it has the null value
## 4. Ignoring a property if it has null value

Apply the `NotLoggedIfNull` attribute:

```csharp
public class LoginCommand
{
/// <summary>
/// `null` value results in removed property
/// `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 "***"
/// Can be applied with [LogMasked] or [LogReplaced] attributes
/// `null` value results in removed property
/// "123456789" results in "***"
/// </summary>
[NotLoggedIfNull] [LogMasked]
[NotLoggedIfNull]
[LogMasked]
public string Password { get; set; }

/// <summary>
/// Attribute has no effect on non-reference and non-nullable types
/// 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 initialization without need to apply attributes:
Ignore null properties can be globally applied during logger configuration without need to apply attributes:
```csharp
var log = new LoggerConfiguration()
.Destructure.UsingAttributes(x => x.IgnoreNullProperties = true)
...
```

## 5. Treating types and properties as scalars

## Treating types and properties as scalars

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


## Masking a string property
## 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.
- **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

<!-- snippet: CustomizedMaskedLogs -->
<a id='snippet-customizedmaskedlogs'></a>
```cs
```csharp
using Destructurama.Attributed;
...
public class CustomizedMaskedLogs
Expand Down Expand Up @@ -273,12 +287,12 @@ public class CustomizedMaskedLogs
<sup><a href='/test/Destructurama.Attributed.Tests/MaskedAttributeTests.cs#L10-L129' title='Snippet source file'>snippet source</a> | <a href='#snippet-customizedmaskedlogs' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->


## Masking a string property with regular expressions
## 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 which 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:
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:

```csharp
[LogReplaced(@"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)", "***|$2")]
Expand All @@ -298,29 +312,28 @@ __Constructor arguments__:
- **replacement:** The string that will be applied by RegEx.

__Available properties__:
- **Options:** The [RegexOptions](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions.regexoptions?view=netcore-3.1) that will be applied. Defaults to __RegexOptions.None__
- **Timeout:** A time-out interval to evaluate regular expression. Defaults to __Regex.InfiniteMatchTimeout__

- **Options:** The [RegexOptions](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions.regexoptions?view=netcore-3.1) that will be applied. Defaults to __RegexOptions.None__.
- **Timeout:** A time-out interval to evaluate regular expression. Defaults to __Regex.InfiniteMatchTimeout__.

### Examples

<!-- snippet: WithRegex -->
<a id='snippet-withregex'></a>
```cs
```csharp
public class WithRegex
{
const string RegexWithVerticalBars = @"([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)\|([a-zA-Z0-9]+)";
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(RegexWithVerticalBars, "***|$2|$3")]
[LogReplaced(REGEX_WITH_VERTICAL_BARS, "***|$2|$3")]
public string? RegexReplaceFirst { get; set; }

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