Class StringDecoratorExtensions

Namespace

Cuemon.Xml

Assembly

Cuemon.Xml.dll

Extension methods for the string class hidden behind the IDecorator<T> interface.

public static class StringDecoratorExtensions

Inheritance

object

StringDecoratorExtensions

Examples

The following example demonstrates how to use the XML StringDecoratorExtensions to escape, unescape, and sanitize XML strings through the IDecorator interface.

using System;
using Cuemon;
using Cuemon.Xml;

namespace MyApp.Examples;

public class Example
{
    public void Run()
    {

        // Escape XML characters in a string
        var raw = "<hello & 'world' \"test\">";
        var escaped = Decorator.Enclose(raw).EscapeXml();
        Console.WriteLine($"Escaped:   {escaped}");
        // Output: &lt;hello &amp; &apos;world&apos; &quot;test&quot;&gt;

        // Unescape back to original
        var unescaped = Decorator.Enclose(escaped).UnescapeXml();
        Console.WriteLine($"Unescaped: {unescaped}");
        // Output: <hello & 'world' "test">

        // Sanitize a string to be a valid XML element name
        var invalidName = "123order-details!.xml";
        var sanitizedName = Decorator.Enclose(invalidName).SanitizeXmlElementName();
        Console.WriteLine($"Sanitized element name: {sanitizedName}");
        // Output: order-details.xml

        // Sanitize XML element text (remove control characters)
        var textWithControlChars = "Hello\x0001\x0002World";
        var cleanText = Decorator.Enclose(textWithControlChars).SanitizeXmlElementText();
        Console.WriteLine($"Clean text: {cleanText}");
        // Output: HelloWorld

        // Sanitize with CDATA section rules (removes ]]> sequences)
        var cdataText = "Some data with ]]> embedded";
        var safeCdata = Decorator.Enclose(cdataText).SanitizeXmlElementText(cdataSection: true);
        Console.WriteLine($"Safe CDATA: {safeCdata}");
        // Output: Some data with  embedded

}
}

Methods

EscapeXml(IDecorator<string>)

Escapes the given XML of the enclosed string of the specified decorator.

public static string EscapeXml(this IDecorator<string> decorator)

Parameters

decorator IDecorator<string>

The IDecorator<T> to extend.

Returns

string

An escaped equivalent of the enclosed string of the specified decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

SanitizeXmlElementName(IDecorator<string>)

Sanitizes the enclosed string of the specified decorator for any invalid characters.

public static string SanitizeXmlElementName(this IDecorator<string> decorator)

Parameters

decorator IDecorator<string>

The IDecorator<T> to extend.

Returns

string

A sanitized string of the enclosed string of the specified decorator.

Remarks

Sanitation rules are as follows:
1. Names can contain letters, numbers, and these 4 characters: _ | : | . | -
2. Names cannot start with a number or punctuation character
3. Names cannot contain spaces

Exceptions

ArgumentNullException

decorator cannot be null.

SanitizeXmlElementText(IDecorator<string>, bool)

Sanitizes the enclosed string of the specified decorator for any invalid characters.

public static string SanitizeXmlElementText(this IDecorator<string> decorator, bool cdataSection = false)

Parameters

decorator IDecorator<string>

The IDecorator<T> to extend.

cdataSection bool

if set to true supplemental CDATA-section rules is applied to the enclosed string of the specified decorator.

Returns

string

A sanitized string of the enclosed string of the specified decorator.

Remarks

Sanitation rules are as follows:
1. The enclosed string of the specified decorator cannot contain characters less or equal to a Unicode value of U+0019 (except U+0009, U+0010, U+0013)
2. The enclosed string of the specified decorator cannot contain the string "]]<" if cdataSection is true.

Exceptions

ArgumentNullException

decorator cannot be null.

UnescapeXml(IDecorator<string>)

Unescapes the given XML of the enclosed string of the specified decorator.

public static string UnescapeXml(this IDecorator<string> decorator)

Parameters

decorator IDecorator<string>

The IDecorator<T> to extend.

Returns

string

An unescaped equivalent of the enclosed string of the specified decorator.

Exceptions

ArgumentNullException

decorator cannot be null.

See Also

IDecorator<T>

Decorator<T>