Sunday, October 6, 2024

OData! my Data!

Summary: How to process OData filters in C#.

I spent a few days at work trying to figure out how to validate OData filters for the project I'm working on. So, I'd like to share a piece of code that performs basic OData parsing. But before I get to code, let me explain what I'm doing here and why.

We're using ASP.NET Core (.NET 8) to build REST APIs which talk to extrnal REST APIs and we need a consistent way to define the search queries (or search filters) used by the HTTP GET operations. There are different ways to define search queries. For example, SCIM filtering spec looks simple and robust, but after spending the last decade dealing with SCIM implementations, I do not want to have anything to do with SCIM anymore.

The most reasonable option (other than building one from scratch) would be using OData. OData comes with a lot of goodies, but for our use case, we only needed to figure out how to parse and validate OData filters. I thought in .NET Core, handling OData queries would be simple, but unfortunately, the good people at Microsoft must have assumed that everyone using OData in their custom controllers would rely on entity frameworks, so they made it easy for the apps that integrate OData with their entity data models. Which is not what we do. In our case, we take a search query, validate it, and pass to an external API. What this API does with it, we do not care, but we want to be good citizens and not hand it garbage (and in case we get garbage from the clients, we want to send them meaningful errors explaining why their queries are garbage). To do this, we need to take an OData filter expression from a query string and make sure that it is valid. Should be simple, right?

There are many articles explaining how to integrate OData into the REST API controllers, but the only two posts I found useful for our use case were:

By trial and error, I built a simple program that validates and parses a string holding an OData filter. This program is not perfect (it does not handle all possible functions, operators, and complex scenarios), but for us, it is more than enough. I will make it more robust and implement the logic as a library at some point, but if you need a more or less simple example, showing how to validate and parse a not very complex OData filter, see code below (read the comments that explain the requirements and dependencies).

/*
This .NET Core console app was built and tested with the following Nuget packages {versions}:

- Microsoft.AspNetCore.OData {9.0.0}
- Microsoft.Extensions.DependencyInjection.Abstractions {8.0.1}
- Microsoft.OData.Core {8.0.1}

To install the latest versions of the packages, run from Package Manager Console:

Install-Package Microsoft.Extensions.DependencyInjection.Abstractions
Install-Package Microsoft.OData.Core
Install-Package Microsoft.AspNetCore.OData

SUMMARY:

This program illustrates how to validate and parse basic OData filters in the given text strings.
The code may not be comprehensive and it does not cover advanced OData use cases,
but it shows how to handle typical filter conditions that utilize common operations
and functions ('not', 'eq', 'ne', 'gt', 'ge', 'lt', 'le', 'startsWith', 'endsWith',
'contains', 'in') and grouped using logical operators ('and', 'or').

The filter properties will be mapped to properties of the filter object properties. The filter
objects (there is more than one) identify how OData filter attributes can be mapped to a real
entity that may come from an external resource, such as a web service, database, report, etc.
*/

// The following namespace holds the classes used in the OData filter.
#pragma warning disable IDE0130 // Namespace does not match folder structure
namespace TestOData1;
#pragma warning restore IDE0130 // Namespace does not match folder structure

using Microsoft.OData.Edm;
using Microsoft.OData.ModelBuilder;
using Microsoft.OData.UriParser;
using System.Linq;

/// <summary>
/// Main program.
/// </summary>
internal class Program
{
    #region Properties
    // Use the same separator for complex (nested) types as the OData filters.
    private static readonly string _separator = "/";

    // Number of indent characters for the binary tree output.
    private static readonly int _indentLength = 2;

    // Set this value to true to print object names of the tree nodes.
    private static readonly bool _printNode = false;
    #endregion

    #region Filter examples
    // Here are some basic filter we may want to test.

    // By default, property names are case-insensitive, but we'll make them case-insensitive.
    private static readonly string[] _filters =
    [
        "not(enabled)",
        "not(true)",
        "email eq null",
        "email ne null",
        "email eq 'john@mail.com'",
        "email ne 'john@mail.com'",
        "email eq displayName",
        "email ne displayName",
        "contains(email, '@')",
        "not contains(email, '@')",
        "contains(email, displayName)",
        "not contains(email, displayName)",
        "startsWith(email, 'john')",
        "not startsWith(email, 'john')",
        "endsWith(email, '@mail.com')",
        "not endsWith(email, '@mail.com')",
        "email in ('john@mail.com', 'mary@mail.com')",
        "not (email in ('john@mail.com', 'mary@mail.com'))",
        "id eq 0",
        "id gt 0",
        "id lt 2000",
        "id ge 1",
        "id le 2000",
        "name eq null",
        "name ne null",
        "name/givenName eq null",
        "sponsor/name/givenName eq null",
        "name/surname ne sponsor/name/surname",
        "name/givenName in ('John', 'Mary')",
        "name/givenName ne name/nickName",
        "startsWith(displayName, 'J')",
        "type eq 'Employee'",
        "type eq 'Guest' and name/Surname eq 'Johnson'",
        "type eq 'Contractor' and not(endsWith(email, '@mail.com'))",
        "enabled eq false and type in ('Employee', 'Contractor') ",
        "(enabled eq true and type eq 'Employee') or (enabled eq false and (type eq 'Guest' or endsWith(email, '@mail.com')))",
        "phoneNumbers/any(p: p eq '123-456-6789')",
        "socialLogins/any(s: s/name eq 'Facebook')",
        "socialLogins/any(s: s/name eq 'Facebook' or endsWith(s/url, 'google.com'))",
        "sponsor/phoneNumbers/any(p: p eq '123-456-6789')",
        "sponsor/socialLogins/any(s: s/name eq 'Facebook')"
    ];
    #endregion

