Class HierarchyExtensions

Namespace

Cuemon.Extensions.Xml

Assembly

Cuemon.Extensions.Xml.dll

Extension methods for the IHierarchy<T> interface.

public static class HierarchyExtensions

Inheritance

object

HierarchyExtensions

Examples

HierarchyExtensions provides extension methods for inspecting XML serialization metadata on hierarchy nodes, including qualified entity names, enumerable detection, and XML ignore and ordering attributes. This example creates HierarchySerializer instances for CatalogDocument (with [XmlAttribute] on Id and a List<string> Tags property) and IgnoredDocument (with [XmlIgnore] on Hidden), then calls GetXmlQualifiedEntity, IsNodeEnumerable, HasXmlIgnoreAttribute, and OrderByXmlAttributes on individual nodes. Console output shows the qualified entity local name, whether the node is enumerable, whether it has [XmlIgnore], and the reordered element order.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Xml.Serialization;
using Cuemon.Extensions.Runtime.Serialization;
using Cuemon.Extensions.Xml;
using Cuemon.Xml.Serialization;

namespace DocExamples;

public static class HierarchyExtensionsExample
{
    public static void Demonstrate()
    {
        var documentNodes = new HierarchySerializer(new CatalogDocument()).Nodes.GetChildren().ToList();
        var idNode = documentNodes.Single(node => node.MemberReference?.Name == nameof(CatalogDocument.Id));
        var tagsNode = documentNodes.Single(node => node.MemberReference?.Name == nameof(CatalogDocument.Tags));

        var ignoredNodes = new HierarchySerializer(new IgnoredDocument()).Nodes.GetChildren().ToList();
        var hiddenNode = ignoredNodes.Single(node => node.MemberReference?.Name == nameof(IgnoredDocument.Hidden));
        var overrideEntity = new XmlQualifiedEntity("Override");

        Console.WriteLine(idNode.GetXmlQualifiedEntity().LocalName);
        Console.WriteLine(idNode.GetXmlQualifiedEntity(overrideEntity).LocalName);
        Console.WriteLine(tagsNode.IsNodeEnumerable());
        Console.WriteLine(hiddenNode.HasXmlIgnoreAttribute());

        var reordered = new[] { tagsNode, idNode }.OrderByXmlAttributes().ToList();
        Console.WriteLine(reordered[0].MemberReference?.Name);
    }

    private sealed class CatalogDocument
    {
        [XmlAttribute]
        public Guid Id { get; } = Guid.Empty;

        public List<string> Tags { get; } = new() { "xml", "docfx" };
    }

    private sealed class IgnoredDocument
    {
        [XmlIgnore]
        public string Hidden => "internal";

        public string Visible => "public";
    }
}

Methods

GetXmlQualifiedEntity(IHierarchy<object>, XmlQualifiedEntity)

Resolves an XmlQualifiedEntity from either the specified qualifiedEntity or from the IHierarchy{object}.

public static XmlQualifiedEntity GetXmlQualifiedEntity(this IHierarchy<object> hierarchy, XmlQualifiedEntity qualifiedEntity = null)

Parameters

hierarchy IHierarchy<object>

The IHierarchy{object} to extend.

qualifiedEntity XmlQualifiedEntity

The optional XmlQualifiedEntity that is part of the equation.

Returns

XmlQualifiedEntity

An XmlQualifiedEntity that is either from qualifiedEntity, embedded within hierarchy, XmlRootAttribute, XmlElementAttribute, XmlAttributeAttribute or resolved from either member name or member type (in that order).

Exceptions

ArgumentNullException

hierarchy cannot be null.

HasXmlIgnoreAttribute(IHierarchy<object>)

Determines whether the hierarchy implements XmlIgnoreAttribute.

public static bool HasXmlIgnoreAttribute(this IHierarchy<object> hierarchy)

Parameters

hierarchy IHierarchy<object>

The IHierarchy{object} to extend.

Returns

bool

true if the IHierarchy{object} implements XmlIgnoreAttribute; otherwise, false.

Exceptions

ArgumentNullException

hierarchy cannot be null.

IsNodeEnumerable(IHierarchy<object>)

Determines whether the hierarchy implements either IEnumerable or IEnumerable<T> and is not a string.

public static bool IsNodeEnumerable(this IHierarchy<object> hierarchy)

Parameters

hierarchy IHierarchy<object>

The IHierarchy{object} to extend.

Returns

bool

true if the IHierarchy{object} implements either IEnumerable or IEnumerable<T> and is not a string; otherwise, false.

Exceptions

ArgumentNullException

hierarchy cannot be null.

OrderByXmlAttributes<T>(IEnumerable<IHierarchy<T>>)

Orders a sequence of IHierarchy<T> from hierarchies by nodes having an XmlAttributeAttribute decoration.

public static IEnumerable<IHierarchy<T>> OrderByXmlAttributes<T>(this IEnumerable<IHierarchy<T>> hierarchies)

Parameters

hierarchies IEnumerable<IHierarchy<T>>

The IEnumerable{IHierarchy{object}} to extend.

Returns

IEnumerable<IHierarchy<T>>

A sequence of IHierarchy<T> that is sorted by nodes having an XmlAttributeAttribute decoration first.

Type Parameters

T

The type of the node represented in the hierarchical structure.

Exceptions

ArgumentNullException

hierarchies cannot be null.