Skip to content

Commit

Permalink
Docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Julian Verdurmen committed Jan 22, 2018
1 parent b6e6fdc commit f2a2106
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 12 deletions.
26 changes: 17 additions & 9 deletions src/NLog/IValueSerializer.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,35 +37,43 @@
namespace NLog
{
/// <summary>
/// Interface for serialization of object values into string format
/// Render a message template property to a string
///
/// If stringify is set, <see cref="StringifyObject"/> will be used
/// If serialize is set, <see cref="SerializeObject"/> will be used
/// Otherwise <see cref="FormatObject"/> will be used
/// </summary>
public interface IValueSerializer
{
/// <summary>
/// Serialization of an object into JSON format (or other destructure format)
/// Serialization of an object, e.g. JSON and append to <paramref name="builder"/>. Used if Serialize is set.
/// </summary>
/// <param name="value">The object to serialize to string.</param>
/// <param name="format">The format string for the object</param>
/// <param name="format">The format string for the value</param>
/// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
/// <param name="builder">Output destination.</param>
/// <returns>Serialize succeeded (true/false)</returns>
bool SerializeObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder);

/// <summary>
/// Convert object into into quoted string value
/// Convert object into into string value and append to <paramref name="builder"/>. Used if Stringify is set.
/// </summary>
/// <param name="value">The object to serialize to string.</param>
/// <param name="format">The format string for the object</param>
/// <param name="value">The object to convert to string.</param>
/// <param name="format">The format string for the value</param>
/// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
/// <param name="builder">Output destination.</param>
/// <returns>Stringify succeeded (true/false)</returns>
bool StringifyObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder);

/// <summary>
/// Format object into into string value
/// Format object into into string value and append to <paramref name="builder"/>. Used for rendering the template properties.
/// </summary>
/// <param name="value">The object to serialize to string.</param>
/// <param name="format">The format string for the object</param>
/// <remarks>
/// Stringify and Serialize isn't set
/// </remarks>
/// <remarks>This one is called if Stringify and Serialize isn't set for this property.</remarks>
/// <param name="value">The object to convert to string.</param>
/// <param name="format">The format string for the value</param>
/// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
/// <param name="builder">Output destination.</param>
/// <returns>Formating succeeded (true/false)</returns>
Expand Down
62 changes: 59 additions & 3 deletions src/NLog/MessageTemplates/ValueSerializer.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
using System;
using System.Collections;
using System.Text;
using NLog.Config;
using NLog.Internal;

namespace NLog.MessageTemplates
Expand Down Expand Up @@ -61,7 +62,14 @@ private ValueSerializer()

private readonly MruCache<Enum, string> _enumCache = new MruCache<Enum, string>(1500);

/// <inheritDoc/>
/// <summary>
/// Convert a object to a string without format and double quotes and append to <paramref name="builder"/>.
/// </summary>
/// <param name="value">The value to convert.</param>
/// <param name="format">Format, not used</param>
/// <param name="formatProvider">Format provider for the value.</param>
/// <param name="builder">Append to this</param>
/// <returns></returns>
public bool StringifyObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
{
builder.Append('"');
Expand All @@ -70,7 +78,14 @@ public bool StringifyObject(object value, string format, IFormatProvider formatP
return true;
}

/// <inheritDoc/>
/// <summary>
/// Format an object to a readable string, or if it's an object, serialize
/// </summary>
/// <param name="value">The value to convert</param>
/// <param name="format"></param>
/// <param name="formatProvider"></param>
/// <param name="builder"></param>
/// <returns></returns>
public bool FormatObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
{
if (SerializeSimpleObject(value, format, formatProvider, builder))
Expand All @@ -88,12 +103,27 @@ public bool FormatObject(object value, string format, IFormatProvider formatProv
return true;
}

/// <inheritDoc/>
/// <summary>
/// Serialize an object to JSON with the help of <see cref="ConfigurationItemFactory.JsonConverter"/>
/// </summary>
/// <param name="value"></param>
/// <param name="format"></param>
/// <param name="formatProvider"></param>
/// <param name="builder"></param>
/// <returns></returns>
public bool SerializeObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
{
return Config.ConfigurationItemFactory.Default.JsonConverter.SerializeObject(value, builder);
}

/// <summary>
/// Try serialising a scalar (string, int, NULL) or simple type (IFormattable)
/// </summary>
/// <param name="value"></param>
/// <param name="format"></param>
/// <param name="formatProvider"></param>
/// <param name="builder"></param>
/// <returns></returns>
private bool SerializeSimpleObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
{
// todo support all scalar types:
Expand Down Expand Up @@ -173,6 +203,12 @@ private bool SerializeSimpleObject(object value, string format, IFormatProvider
return false;
}

/// <summary>
/// Apend a int type (byte, int) as string
/// </summary>
/// <param name="sb"></param>
/// <param name="value"></param>
/// <param name="objTypeCode"></param>
private static void AppendIntegerAsString(StringBuilder sb, object value, TypeCode objTypeCode)
{
switch (objTypeCode)
Expand Down Expand Up @@ -245,6 +281,19 @@ private void AppendEnumAsString(StringBuilder sb, Enum value)
}
}

/// <summary>
/// Serialize Dictionary as JSON like structure, without { and }
/// </summary>
/// <example>
/// "FirstOrder"=true, "Previous login"=20-12-2017 14:55:32, "number of tries"=1
/// </example>
/// <param name="dictionary"></param>
/// <param name="format">formatstring of an item</param>
/// <param name="formatProvider"></param>
/// <param name="builder"></param>
/// <param name="objectsInPath"></param>
/// <param name="depth"></param>
/// <returns></returns>
private bool SerializeDictionaryObject(IDictionary dictionary, string format, IFormatProvider formatProvider, StringBuilder builder, SingleItemOptimizedHashSet<object> objectsInPath, int depth)
{
bool separator = false;
Expand Down Expand Up @@ -289,6 +338,13 @@ private bool SerializeCollectionObject(IEnumerable collection, string format, IF
return true;
}

/// <summary>
/// Convert a value to a string with format and append to <paramref name="builder"/>.
/// </summary>
/// <param name="value">The value to convert.</param>
/// <param name="format">Format sting for the value.</param>
/// <param name="formatProvider">Format provider for the value.</param>
/// <param name="builder">Append to this</param>
public static void FormatToString(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
{
var stringValue = value as string;
Expand Down

0 comments on commit f2a2106

Please sign in to comment.