    #region Main method
    private static void Main()
    {
        // The builder is responsible for mapping OData filter conditions to the object properties.
        ODataConventionModelBuilder builder = new();

        // UserFilter defines the properties which can be used in our filter (this class is defined below).
        // The UserFilter class properties also can be based on other complex types, but they will be
        // included implicitly, so no need to reference them.
        builder.AddEntityType(typeof(User));

        // EDM (Entity Data Model) encapsulates classes that will be used in the OData filters.
        IEdmModel model = builder.GetEdmModel();

        // Let's print all classes that our EDM schema recognizes.
        Console.WriteLine("ODATA SCHEMA ELEMENTS:");
        foreach (IEdmSchemaElement element in model.SchemaElements)
        {
            Console.WriteLine($"- {element.FullName()}: {element.SchemaElementKind}");
        }

        // If you define the EDM classes not under an explicitly defined namespace,
        // make sure you add 'Default.' to the full name because 'Default' would be the implicit
        // namespace created by the compiler; if you do not, these types will not be found.
        // string qualifiedName = "Default." + typeof(GroupFilter).FullName;
        string qualifiedName = typeof(User).FullName ?? "";

        // Now, lets use our filter class as the EDM type, so it can be used for OData filter handling.
        IEdmType type = model.FindDeclaredType(qualifiedName);
        if (type == null)
        {
            Console.WriteLine($"Type '{qualifiedName}' is not found in the OData schema model.");
            return;
        }

        foreach (string filter in _filters)
        {
            Console.WriteLine();
            Console.WriteLine(new string('-', 72));
            Console.WriteLine("EXPRESSION: " + filter);
            Console.WriteLine(new string('-', 72));

            // This dictionary can include other OData parameters,
            // such as "$top", "$skip", "$count", "$select", "$orderby", "$search", etc.
            // but we are only interested in the filter.
            Dictionary<string, string> options = new()
            {
                {"$filter", filter}
            };

            try
            {
                ODataQueryOptionParser parser = new(model, type, null, options)
                {
                    // By default, property names are case-sensitive,
                    // so we need to explicitly specify them to be case-insensitive.
                    Resolver = new ODataUriResolver() { EnableCaseInsensitive = true }
                };

                FilterClause clause = parser.ParseFilter();

                if (clause == null)
                {
                    Console.WriteLine("FilterClause is null.");
                }
                else
                {
                    ProcessNode(clause.Expression, 0, null);
                }
            }
            catch (Exception ex)
            {
                while (ex != null)
                {
                    Console.WriteLine(ex.Message + " ");

                    if (ex.InnerException != null)
                    {
                        ex = ex.InnerException;
                    }
                    else
                    {
                        break;
                    }
                }
                Console.WriteLine();
            }
        }
    }
    #endregion

    #region Node processing methods
    /// <summary>
    /// Process a node of the OData filter.
    /// </summary>
    /// <param name="node">
    /// Node to process.
    /// </param>
    /// <param name="level">
    /// Indent level of this node.
    /// </param>
    /// <param name="parentName">
    /// Name of the parent property of the nodes under the 'Any' operator.
    /// </param>
    /// <remarks>
    /// OData filter is basically a binary tree, so we'll process it as such.
    /// </remarks>
    private static void ProcessNode
    (
        SingleValueNode node, 
        int level, 
        string? parentName
    )
    {
        // The filter tree consists of nodes all of which are directly derived from SingleValueNode.
        if (node == null)
        {
            // Shouldn't happen, but just in case.
            return;
        }
        else if (node is BinaryOperatorNode binaryOperatorNode)
        {
            ProcessBinaryOperatorNode(binaryOperatorNode, level, parentName);
        }
        else if (node is SingleComplexNode singleComplexNode)
        {
            ProcessSingleComplexNode(singleComplexNode, level, parentName);
        }
        else if (node is SingleValueFunctionCallNode singleValueFunctionCallNode)
        {
            ProcessSingleValueFunctionCallNode(singleValueFunctionCallNode, level, parentName);
        }
        else if (node is SingleValueOpenPropertyAccessNode singleValueOpenPropertyAccessNode)
        {
            ProcessSingleValueOpenPropertyAccessNode(singleValueOpenPropertyAccessNode, level, parentName);
        }
        else if (node is SingleValuePropertyAccessNode singleValuePropertyAccessNode)
        {
            ProcessSingleValuePropertyAccessNode(singleValuePropertyAccessNode, level, parentName);
        }
        else if (node is InNode inNode)
        {
            ProcessInNode(inNode, level, parentName);
        }
        else if (node is ConstantNode constantNode)
        {
            ProcessConstantNode(constantNode, level);
        }
        else if (node is ConvertNode convertNode)
        {
            ProcessConvertNode(convertNode, level, parentName);
        }
        else if (node is UnaryOperatorNode unaryOperatorNode)
        {
            ProcessUnaryOperatorNode(unaryOperatorNode, level, parentName);
        }
        else if (node is AnyNode anyNode)
        {
            ProcessAnyNode(anyNode, level);
        }
        else if (node is NonResourceRangeVariableReferenceNode nonResourceRangeVariableReferenceNode)
        {
            ProcessNonResourceRangeVariableReferenceNode(nonResourceRangeVariableReferenceNode, level, parentName);
        }
        else
        {
            // There may be more node types that need to be handled explicitly,
            // but for now, let's handle all unexpected nodes as a simple node.
            ProcessSingleValueNode(node, level);
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles all kinds of nodes, 
    /// e.g. holding elements that must be converted to a certain data type, such as enum,
    /// operator nodes, value nodes, etc.
    /// </summary>
    private static void ProcessConvertNode
    (
        ConvertNode node, 
        int level, 
        string? parentName
    )
    {
        ProcessNode(node.Source, level, parentName);
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="params"/>
    /// <summary>
    /// Handles the simplest node holding a single element.
    /// </summary>
    /// <remarks>
    /// This method will also handle any nodes that are not handled by the node type-specific methods.
    /// </remarks>
    private static void ProcessSingleValueNode
    (
        SingleValueNode node, 
        int level
    )
    {
        if (_printNode)
        {
            WriteLine(level, FormatNode(node.Kind));
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a node holding a simple constant value, such as a string, a number, or a boolean.
    /// </summary>
    private static void ProcessConstantNode
    (
        ConstantNode node, 
        int level
    )
    {
        WriteLine(level, FormatValue(node.Value ?? "(null)"));
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles values in the collection object (such as a collection inside of the 'in' clause).
    /// </summary>
    private static void ProcessCollectionConstantNode
    (
        CollectionConstantNode node, 
        int level, 
        string? parentName
    )
    {
        foreach(var value in node.Collection) 
        {
            ProcessNode(value, level, parentName);
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a node holding a complex (i.e. nested) object property.
    /// </summary>
    private static void ProcessSingleComplexNode
    (
        SingleComplexNode node, 
        int level,
        string? parentName
    )
    {
        WriteLine(level, FormatProperty(node.Property.Name));
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a node holding a simple object property.
    /// </summary>
    private static void ProcessSingleValuePropertyAccessNode
    (
        SingleValuePropertyAccessNode node, 
        int level,
        string? parentName
    )
    {
        WriteLine(level, FormatProperty(GetPropertyName(node, parentName)));
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Not sure what node this is, but based on the name it should be similar to SingleValuePropertyAccessNode.
    /// </summary>
    private static void ProcessSingleValueOpenPropertyAccessNode
    (
        SingleValueOpenPropertyAccessNode node, 
        int level,
        string? parentName
    )
    {
        WriteLine(level, FormatProperty(GetPropertyName(node, parentName)));
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="params"/>
    /// <summary>
    /// Handles the nodes holding dynamic value such as aliases use in the 'Any' operator.
    /// </summary>
    private static void ProcessNonResourceRangeVariableReferenceNode
    (
        NonResourceRangeVariableReferenceNode node, 
        int level,
        string? parentName
    )
    {
        // In filter 'phoneNumbers/any(p: p eq '123-456-6789')', since 'p' is just an alias,
        // we want to print 'phoneNumbers' because it is the name of the collection to
        // to which the filter is applied.

        // This node should be under a parent's 'Any' operation.
        if (!string.IsNullOrEmpty(parentName))
        {
            WriteLine(level, FormatProperty(parentName));
        }
        // But just in case, we can just print the alias (e.g. 'p' in our example).
        else
        {
            WriteLine(level, FormatProperty(node.RangeVariable.Name));
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a unary operation node, such as 'not'.
    /// </summary>
    private static void ProcessUnaryOperatorNode
    (
        UnaryOperatorNode node, 
        int level,
        string? parentName
    )
    {
        ProcessSingleValueNode(node, level);

        WriteLine(level, FormatOperator(node.OperatorKind));

        ProcessNode(node.Operand, level + 1, parentName);
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles an any operation applicable to arrays, lists and collections.
    /// </summary>
    private static void ProcessAnyNode
    (
        AnyNode node, 
        int level
    )
    {
        ProcessSingleValueNode(node, level);

        WriteLine(level, FormatOperator(node.Kind));

        string? parentName = null;

        if (node.Source is CollectionPropertyAccessNode collectionPropertyAccessNode)
        {
            parentName = GetPropertyName(collectionPropertyAccessNode, null);
        }
        else if (node.Source is CollectionComplexNode collectionComplexNode)
        {
            parentName = GetPropertyName(collectionComplexNode, null);
        }

        if (!string.IsNullOrEmpty(parentName))
        {
            WriteLine(level + 1, FormatProperty(parentName));
            ProcessNode(node.Body, level + 2, parentName);
        }
        else
        {
            ProcessNode(node.Body, level + 1, null);
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a node holing an 'in' operation.
    /// </summary>
    private static void ProcessInNode
    (
        InNode node, 
        int level, 
        string? parentName
    )
    {
        ProcessSingleValueNode(node, level);

        WriteLine(level, FormatOperator(node.Kind));

        // The left element of the in node holds the property name.
        if (node.Left is SingleValuePropertyAccessNode singleValuePropertyAccessNode && 
            !string.IsNullOrEmpty(singleValuePropertyAccessNode.Property?.Name))
        {
            WriteLine(level + 1, FormatProperty(GetPropertyName(singleValuePropertyAccessNode.Property?.Name ?? "", parentName)));
        }
        else if (node.Left is SingleValueOpenPropertyAccessNode singleValueOpenPropertyAccessNode && 
            !string.IsNullOrEmpty(singleValueOpenPropertyAccessNode.Name))
        {
            WriteLine(level + 1, FormatProperty(GetPropertyName(singleValueOpenPropertyAccessNode.Name ?? "", parentName)));
        }

        // The right element of the in node holds the collection of the values. 
        if (node.Right is CollectionConstantNode collectionConstantNode)
        {
            ProcessCollectionConstantNode(collectionConstantNode, level + 1, parentName);
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a node holding a function call, such as 'startsWith', 'contains', etc.
    /// </summary>
    private static void ProcessSingleValueFunctionCallNode
    (
        SingleValueFunctionCallNode node, 
        int level, 
        string? parentName
    )
    {
        ProcessSingleValueNode(node, level);

        WriteLine(level, FormatOperator(node.Name));

        // The first item in the array of parameters holds the property being used in the function.
        if (node.Parameters.FirstOrDefault() is SingleValuePropertyAccessNode param)
        {
            WriteLine(level + 1, FormatProperty(GetPropertyName(param.Property.Name, parentName)));
        }

        // The rest of the items must be constants.
        IEnumerable<QueryNode> values = node.Parameters.Skip(1);

        foreach (QueryNode value in values) 
        {
            if (value is SingleValueNode singleValue)
            {
                ProcessNode(singleValue, level + 1, parentName);
            }
        }
    }

    /// <inheritdoc cref="ProcessNode(SingleValueNode, int, string?)" path="param"/>
    /// <summary>
    /// Handles a binary operator, such as 'eq', 'ne', 'and', 'or', etc.
    /// </summary>
    private static void ProcessBinaryOperatorNode
    (
        BinaryOperatorNode node, 
        int level, 
        string? parentName
    )
    {
        ProcessSingleValueNode(node, level);

        WriteLine(level, FormatOperator(node.OperatorKind));

        ProcessNode(node.Left, level + 1, parentName);
        ProcessNode(node.Right, level + 1, parentName);
    }
    #endregion

    #region Property name formatting methods
    /// <summary>
    /// Appends name of the parent to the given name if needed.
    /// </summary>
    /// <param name="name">
    /// Name of the property.
    /// </param>
    /// <param name="parentName">
    /// Name of the parent collection property (to which the 'Any' operation is applied).
    /// </param>
    /// <returns>
    /// Property name.
    /// </returns>
    private static string GetPropertyName
    (
        string name,
        string? parentName
    )
    {
        return string.IsNullOrEmpty(parentName)
            ? name
            : parentName + _separator + name;
    }

    /// <inheritdoc cref="GetPropertyName(string, string)" path="param|returns"/>
    /// <summary>
    /// Generates the name of the complex (i.e. nested) property that includes the names of all parents.
    /// </summary>
    /// <param name="node">
    /// Property node.
    /// </param>
    private static string GetPropertyName
    (
        SingleValuePropertyAccessNode node,
        string? parentName
    )
    {
        string path = "";
        string parent;

        if (node.Source == null)
        {
            return GetPropertyName(node.Property.Name, parentName);
        }

        // The source property point to the parent object referencing this property.
        var source = node.Source;

        while (source != null)
        {
            // There may be a couple of types used as sources.
            // In our example, UserFilter.Name is a SingleComplexNode, 
            // while UserFilter.Sponsor.Name is a SingleNavigationNode.
            // There may be other case, but I'm not sure how to test.
            if (source is SingleComplexNode singleComplexNode &&
                !string.IsNullOrEmpty(singleComplexNode.Property?.Name))
            {
                parent = singleComplexNode.Property.Name ?? "";
                source = singleComplexNode.Source;
            }
            else if (source is SingleNavigationNode singleNavigationNode &&
                !string.IsNullOrEmpty(singleNavigationNode.NavigationProperty?.Name))
            {
                parent = singleNavigationNode.NavigationProperty?.Name ?? "";
                source = singleNavigationNode.Source;
            }
            else
            {
                break;
            }

            path = string.IsNullOrEmpty(path)
                ? parent
                : parent + _separator + path;
        }

        return string.IsNullOrEmpty(path)
            ? GetPropertyName(node.Property.Name, parentName)
            : GetPropertyName(GetPropertyName(node.Property.Name, path), parentName);
    }

    /// <inheritdoc cref="GetPropertyName(SingleValuePropertyAccessNode, string)" path="param|returns"/>
    private static string GetPropertyName
    (
        SingleValueOpenPropertyAccessNode node,
        string? parentName
    )
    {
        string path = "";
        string parent;

        if (node.Source == null)
        {
            return GetPropertyName(node.Name, parentName);
        }

        // The source property point to the parent object referencing this property.
        var source = node.Source;

        while (source != null)
        {
            // There may be a couple of types used as sources.
            // In our example, UserFilter.Name is a SingleComplexNode, 
            // while UserFilter.Sponsor.Name is a SingleNavigationNode.
            // There may be other case, but I'm not sure how to test.
            if (source is SingleComplexNode singleComplexNode &&
                !string.IsNullOrEmpty(singleComplexNode.Property?.Name))
            {
                parent = singleComplexNode.Property.Name ?? "";
                source = singleComplexNode.Source;
            }
            else if (source is SingleNavigationNode singleNavigationNode &&
                !string.IsNullOrEmpty(singleNavigationNode.NavigationProperty?.Name))
            {
                parent = singleNavigationNode.NavigationProperty?.Name ?? "";
                source = singleNavigationNode.Source;
            }
            else
            {
                break;
            }

            path = string.IsNullOrEmpty(path)
                ? parent
                : parent + _separator + path;
        }

        return string.IsNullOrEmpty(path)
            ? GetPropertyName(node.Name, parentName)
            : GetPropertyName(GetPropertyName(node.Name, path), parentName);
    }

    /// <inheritdoc cref="GetPropertyName(SingleValuePropertyAccessNode, string)" path="param|returns"/>
    private static string GetPropertyName
    (
        CollectionComplexNode node,
        string? parentName
    )
    {
        string path = "";
        string parent;

        if (node.Source == null)
        {
            return GetPropertyName(node.Property.Name, parentName);
        }

        // The source property point to the parent object referencing this property.
        var source = node.Source;

        while (source != null)
        {
            // There may be a couple of types used as sources.
            // In our example, UserFilter.Name is a SingleComplexNode, 
            // while UserFilter.Sponsor.Name is a SingleNavigationNode.
            // There may be other case, but I'm not sure how to test.
            if (source is SingleComplexNode singleComplexNode &&
                !string.IsNullOrEmpty(singleComplexNode.Property?.Name))
            {
                parent = singleComplexNode.Property.Name ?? "";
                source = singleComplexNode.Source;
            }
            else if (source is SingleNavigationNode singleNavigationNode &&
                !string.IsNullOrEmpty(singleNavigationNode.NavigationProperty?.Name))
            {
                parent = singleNavigationNode.NavigationProperty?.Name ?? "";
                source = singleNavigationNode.Source;
            }
            else
            {
                break;
            }

            path = string.IsNullOrEmpty(path)
                ? parent
                : parent + _separator + path;
        }

        return string.IsNullOrEmpty(path)
            ? GetPropertyName(node.Property.Name, parentName)
            : GetPropertyName(GetPropertyName(node.Property.Name, path), parentName);
    }

    /// <inheritdoc cref="GetPropertyName(SingleValuePropertyAccessNode, string)" path="param|returns"/>
    private static string GetPropertyName
    (
        CollectionPropertyAccessNode node,
        string? parentName
    )
    {
        string path = "";
        string parent;

        if (node.Source == null)
        {
            return GetPropertyName(node.Property.Name, parentName);
        }

        // The source property point to the parent object referencing this property.
        var source = node.Source;

        while (source != null)
        {
            // There may be a couple of types used as sources.
            // In our example, UserFilter.Name is a SingleComplexNode, 
            // while UserFilter.Sponsor.Name is a SingleNavigationNode.
            // There may be other case, but I'm not sure how to test.
            if (source is SingleComplexNode singleComplexNode &&
                !string.IsNullOrEmpty(singleComplexNode.Property?.Name))
            {
                parent = singleComplexNode.Property.Name ?? "";
                source = singleComplexNode.Source;
            }
            else if (source is SingleNavigationNode singleNavigationNode &&
                !string.IsNullOrEmpty(singleNavigationNode.NavigationProperty?.Name))
            {
                parent = singleNavigationNode.NavigationProperty?.Name ?? "";
                source = singleNavigationNode.Source;
            }
            else
            {
                break;
            }

            path = string.IsNullOrEmpty(path)
                ? parent
                : parent + _separator + path;
        }

        return string.IsNullOrEmpty(path)
            ? GetPropertyName(node.Property.Name, parentName)
            : GetPropertyName(GetPropertyName(node.Property.Name, path), parentName);
    }

    #endregion
    
    #region Output formatting methods
    /// <summary>
    /// Formats node message.
    /// </summary>
    /// <param name="name">
    /// Name of the node.
    /// </param>
    /// <returns>
    /// Formatted node message.
    /// </returns>
    private static string FormatNode
    (
        object name
    )
    {
        return "NODE: " + name;
    }

    /// <summary>
    /// Formats operator message.
    /// </summary>
    /// <param name="name">
    /// Name of the operator.
    /// </param>
    /// <returns>
    /// Formatted operator message.
    /// </returns>
    private static string FormatOperator
    (
        object name
    )
    {
        return "OPERATOR: " + name;
    } 

    /// <summary>
    /// Formats property message.
    /// </summary>
    /// <param name="name">
    /// Name of the property.
    /// </param>
    /// <returns>
    /// Formatted property message.
    /// </returns>
    private static string FormatProperty
    (
        object name
    )
    {
        return "PROPERTY: " + name;
    }

    /// <summary>
    /// Formats value message.
    /// </summary>
    /// <param name="name">
    /// Name of the value.
    /// </param>
    /// <returns>
    /// Formatted value message.
    /// </returns>
    private static string FormatValue
    (
        object name
    )
    {
        return "VALUE: " + name;
    }
    #endregion

    #region Print functions
    /// <summary>
    /// Prints text with appropriate indentation.
    /// </summary>
    /// <param name="indentLevel">
    /// Indentation level.
    /// </param>
    /// <param name="message">
    /// Message text.
    /// </param>
    /// <param name="args">
    /// Optional message parameters.
    /// </param>
    private static void WriteLine
    (
        int indentLevel, 
        string message, 
        params object[] args
    )
    {
        string indent = new(' ', indentLevel * _indentLength);
        Console.WriteLine(indent + message, args);
    }
    #endregion
}

#region Data models used by the OData filter
/// <summary>
/// Defines types of users.
/// </summary>
public enum UserType
{
    Employee,
    Contractor,
    Guest
}

/// <summary>
/// Defines name parts.
/// </summary>
public class PersonName
{
    public string? GivenName
    {
        get; set;
    }

    public string? NickName
    {
        get; set;
    }

    public string? Surname
    {
        get; set;
    }

    public char? MiddleInitial
    {
        get; set;
    }
}

/// <summary>
/// Defines social login info.
/// </summary>
public class SocialLogin
{
    public string? Name
    {
        get; set;
    }

    public string? Url
    {
        get; set;
    }
}

/// <summary>
/// Primary filter object (it may not necessarily correspond to the corresponding backend entity).
/// </summary>
public class User
{
    public int? Id
    {
        get; set;
    }

    public UserType? Type
    {
        get; set;
    }

    public PersonName? Name
    {
        get; set;
    }

    public string? DisplayName
    {
        get; set;
    }

    public string? Email
    {
        get; set;
    }

    public bool? Enabled
    {
        get; set;
    }

    // Use this property to test complex properties (it can be nested indefinitely).
    public User? Sponsor
    {
        get; set;
    }

    public string[]? PhoneNumbers
    {
        get; set;
    }

    public List<SocialLogin>? SocialLogins
    {
        get; set;
    }
}
#endregion

Here is the program output:

ODATA SCHEMA ELEMENTS:
- TestOData1.User: TypeDefinition
- TestOData1.PersonName: TypeDefinition
- TestOData1.SocialLogin: TypeDefinition
- TestOData1.UserType: TypeDefinition
- Default.Container: EntityContainer

------------------------------------------------------------------------
EXPRESSION: not(enabled)
------------------------------------------------------------------------
OPERATOR: Not
  PROPERTY: Enabled

------------------------------------------------------------------------
EXPRESSION: not(true)
------------------------------------------------------------------------
OPERATOR: Not
  VALUE: True

------------------------------------------------------------------------
EXPRESSION: email eq null
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Email
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: email ne null
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Email
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: email eq 'john@mail.com'
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Email
  VALUE: john@mail.com

------------------------------------------------------------------------
EXPRESSION: email ne 'john@mail.com'
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Email
  VALUE: john@mail.com

------------------------------------------------------------------------
EXPRESSION: email eq displayName
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Email
  PROPERTY: DisplayName

------------------------------------------------------------------------
EXPRESSION: email ne displayName
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Email
  PROPERTY: DisplayName

------------------------------------------------------------------------
EXPRESSION: contains(email, '@')
------------------------------------------------------------------------
OPERATOR: contains
  PROPERTY: Email
  VALUE: @

------------------------------------------------------------------------
EXPRESSION: not contains(email, '@')
------------------------------------------------------------------------
OPERATOR: Not
  OPERATOR: contains
    PROPERTY: Email
    VALUE: @

------------------------------------------------------------------------
EXPRESSION: contains(email, displayName)
------------------------------------------------------------------------
OPERATOR: contains
  PROPERTY: Email
  PROPERTY: DisplayName

------------------------------------------------------------------------
EXPRESSION: not contains(email, displayName)
------------------------------------------------------------------------
OPERATOR: Not
  OPERATOR: contains
    PROPERTY: Email
    PROPERTY: DisplayName

------------------------------------------------------------------------
EXPRESSION: startsWith(email, 'john')
------------------------------------------------------------------------
OPERATOR: startswith
  PROPERTY: Email
  VALUE: john

------------------------------------------------------------------------
EXPRESSION: not startsWith(email, 'john')
------------------------------------------------------------------------
OPERATOR: Not
  OPERATOR: startswith
    PROPERTY: Email
    VALUE: john

------------------------------------------------------------------------
EXPRESSION: endsWith(email, '@mail.com')
------------------------------------------------------------------------
OPERATOR: endswith
  PROPERTY: Email
  VALUE: @mail.com

------------------------------------------------------------------------
EXPRESSION: not endsWith(email, '@mail.com')
------------------------------------------------------------------------
OPERATOR: Not
  OPERATOR: endswith
    PROPERTY: Email
    VALUE: @mail.com

------------------------------------------------------------------------
EXPRESSION: email in ('john@mail.com', 'mary@mail.com')
------------------------------------------------------------------------
OPERATOR: In
  PROPERTY: Email
  VALUE: john@mail.com
  VALUE: mary@mail.com

------------------------------------------------------------------------
EXPRESSION: not (email in ('john@mail.com', 'mary@mail.com'))
------------------------------------------------------------------------
OPERATOR: Not
  OPERATOR: In
    PROPERTY: Email
    VALUE: john@mail.com
    VALUE: mary@mail.com

------------------------------------------------------------------------
EXPRESSION: id eq 0
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Id
  VALUE: 0

------------------------------------------------------------------------
EXPRESSION: id gt 0
------------------------------------------------------------------------
OPERATOR: GreaterThan
  PROPERTY: Id
  VALUE: 0

------------------------------------------------------------------------
EXPRESSION: id lt 2000
------------------------------------------------------------------------
OPERATOR: LessThan
  PROPERTY: Id
  VALUE: 2000

------------------------------------------------------------------------
EXPRESSION: id ge 1
------------------------------------------------------------------------
OPERATOR: GreaterThanOrEqual
  PROPERTY: Id
  VALUE: 1

------------------------------------------------------------------------
EXPRESSION: id le 2000
------------------------------------------------------------------------
OPERATOR: LessThanOrEqual
  PROPERTY: Id
  VALUE: 2000

------------------------------------------------------------------------
EXPRESSION: name eq null
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Name
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: name ne null
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Name
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: name/givenName eq null
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Name/GivenName
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: sponsor/name/givenName eq null
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Sponsor/Name/GivenName
  VALUE: (null)

------------------------------------------------------------------------
EXPRESSION: name/surname ne sponsor/name/surname
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Name/Surname
  PROPERTY: Sponsor/Name/Surname

------------------------------------------------------------------------
EXPRESSION: name/givenName in ('John', 'Mary')
------------------------------------------------------------------------
OPERATOR: In
  PROPERTY: GivenName
  VALUE: John
  VALUE: Mary

------------------------------------------------------------------------
EXPRESSION: name/givenName ne name/nickName
------------------------------------------------------------------------
OPERATOR: NotEqual
  PROPERTY: Name/GivenName
  PROPERTY: Name/NickName

------------------------------------------------------------------------
EXPRESSION: startsWith(displayName, 'J')
------------------------------------------------------------------------
OPERATOR: startswith
  PROPERTY: DisplayName
  VALUE: J

------------------------------------------------------------------------
EXPRESSION: type eq 'Employee'
------------------------------------------------------------------------
OPERATOR: Equal
  PROPERTY: Type
  VALUE: Employee

------------------------------------------------------------------------
EXPRESSION: type eq 'Guest' and name/Surname eq 'Johnson'
------------------------------------------------------------------------
OPERATOR: And
  OPERATOR: Equal
    PROPERTY: Type
    VALUE: Guest
  OPERATOR: Equal
    PROPERTY: Name/Surname
    VALUE: Johnson

------------------------------------------------------------------------
EXPRESSION: type eq 'Contractor' and not(endsWith(email, '@mail.com'))
------------------------------------------------------------------------
OPERATOR: And
  OPERATOR: Equal
    PROPERTY: Type
    VALUE: Contractor
  OPERATOR: Not
    OPERATOR: endswith
      PROPERTY: Email
      VALUE: @mail.com

------------------------------------------------------------------------
EXPRESSION: enabled eq false and type in ('Employee', 'Contractor')
------------------------------------------------------------------------
OPERATOR: And
  OPERATOR: Equal
    PROPERTY: Enabled
    VALUE: False
  OPERATOR: In
    PROPERTY: Type
    VALUE: Employee
    VALUE: Contractor

------------------------------------------------------------------------
EXPRESSION: (enabled eq true and type eq 'Employee') or (enabled eq false and (type eq 'Guest' or endsWith(email, '@mail.com')))
------------------------------------------------------------------------
OPERATOR: Or
  OPERATOR: And
    OPERATOR: Equal
      PROPERTY: Enabled
      VALUE: True
    OPERATOR: Equal
      PROPERTY: Type
      VALUE: Employee
  OPERATOR: And
    OPERATOR: Equal
      PROPERTY: Enabled
      VALUE: False
    OPERATOR: Or
      OPERATOR: Equal
        PROPERTY: Type
        VALUE: Guest
      OPERATOR: endswith
        PROPERTY: Email
        VALUE: @mail.com

------------------------------------------------------------------------
EXPRESSION: phoneNumbers/any(p: p eq '123-456-6789')
------------------------------------------------------------------------
OPERATOR: Any
  PROPERTY: PhoneNumbers
    OPERATOR: Equal
      PROPERTY: PhoneNumbers
      VALUE: 123-456-6789

------------------------------------------------------------------------
EXPRESSION: socialLogins/any(s: s/name eq 'Facebook')
------------------------------------------------------------------------
OPERATOR: Any
  PROPERTY: SocialLogins
    OPERATOR: Equal
      PROPERTY: SocialLogins/Name
      VALUE: Facebook

------------------------------------------------------------------------
EXPRESSION: socialLogins/any(s: s/name eq 'Facebook' or endsWith(s/url, 'google.com'))
------------------------------------------------------------------------
OPERATOR: Any
  PROPERTY: SocialLogins
    OPERATOR: Or
      OPERATOR: Equal
        PROPERTY: SocialLogins/Name
        VALUE: Facebook
      OPERATOR: endswith
        PROPERTY: SocialLogins/Url
        VALUE: google.com

------------------------------------------------------------------------
EXPRESSION: sponsor/phoneNumbers/any(p: p eq '123-456-6789')
------------------------------------------------------------------------
OPERATOR: Any
  PROPERTY: Sponsor/PhoneNumbers
    OPERATOR: Equal
      PROPERTY: Sponsor/PhoneNumbers
      VALUE: 123-456-6789

------------------------------------------------------------------------
EXPRESSION: sponsor/socialLogins/any(s: s/name eq 'Facebook')
------------------------------------------------------------------------
OPERATOR: Any
  PROPERTY: Sponsor/SocialLogins
    OPERATOR: Equal
      PROPERTY: Sponsor/SocialLogins/Name
      VALUE: Facebook

Enjoy!

Wednesday, May 1, 2024

Customizing .editorconfig file

Summary: A few non-default settings in the .editorconfig file that will improve the code.
Before checking in code updates, I prefer the compiler output (and the Visual Studio Error List tab) to show no errors (obviously) or warnings. In most cases, the warnings are useful (I learned a few programming trick from some), but some (mostly, IntelliSense) warnings are a bit irritating, so I prefer to supress them. To allow my warning supression settings to be shared across the team, I put them in the .editorconfig file, which gets saved in the source control along with the project. The following settings override the defaults:
# Expression-level preferences
csharp_style_unused_value_expression_statement_preference = unused_local_variable:none

# Indentation preferences
csharp_indent_labels = flush_left

# IDE0058: Expression value is never used
dotnet_diagnostic.IDE0058.severity = silent

Sunday, February 11, 2024

Unit testing cheat sheet (xUnit, FakeItEasy, FluentAssertions)

Summary: Samples of C# code handling common unit testing tasks using xUnit, FakeItEasy, and FluentAssertions frameworks.

Here are some tips, samples, and suggestions for implementing common unit testing tasks.

Unit test without parameters:

[Fact]
void SampleClassName_MethodToBeTested_DescriptiveTestTitle()
{
    // ARRANGE
    // ACT
    // ASSERT
}

Unit test with parameters:

[Theory]
[InlineData("abc", 1, true)]
[InlineData("xyz", 2, false)]
void SampleClassName_MethodToBeTested_DescriptiveTestTitle
(
    string? param1,
    int? param2,
    bool? param3
)
{
    // ARRANGE
    // ACT
    // ASSERT
}

Unit tests with DateTime or DateTimeOffset parameters:

[Theory]
[InlineData("2024-06-05 23:45:10.456", "3/28/2007 12:13:50 PM -07:00")]
void SampleClassName_MethodToBeTested_DescriptiveTestTitle
(
    string? paramDateTime,
    string? paramDateTimeOffset
)
{
    DateTime dateTime = DateTime.Parse(paramDateTime);
    DateTime dateTimeOffset = DateTimeOffset.Parse(paramDateTimeOffset);
    ...
}

Unit tests with complex parameters:

[Theory]
[InlineData("{\"id\":123,\"email\":\"joe.doe@somemail.com\",\"enabled\":true}")]
void SampleClassName_MethodToBeTested_DescriptiveTestTitle
(
    string? paramUser
)
{
	// This example uses Newtonsoft.Json, but the same can be done
    // using the default framework's JSON serializer.
    User? user = JsonConvert.DeserializeObject<User?>(paramUser);
    
    // NOTE: Yes, I know about MemberData, but this seems more straightforward IMHO.
    ...
}

A fake object with the default constructor (can use an interface or a class):

ISample fakeISample = A.Fake<ISample>();
Sample fakeSample = A.Fake<Sample>();
ISample<AnotherSample> fakeGenericSample = A.Fake<ISample<AnotherSample>>();

A fake object with a parametrized constructor:

Sample fakeSample = A.Fake<Sample>(x => x.WithArgumentsForConstructor(new object[] { "param1", 2, true }));

A fake object returns specific property values:

User user = A.Fake<User>();

A.CallTo(() => user.Id).Returns(12345);
A.CallTo(() => user.Email).Returns("joe.doe@somemail.com");
A.CallTo(() => user.Enabled).Returns(true);

A fake object returns a specific method result:

// Data service is used by user service to get user from database
// and we are faking it.
IDataService dataService = A.Fake<IDataService>();

// Define properties of the user object to be retuned.
int id = 12345;

// Let's assume that the method of the UserService class being tested 
// internally calls the GetUserById method of the IDataService object
// (we're using a fake here to simulate a valid return).
A.CallTo(() => dataService.GetUserById(id)).Returns(new User(id));

// UserService is the class we're testing (system under test or SUT).
UserService userService = new UserService(dataService);

// We are testing the Enable method and expect it to be successful.
userService.Enable(id);

Use wildcard to trigger a fake method result for any parameter value:

// A<T>._ is a shortcut for a wildcard.
A.CallTo(() => dataService.GetUserById(A<string>._)).Returns(existingUser);

A fake object returns a specific value from an async method:

IDataService dataService = A.Fake<IDataService>();

// Define properties of the user object to be retuned.
int id = 12345;

// Assume that GetUserById is an async method returning Task<User>.
A.CallTo(() => dataService.GetUserById(A<string>._)).Returns(Task.FromResult(new User(id)));

A fake object returns a specific value from a generic method:

// Data service is used by user service to get user from database
// and we are faking it.
IDataService dataService = A.Fake<IDataService>();

// Define properties of the user object to be retuned.
int id = 12345;

// Data service has a generic method GetUser that we want to fake.
A.CallTo(dataService).Where(call => call.Method.Name == "GetUser")
   .WithReturnType<User>()
   .Returns(new User(id));
   
// UserService is the class we're testing (system under test or SUT).
UserService userService = new UserService(dataService);

Force a fake method to throw an exception:

A.CallTo(() => dataService.GetUserById(A<string>._)).Throws<Exception>();
// Equivalent to:
A.CallTo(() => dataService.GetUserById(A<string>._)).Throws(new Exception());

Expect a method to throw an exception of the exact type:

Assert.Throws<InvalidInputException>(() => userService.UpdateUser(user));

Expect a method to throw any exception derived from the specific type:

Assert.ThrowsAny<InvalidInputException>(() => userService.UpdateUser(user));

Assign expected exception to a variable:

Exception ex = Assert.Throws<InvalidInputException>(() => userService.UpdateUser(user));

Set up a fake SendGrid call:

ISendGridClient _sendGridClient = A.Fake<ISendGridClient>();

System.Net.Http.HttpResponseMessage httpResponse = new();
System.Net.Http.HttpContent         httpContent  = httpResponse.Content;
System.Net.Http.HttpResponseHeaders httpHeaders  = httpResponse.Headers;

httpHeaders.Add("X-Message-Id", "12345");

SendGrid.Response sendGridResponse = 
    A.Fake<SendGrid.Response>(x => x
        .WithArgumentsForConstructor(new object[] { httpStatusCode, httpContent, httpHeaders }));

A.CallTo(() =< _sendGridClient
    .SendEmailAsync(A<SendGridMessage>._, A<CancellationToken>._))
    .Returns(Task.FromResult(sendGridResponse));

Mock HttpContext for a controller class under test:

System.Net.Http.HttpRequest httpRequest = A.Fake<HttpRequest>();
System.Net.Http.HttpContext httpContext= A.Fake<HttpContext>();

A.CallTo(() => httpContext.Request).Returns(httpRequest);

// Set up the request properies that you need.
A.CallTo(() => httpRequest.Scheme).Returns("https");
A.CallTo(() => httpRequest.Host).Returns(new HostString("localhost:8888"));
A.CallTo(() => httpRequest.PathBase).Returns(new PathString("/api/v1"));
A.CallTo(() => httpRequest.Path).Returns(new PathString("sample"));

// SampleController is derived from the ControllerBase class.
SampleController controller = new(...);

controller.ControllerContext =  new ControllerContext()
{
	HttpContext = httpContext
};

Controller method GET returns HTTP status code 200 OK:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.GetUser("1234567890");

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<OkObjectResult>();

// Next, test response specific result.
OkObjectResult? result = actionResult.Result as OkObjectResult;

Controller method POST returns HTTP status code 201 Created:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.CreateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<CreatedResult>();

// Next, test response specific result.
CreatedResult? result = actionResult.Result as CreatedResult;
result.Should().NotBeNull();

// Successful POST must return the URL of the GET method 
// ending with the ID of the newly created object in the
// Location header.
result?.Location.Should().NotBeNull();
result?.Location.Should().EndWith(id);

Controller method PATCH returns HTTP status code 204 No Content:

// Assume that all dependencies have been set.
ActionResult actionResult = controller.UpdateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.BeAssignableTo<NoContentResult>();

Controller method POST returns HTTP status code 400 Bad Request:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.CreateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<BadRequestObjectResult>();

// Next, test response specific result.
BadRequestObjectResult? result = actionResult.Result as BadRequestObjectResult;
result.Should().NotBeNull();

// Finally, check the error object to be returned to consumer.
// This example shows a custom problem details object ErroDetails,
// which may be different in your case.
result?.Value.Should().NotBeNull();
result?.Value.Should().BeAssignableTo<ErrorDetails>();

if (result?.Value is ErrorDetails errorDetails)
{
    // ServiceCodeType is a custom enum value returned via the error object's 
    // ServiceCode property (this check may be different in your case).
    errorDetails.ServiceCode.Should().NotBeNull();  
    errorDetails.ServiceCode.Should().Be(ServiceCodeType.BadRequest.ToString());
}

Controller method POST returns HTTP status code 401 Unauthorized:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.CreateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<UnauthorizedObjectResult>();

// Next, test response specific result.
UnauthorizedObjectResult? result = actionResult.Result as UnauthorizedObjectResult;
result.Should().NotBeNull();

// See example handling 400 Bad Request.

Controller method PATCH returns HTTP status code 404 Not Found:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.UpdateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<NotFoundObjectResult>();

// Next, test response specific result.
NotFoundObjectResult? result = actionResult.Result as NotFoundObjectResult;
result.Should().NotBeNull();

// See example handling 400 Bad Request.

Controller method POST returns HTTP status code 409 Conflict:

// Assume that all dependencies have been set.
ActionResult<User> actionResult = controller.CreateUser(user);

// First, test action result.
actionResult.Should().NotBeNull();
actionResult.Result.Should().NotBeNull();
actionResult.Result.Should().BeAssignableTo<ConflictObjectResult>();

// Next, test response specific result.
ConflictObjectResult? result = actionResult.Result as ConflictObjectResult;
result.Should().NotBeNull();

// See example handling 400 Bad Request.

Mock AppSettings:

// The following dictionary mimics appsettings.json file.
// Notice how array values must be defined using indexes.
Dictionary<string,string?> configSettings = new()
{
    {"ServiceA:ValueSettingX", "ValueX"},
    {"ServiceA:ValueSettingY", "ValueY"},
    {"ServiceA:ValueSettingZ", "ValueZ"},
    {"ServiceA:ArraySetting1:0", "Value0"},
    {"ServiceA:ArraySetting1:1", "Value1"},
    {"ServiceA:ArraySetting1:2", "Value2"},
}

IConfiguration config = new ConfigurationBuilder()
    .AddInMemoryCollection(configSettings)
    .Build();

Common FluentAssertions:

// Value should not be null.
value.Should().NotBeNull();

// Value should be of specific type.
value.Should().BeOfType<User>();

// Value should be equal to.
value.Should().Be(1);
value.Should().Be(true);
value.Should().Be("expected value");

// Value should contain (comparison is case sensitive).
value.Should().Contain("value");

// Value should contain any one of the specified values (comparison is case sensitive):
value.Should().ContainAny("value1", "value2");

// Value should contain all of the specified values (comparison is case sensitive):
value.Should().ContainAll("value1", "value2");

// String value should be equal to (comparison is case insensitive).
value.Should().BeEquivalentTo("Value");

Wednesday, February 1, 2023

How to edit a web page layout in the browser

Summary: How to edit a web page in a browser.

Here is something my 10-year-old showed me that I used at work today. Since I do not do this often, it's mostly a note to self (in case I forget). If you need to play with a web page layout in a browser (I, for example, needed to add some new lines to a few messages on the page to see what makes them easier to read). It is very simple (the instructions assume you are using Google Chrome, but I suspect you can do the same in other browsers).

  1. Right click anywehere on the web page and select the Inspect option from the context menu.
  2. In the Developer Tools' window, switch to the Console tab.
  3. At the prompt, type in document.body.contentEditable=true and press Enter.
  4. Make your changes on the page (you can cadd, change and delete text, and do other things).
  5. When done with your changes, at the prompt, type in document.body.contentEditable=false and press Enter
Happy programming.

Monday, June 27, 2022

Tell Git to bypass proxy for internal addresses

Summary: How to make Git bypass proxy settings when connecting to internal repositories.

A common question enterprise application developers ask that generally gets unsatisfactory answers is: how do you configure Git to use the corporate proxy settings to connect to the external repositories (such as Github) while bypassing the proxy when connecting to internal repositories (such as corporate Gitlab instances)? A typical answer would recommend configuring proxy settings on each repo. The problem with this approach is that it assumes that you already have a local repo, but how do you access a repo if you want to perform the initial clone other than changing global proxy settings?

One option would be to specify proxy in the git clone command. For example, to bypass the global proxy settings, run it like this:

git -c http.proxy= clone https://internalgithub.com/foo/bar.git

But there is an even better solution: you can specify proxy settings on a per-domain basis. The following instructions assume that you are using a Windows system (I suspect that Mac or Linux instructions would be slightly different, but the idea must be the same). Simply, open the .gitconfig file located in the root of your user profile folder (such as c:\Windows\Users\yourusername), and add lines similar to the following:

[http]
	proxy = http://your.corp.proxy.server.com:XXX
	sslBackend = schannel
[https]
	proxy = http://your.corp.proxy.server.com:YYY
[http "https://your.company.repo.host1.com/"]
	proxy = ""
	sslVerify = false
[http "https://your.company.repo.host2.com/"]
	proxy = ""
	sslVerify = false
[credential "https://your.company.repo.host1.com/"]
	provider = generic
[credential "https://your.company.repo.host2.com/"]
	provider = generic

Once you save the .gitconfig file, you will need to log off and log on to the system for the changes to take effect.

Notice that your global proxy settings are defined under both the http and https sections, while domain-specific sections only use http (when I added the https sections for domain-specific URLs, it stopped working). Also, the global proxy definition assumes that the proxy server does not require authentication (if it does, adjust the proxy definition appropriately).

Thursday, May 5, 2022

How to stop and start tracking file changes for Git

Summary: Git commands that let you stop and start tracking project file chages.

During application development, there may be situations when you want to make a change in a file (e.g. modify an application setting) without accidentally committing this change to source control. There may be better ways to do this, but one option is to tell Git to stop tracking the file before you make the the change that you do not commit to the repo. Say, there is an appsettings.Developement.json file that you want to stop and start tracking. This is how I do it.

Create two files stop-tracking-appsettings.bat and start-tracking-appsettings.bat files in the solution folder (PROJECT_FOLDER must be replace by the name of the project directory under the solution folder).

stop-tracking-appsettings.bat

@echo off
git update-index --skip-worktree PROJECT_FOLDER\appsettings.Development.json

start-tracking-appsettings.bat

@echo off
git update-index --no-skip-worktree PROJECT_FOLDER\appsettings.Development.json

Now you can either run these files from a console whenever you want to stop and start tracking file changes. Even better, in Visual Studio, you can create a custom tool menu option (e.g. Run batch file) that you can invoke by right clicking the file in the Solution Explorer and selectin the context menu option (see this Stack Overflow answer explaining how to set it up).

Thursday, October 21, 2021

Resources that helped me pass the CISSP exam

Summary: List of helpful resources for CISSP exam.

After four months of intense study (and about a year since I started) I passed the CISSP exam. Here is the list of resources I found useful (and some that weren't).

BOOTCAMPS

Feedback from my colleagues who went to bootcamps varies but the general consensus is that with some exceptions they are not really worth the cost. There is only a handful of trainers who are exceptional and you can find them online for cheaper than $2K+. Yes, most bootcamps can give you a voucher to repeat an exam if you do not pass, but it's still cheaper to pay for two exams than for one bootcamp.

The digital versions of the bootcamps I used and found helpful include:

  • Thor's CISSP Udemy course. I have a Udemy subscription through work, so I watched this course 3 times: first, in the very beginning of my studies (and did not really like it), then after the 2021 update, and finally on the week of the exam at 2x speed (now, after watching it three times, I can say, it's excellent).
  • I lost the link but there was an old audio version of Kelly Handerhan's Cybrary course posted on Reddit. I watched a couple of video episodes when they were free at Cybrary, but mostly listened to the audio while driving. Overall, I think I listened to the whole series 2-3 times (at x1.7 speed). Kelly is one of (if not) the best instructors out there. The audio version is a bit outdated, but the fundamentals are still there. Highly recommend. Also, make sure you watch Kelly's Why You Will Pass the CISSP [exam] video. (UPDATE: Found links to the audios here.)
  • Destination Certification's Mind Map series. Excellent coverage. I would recommend also watching the supplemental videos, like the one that explains how Kerberos works and there are others.

BOOKS

I first planned to use O'Reilly Digital Subscription (through work), but the digital versions did not work for me, so I switched to paperbacks (for casual reading, I prefer digital).

PRACTICE TESTS

When practicing tests, the point is not to remember, but to try to understand why an answer is right or wrong. Yes you need to memorize a few things, but generally, memorization will not take you too far.

  • Boson Practice Exams. Must be used on a desktop (Windows, not sure it the environment works on a Mac). Very good overall. Explains why the correct answer is correct and why each wrong answer is wrong. I think it expires after 6 months once you start using it, so keep it in mind. I also tried a couple of practical labs (not the tests), but did not find them particularly useful. If you have no practical experience with the concepts (like hashing, etc), they may offer some value, though.

I'm using Android, but assume Apple store has the same apps:

  • (ISC)² Official CISSP Tests. Good app with some limitations. A few questions had wrong answers. There is no way to mark a question when you are taking a practice test. Once you are done with the practice test and exit the app, your results are gone.
  • CISSP Practice Tests. Use the free version. Found a few errors, but overall good.

I used a number of other free apps but as I'm checking now, they are either discontinued, or were not very good.

UTILITIES

  • Chegg Prep. Used it for building flashcards for the topics I needed to review. Terrible app, but it's the one I started to use and it was too late to switch. It can get you by.

VIDEOS

For every topic that I struggled with, I just searched the Internet for the best resource (in most cases, video) to cover it. There are too many to list, but I want to mention this one because it helped me a lot to learn about networking (one of my weak areas):

COMMUNITIES

Spent a lot of time here:

SEE ALSO

How I passed the CISSP exam

Best of luck to all learners. You can do it!