The 20-Line MCP Server

Here's a complete, production-ready MCP server that could provide multiple useful tools:

#:package Microsoft.Extensions.Hosting@9.0.8
#:package ModelContextProtocol@0.3.0-preview.3
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
    // Configure all logs to go to stderr
    consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});

// Register the MCP server
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

// Build and run the MCP Server Application
await builder.Build().RunAsync();

//====== TOOLS ======

[McpServerToolType]
public static class TextTools
{
    [McpServerTool, Description("Generates a password with specified length and complexity")]
    public static string GeneratePassword(int length = 12, bool includeSymbols = true, bool includeNumbers = true)
    {
        const string letters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
        const string numbers = "0123456789";
        const string symbols = "!@#$%^&*()_+-=[]{}|;:,.<>?";

        var chars = letters;
        if (includeNumbers) chars += numbers;
        if (includeSymbols) chars += symbols;

        return new string(Enumerable.Repeat(chars, length)
            .Select(s => s[Random.Shared.Next(s.Length)]).ToArray());
    }
}

That's it! Save this as mcp-server.cs and run with dotnet run mcp-server.cs.

To explore the benefits of single-file MCPs further, I created an open-source solution: https://anymcp.io/.

Why This Approach is Revolutionary

1. Zero Project Setup

Traditional .NET development requires creating projects, managing dependencies, and complex build configurations. The #:package directive eliminates all that overhead.

2. Automatic Tool Discovery

The WithToolsFromAssembly() method automatically discovers any class marked with [McpServerToolType] and exposes its methods as MCP tools. No manual registration required.

3. Type-Safe by Default

Unlike JSON-based tool definitions, your tools are strongly typed. IntelliSense works, refactoring is safe, and runtime errors are minimized.

4. Production Ready

This isn't a toy example. The server includes proper logging, error handling, and follows MCP protocol specifications.

Expanding Your Server

Adding new tools is trivial. Here's how to add mathematical capabilities:

[McpServerToolType]
public static class MathTools
{
    [McpServerTool, Description("Evaluates mathematical expressions safely")]
    public static double Calculate(string expression)
    {
        var table = new System.Data.DataTable();
        return Convert.ToDouble(table.Compute(expression.Replace("^", "**"), ""));
    }

    [McpServerTool, Description("Converts temperatures between units (C, F, K)")]
    public static double ConvertTemp(double value, string from, string to) =>
        (from.ToLower(), to.ToLower()) switch
        {
            ("c", "f") => value * 9/5 + 32,
            ("f", "c") => (value - 32) * 5/9,
            ("c", "k") => value + 273.15,
            ("k", "c") => value - 273.15,
            _ => value
        };
}

Advanced Features Made Simple

Complex Return Types

Return tuples, objects, or collections naturally:

[McpServerTool, Description("Analyzes text content")]
public static (int words, int chars, int lines, double readability) AnalyzeText(string text)
{
    var words = text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
    var sentences = text.Split('.', '!', '?').Length - 1;
    var readability = Math.Max(0, 206.835 - 1.015 * (words / Math.Max(sentences, 1)));

    return (words, text.Length, text.Split('\n').Length, readability);
}

Error Handling

Exceptions are automatically converted to proper MCP error responses:

[McpServerTool, Description("Fetches and parses web content")]
public static async Task<string> FetchUrl(string url)
{
    using var client = new HttpClient();
    var response = await client.GetStringAsync(url); // Throws on error - automatically handled
    return response;
}

Deployment and Integration

Configuration for MCP Clients

Create .mcp.json in your project root:

{
  "servers": {
    "MyUtilityServer": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "C:\\path\\to\\your\\mcp-server.cs"]
    }
  }
}

Docker Deployment

For containerized environments:

FROM mcr.microsoft.com/dotnet/sdk:10.0-preview-alpine
WORKDIR /app
COPY mcp-server.cs .
ENTRYPOINT ["dotnet", "run", "mcp-server.cs"]

Environment variables

Sometimes you might need to pass environment variables into your code, such as tokens or authentication keys. This can be done very easily with this approach.

First, add the input and set up the variable in your .mcp.json file.

{
  "inputs": [
    {
      "id": "user_email",
      "description": "Your email",
      "type": "promptString",
      "password": true
    }
  ],
  "servers": {
    "DotnetMcpFile": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "C:\\path\\to\\your\\mcp-server.cs"]
      "env": {
        "USER_EMAIL": "${input:user_email}"
      }
    }
  }
}

Visual Studio will display a prompt where you can enter the data.

To use the data, apply C# Environment methods.

[McpServerToolType]
public static class EnvironmentExamples
{
    [McpServerTool, Description("Gets environment variable value with optional default")]
    public static string GetEnvironmentVariable(string variableName, string? defaultValue = null)
    {
        var value = Environment.GetEnvironmentVariable(variableName);

        if (string.IsNullOrEmpty(value))
        {
            if (defaultValue != null)
                return $"Environment variable '{variableName}' not found, using default: {defaultValue}";
            else
                return $"Environment variable '{variableName}' not found";
        }

        return $"{variableName} = {value}";
    }
}

And the result is shown below:

Real-World Example: File System Tools

Here's a practical server that provides file system operations:

[McpServerToolType]
public static class FileTools
{
    [McpServerTool, Description("Lists files in directory with optional pattern")]
    public static string[] ListFiles(string path, string pattern = "*") =>
        Directory.GetFiles(path, pattern).Take(100).ToArray();

    [McpServerTool, Description("Gets file information")]
    public static object GetFileInfo(string path)
    {
        var info = new FileInfo(path);
        return new { 
            Name = info.Name, 
            Size = info.Length, 
            Modified = info.LastWriteTime,
            IsReadOnly = info.IsReadOnly 
        };
    }

    [McpServerTool, Description("Safely reads text file with size limits")]
    public static string ReadTextFile(string path, int maxLines = 1000) =>
        string.Join("\n", File.ReadLines(path).Take(maxLines));
}

Best Practices

1. Security First

Always validate inputs and limit resource usage:

[McpServerTool]
public static string ProcessFile(string path)
{
    if (!Path.IsPathFullyQualified(path)) throw new ArgumentException("Use absolute paths");
    if (new FileInfo(path).Length > 10_000_000) throw new ArgumentException("File too large");
    // ... process safely
}

2. Clear Descriptions

Make your tools discoverable with detailed descriptions:

[McpServerTool, Description("Compresses images while maintaining quality. Supports JPEG (quality 85), PNG (lossless), WebP (quality 90). Max input: 50MB")]
public static byte[] CompressImage(byte[] imageData, string format = "jpeg") { /* ... */ }

3. Async When Needed

Use async for I/O operations:

[McpServerTool, Description("Downloads and processes remote content")]
public static async Task<string> ProcessRemoteData(string url)
{
    using var client = new HttpClient();
    var data = await client.GetStringAsync(url);
    return ProcessData(data);
}

Conclusion

This 20-line approach to MCP servers represents a paradigm shift in how we build AI tool integrations. By leveraging .NET's modern features - top-level programs, package directives, and attribute-based configuration - we've eliminated the traditional complexity barrier.

The result is a development experience that's:

• Fast: From idea to working server in minutes

• Maintainable: Clear, typed code that's easy to modify

• Powerful: Full access to .NET ecosystem and NuGet packages

• Professional: Production-ready with proper error handling and logging

Whether you're building personal productivity tools or enterprise AI integrations, this pattern provides the perfect balance of simplicity and capability. Start with the 20-line foundation, then grow your server organically as your needs evolve.

The future of AI tool development is here, and it fits in 20 lines of code.

Setup

First, you'll need to add the CsWin32 NuGet package to your project:

<PackageReference Include="Microsoft.Windows.CsWin32" Version="0.3.49-beta" />

Then create a file called NativeMethods.txt in your project root and add these required Win32 APIs:

SetWindowSubclass
DefSubclassProc
GetDpiForWindow
MINMAXINFO

After creating NativeMethods.txt, ensure its build action is set to "C# analyzer additional file":

1. Right-click the file > Properties > Build Action > Select "C# analyzer additional file".

This file tells the CsWin32 source generator which Win32 APIs to generate code for.

The Solution

Here is a helper class that will handle the window size constraints:

public class WindowsSubclass
{
    private const int WM_GETMINMAXINFO = 0x0024;
    private readonly Windows.Win32.UI.Shell.SUBCLASSPROC _subclassProc;
    private readonly Windows.Win32.Foundation.HWND _hwnd;
    private readonly uint _id;

    /// <summary>
    /// Initializes a new instance of the <see cref="WindowMinSizeSubclass"/> class.
    /// </summary>
    /// <param name="hwnd">The handle to the window.</param>
    /// <param name="id">The subclass ID, could be any number.</param>
    /// <param name="minSize">The minimum size of the window.</param>
    /// <exception cref="InvalidOperationException">Thrown when setting the window subclass fails.</exception>
    public WindowsSubclass(IntPtr hwnd, uint id, Size minSize)
    {
        _hwnd = (Windows.Win32.Foundation.HWND)hwnd;
        _id = id;
        MinSize = minSize;
        _subclassProc = new Windows.Win32.UI.Shell.SUBCLASSPROC(WindowSubclassProc);

        var result = Windows.Win32.PInvoke.SetWindowSubclass(_hwnd, _subclassProc, _id, 0);
        if (result.Value == 0)
        {
            throw new InvalidOperationException("Failed to set window subclass");
        }
    }

    public Size MinSize { get; }

    private Windows.Win32.Foundation.LRESULT WindowSubclassProc(Windows.Win32.Foundation.HWND hWnd, uint uMsg,
        Windows.Win32.Foundation.WPARAM wParam, Windows.Win32.Foundation.LPARAM lParam,
        nuint uIdSubclass, nuint dwRefData)
    {
        switch (uMsg)
        {
            case WM_GETMINMAXINFO:
                // Windows sends this message to query size constraints. 
                // ptMinTrackSize defines the smallest draggable window size.
                // We adjust it based on DPI scaling.
                var dpi = Windows.Win32.PInvoke.GetDpiForWindow(hWnd);
                float scalingFactor = (float)dpi / 96;
                var minMaxInfo = Marshal.PtrToStructure<Windows.Win32.UI.WindowsAndMessaging.MINMAXINFO>(lParam);
                minMaxInfo.ptMinTrackSize.X = (int)(MinSize.Width * scalingFactor);
                minMaxInfo.ptMinTrackSize.Y = (int)(MinSize.Height * scalingFactor);
                Marshal.StructureToPtr(minMaxInfo, lParam, true);
                return new Windows.Win32.Foundation.LRESULT(0);            
        }
        return Windows.Win32.PInvoke.DefSubclassProc(hWnd, uMsg, wParam, lParam);
    }
}

How to Use It

To use this in your WinUI 3 window, add this code to your window's constructor:

public MainWindow()
{
    this.InitializeComponent();

    var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
    _ = new WindowsSubclass(hwnd, 69, new Size(500, 300)); // Sets minimum size to 500x300
}

How It Works

The solution works by intercepting the WM_GETMINMAXINFO Windows Message, which Windows sends to a window when it needs to know its size constraints. We use window subclassing to add our own procedure that handles this message.

Key points about the implementation:

1. CsWin32 generates strongly-typed wrappers for the Win32 APIs we specified in NativeMethods.txt

2. The class keeps a reference to the subclass procedure delegate to prevent it from being garbage collected

3. It properly handles DPI scaling to ensure consistent sizing across different display scales

4. All other window messages are passed through to the default handler

5. The subclass is automatically cleaned up when the window is destroyed

Important Notes

• The minimum size is specified in logical pixels and will be properly scaled based on the display's DPI

• The window subclassing is automatically cleaned up when the window is destroyed

• This solution works only for desktop applications, not for UWP or other platforms

• Make sure NativeMethods.txt is included in your project and the file properties are set to "C# analyzer additional file"

Troubleshooting

Some problems you could encounter and how to fix them:

• Subclass ID Conflicts: Ensure unique IDs if subclassing multiple windows.

• DPI Scaling Issues: Verify GetDpiForWindow returns valid values (e.g., not zero).

• Garbage Collection: The SUBCLASSPROC delegate must remain referenced (already handled in the helper class).

Now you can set minimum window sizes in your WinUI 3 desktop applications while maintaining proper Windows integration and DPI awareness.

The Problem

My application Docker is based on a custom Docker image that comes with Python pre-installed at /app/python. This is a requirement I cannot change, and Python must be available at this specific location for the application to work.

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM myregistry.azurecr.io/base-python:latest AS base
USER $APP_UID
ENV Python3_ROOT_DIR="/app/python"
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

When trying to debug the application from Visual Studio using Fast Mode (default for Debug configuration), I ran into a problem.

The issue was that Fast Mode was mounting my application files to /app (the WORKDIR), which effectively overlaid and hid the Python installation that was already there. As a result, Python became unavailable and the application couldn't work properly.

Issue 1: Fixing the Mount Points

After some research, I found that Visual Studio's mounting behavior can be controlled through the project file. The solution was to configure Fast Mode to mount files into a different directory:

<PropertyGroup>
    <DockerDebuggeeWorkingDirectory>/app/dotnet</DockerDebuggeeWorkingDirectory> 
    <DockerFastModeProjectMountDirectory>/app/dotnet</DockerFastModeProjectMountDirectory>
</PropertyGroup>

This configuration tells Fast Mode to:

1. Mount application files to app/dotnet instead of /app

2. Set the working directory for the debugger

3. Leave the Python installation at /app/python intact and accessible

Issue 2: Windows PDBs Not Working

After fixing the mount point, I encountered another issue. When trying to hit breakpoints, the debugger was complaining about symbol files:

WARNING: Could not load symbols for 'MyCompany.Service.dll'. 
'/src/build/bin/.../MyCompany.Service.pdb' is a Windows PDB. 
These are not supported by the cross-platform .NET Core debugger.

The problem comes from the difference between debugging environments. While developing on Windows, Visual Studio by default generates Windows PDB files (Program Database) which contain debugging information. However, when debugging in a Linux container with the cross-platform .NET debugger, these Windows-specific PDBs aren't supported.

Microsoft introduced Portable PDBs exactly for this cross-platform scenario - they contain the same debugging information but in a format that works across different operating systems. The solution was to tell the compiler to generate portable PDBs instead of Windows ones:

<PropertyGroup>
    <DebugType>portable</DebugType>
</PropertyGroup>

After this change and rebuilding the application, the debugger successfully loaded the symbols and I could debug my application running in the container.

References

• Visual Studio Container Tools Build Properties

• Debug Type Property (C#)

That's it. Both issues fixed and debugging now works as expected.

The Challenge

The core issue stems from different operating systems using different line-ending conventions:

• Windows uses CRLF (Carriage Return + Line Feed, \r\n)

• Linux systems, including WSL, use LF (Line Feed, \n)

When working with Git repositories created in Windows and accessed through WSL, these differences can cause Git to flag files as modified even when no actual content changes have occurred. This happens because Git may interpret the line-ending differences as file modifications.

Understanding the Environment

A key insight is that WSL Git and Windows Git maintain separate global environments, which might not be immediately obvious to developers new to this setup. This means configurations need to be managed separately for each environment.

Solutions

To ensure consistent line-ending handling, you have two main configuration options:

1. Windows Configuration

    git config --global core.autocrlf true
   

   This setting converts line endings to CRLF during checkout. Note that this is often the default setting in Windows Git installations.

2. WSL Configuration

    git config --global core.autocrlf input
   

   This setting prevents line ending conversion in the Linux environment, accepting whatever line endings are provided.

Understanding core.autocrlf

The core.autocrlf setting controls how Git handles line ending conversions:

• When set to true, Git converts LF to CRLF in your working directory while maintaining LF in the repository

• When set to input, Git performs no output conversion, accepting files as-is

Conclusion

Understanding and properly configuring line-ending behavior is crucial when sharing Git repositories between Windows and WSL environments. With the appropriate settings, you can prevent unnecessary file modifications and maintain a smooth development workflow across both platforms.

Just look at this amazing growth of websites using the htmx over the year.

Unfortunately, currently, Visual Studio's support for htmx is limited. While there are some NuGet packages providing tag helpers, developers lack crucial features like code completion and IntelliSense for HTMX. This gap in tooling can lead to inefficiencies, with developers constantly switching between Visual Studio and HTMX documentation.

Because I work with dotnet and htmx a lot, I decided to create a Visual Studio extension to fill the gap. I had no prior experience building extensions, so here are my discoveries and frustrations along the way. Despite the challenges, I managed to complete it, and now it's available in the VS marketplace.

This is what we want to achieve.

Building the HTMX Code Completion Extension

To build a Visual Studio extension, you need to install specific extension development packages through the Visual Studio Installer. It's important to note that Visual Studio extensions are built on the .NET framework. And Visual Studio works only on Windows now - they discontinued it literally a couple of days ago.

So the first thing we need is to install the required tooling. If you have Visual Studio, you have Visual Studio Installer. This is the app to install VSIX tooling

Additionally, it's recommended to install Extensibility Essentials. I didn't use it, but it looks like it has a ton of useful pieces. KnownMonikers for example is something I need but found on the web - it shows what kind of icons are available in VS.

Extension Architecture

A VSIX package is a .vsix archive that contains one or more Visual Studio extensions, together with the metadata Visual Studio uses to classify and install the extensions. The first thing in the extension is a manifest, VSIX manifest contains information about the extension to be installed.

Any VSIX extension can provide several exported Managed Extensibility Framework (MEF) classes. MEF is used to export classes and interfaces that Visual Studio uses to integrate new functionality. Recent versions of Visual Studio (2019 and 2022) have introduced significant improvements in code completion and IntelliSense features, particularly through asynchronous interfaces.

Here is an example of an exported source provider.

[Export(typeof(IAsyncQuickInfoSourceProvider))]
[Name("htmx tooltip quickInfo source")]
[ContentType("razor")]
internal class HtmxQuickInfoSourceProvider : IAsyncQuickInfoSourceProvider
{
    [Import]
    internal ITextStructureNavigatorSelectorService NavigatorService { get; set; }

    public IAsyncQuickInfoSource TryCreateQuickInfoSource(ITextBuffer textBuffer)
    {            
        return new HtmxQuickInfoSource(NavigatorService, textBuffer);
    }
}

This code exports our HtmxQuickInfoSourceProvider as an IAsyncQuickInfoSourceProvider, specifically for HTML content types. The [Import] attribute allows MEF to inject the required ITextStructureNavigatorSelectorService.

Key Components of the Extension

1. Completion Source: Implements IAsyncCompletionSource interface to provide HTMX-specific code completion.

2. Provider Interface: Exported as a MEF interface, called by Visual Studio under specific conditions (e.g., when an HTML file is opened). We particularly interested in the next providers

   1. IAsyncCompletionSourceProvider: provides instances of IAsyncCompletionSource which provides CompletionItems

   2. IAsyncCompletionCommitManagerProvider: provides instances of IAsyncCompletionCommitManager which provides means to adjust the commit behavior, including which typed characters commit

   3. IAsyncQuickInfoSourceProvider: creates an IAsyncQuickInfoSource specified ITextBuffer.

   4. IIntellisenseControllerProvider: creates IntelliSense controllers for individual ITextView instances.

3. QuickInfo Source: Provides additional information when hovering over HTMX attributes with IAsyncQuickInfoSource.

Overall, the class overview of the extension would look like this:

Code Completion Implementation

The extension implements two completion sources: one for HTMX attributes and another for attribute values. The main challenge was detecting when a user starts typing an HTMX attribute (which always begins with "hx-").

The full completion process looks like this:

• IAsyncCompletionSource - Produces the completion list when needed.

• IAsyncCompletionBroker - Triggers completion and provides the completion session.

• IAsyncCompletionItemManager - Filters and sorts completion items.

• IAsyncCompletionCommitManager - Adjust the commit behavior and perform a completion commit

For attribute code completion we would need to implement two interfaces: IAsyncCompletionSourceProvider and IAsyncCompletionSource

To handle completion Visual Studio sends an event when the completion trigger is fired, which should be handled by IAsyncCompletionSource. In it, we should implement three methods:

internal class HtmxCompletionSource : IAsyncCompletionSource
{
    public Task<CompletionContext> GetCompletionContextAsync(IAsyncCompletionSession session, CompletionTrigger trigger, SnapshotPoint triggerLocation, SnapshotSpan applicableToSpan, CancellationToken cancellationToken)
    {
        /// Provide completion context which has a list of items to show
    }

    public Task<object> GetDescriptionAsync(IAsyncCompletionSession session, CompletionItem item, CancellationToken token)
    {
        /// Provide description for currently selected item
    }

    public CompletionStartData InitializeCompletion(CompletionTrigger trigger, SnapshotPoint triggerLocation, CancellationToken cancellationToken)
    {
       /// Perform checks if completion needs to be shown
    }

Method InitializeCompletion provides the trigger and a snapshot, which is essentially the location in the text view where the cursor was at the moment the trigger occurred.

This allows us to evaluate the context around the cursor to decide whether to trigger completion.

public CompletionStartData InitializeCompletion(CompletionTrigger trigger, SnapshotPoint triggerLocation, CancellationToken cancellationToken)
{
    Output.WriteInfo($"HtmxCompletionSource:InitializeCompletion: triggered by {trigger.Reason}:{trigger.Character}.");
    if (!triggerLocation.IsInsideHtmlTag())
    {
        return CompletionStartData.DoesNotParticipateInCompletion;
    }

    var tokenSpan = triggerLocation.GetContainingToken();
    var currentToken = tokenSpan.GetText();
    Output.WriteInfo($"HtmxCompletionSource:InitializeCompletion: {currentToken}");

    if (currentToken.StartsWith("hx", StringComparison.OrdinalIgnoreCase) ||
        currentToken.StartsWith("hx-", StringComparison.OrdinalIgnoreCase) ||
        (trigger.Character == '-' && tokenSpan.GetPreviousToken().GetText().Equals("hx", StringComparison.OrdinalIgnoreCase)))
    {
        return new CompletionStartData(CompletionParticipation.ProvidesItems, tokenSpan);
    }

    return CompletionStartData.DoesNotParticipateInCompletion;
}

First, we check if our cursor is inside an HTML tag. Then, we check if it is inside an htmx attribute. These checks are implemented as extension methods.

public static bool IsInsideHtmlTag(this SnapshotPoint point)
{
    var snapshot = point.Snapshot;
    var position = point.Position;

    // Check if we're already at the start of the snapshot
    if (position == 0)
        return false;

    int openBracketPos = -1;

    // Look backwards for opening bracket
    for (int i = position - 1; i >= 0; i--)
    {
        if (snapshot[i] == '>')
            return false; // Found closing bracket first, so we're not inside a tag
        if (snapshot[i] == '<')
        {
            openBracketPos = i;
            break;
        }
    }

    return openBracketPos != -1;
}

A Snapshot is an ITextSnapshot, which provides read access to an unchangeable snapshot of an ITextBuffer containing a sequence of Unicode characters. The algorithm is simple — we move left until we confirm that we are inside an HTML tag.

public static SnapshotSpan GetContainingToken(this SnapshotPoint point)
{
    var line = point.GetContainingLine();

    var linePosition = point.Position;
    var snapshot = line.Snapshot;

    int tokenStart = linePosition;
    while (tokenStart > line.Start.Position && IsValidTokenChar(snapshot[tokenStart - 1]))
    {
        tokenStart--;
    }

    int tokenEnd = linePosition;
    while (tokenEnd < line.End.Position && IsValidTokenChar(snapshot[tokenEnd]))
    {
        tokenEnd++;
    }

    return new SnapshotSpan(line.Snapshot, tokenStart, tokenEnd - tokenStart);
}

A line here is ITextSnapshotLine - an immutable information about a line of text from an ITextSnapshot. We do not need to go outside the line, because attributes could not be beyond the single line. The algorithm is pretty much the same, but we go to both sides of the line to extract the entire attribute name.

If we successfully confirm that the cursor is inside an attribute, the CompletionContext with a list of items will be requested.

Providing a List of Completion Items

List of completion items provided from CompletionContext

public Task<CompletionContext> GetCompletionContextAsync(IAsyncCompletionSession session, CompletionTrigger trigger, SnapshotPoint triggerLocation, SnapshotSpan applicableToSpan, CancellationToken cancellationToken)
{
    var arr = ToolTipsProvider.Instance.Keywords.Select(ConvertToItem).ToImmutableArray();

    Output.WriteInfo($"HtmxCompletionSource:GetCompletionContextAsync: got a request for a context. Returning {arr.Length} items.");

    return Task.FromResult(new CompletionContext(arr));
}

The item itself has several parameters, and to be honest, I don't know what half of them do. However, I do know that we have text, insertText which will be inserted, and icon which adds a small icon to the left of the completion item.

private static ImageElement CompletionItemIcon = new ImageElement(KnownMonikers.HTMLEndTag.ToImageId(), "htmx");

private CompletionItem ConvertToItem(string text)
{
    string insertText = text == "hx-on" ? $"hx-on:" : $"{text}=\"\"";
    return new CompletionItem(
                    text,
                    insertText: insertText,
                    sortText: text,
                    filterText: text,
                    automationText: text,
                    source: this,
                    filters: ImmutableArray<CompletionFilter>.Empty,
                    icon: CompletionItemIcon,
                    suffix: default,
                    attributeIcons: ImmutableArray<ImageElement>.Empty);
}

Here is a screenshot to better understand what each part does:

Customizing Completion Behavior

By default, the completion feature places the cursor after the string. So, when hx-get is completed and hx-get="" is inserted, the cursor is set at the end. However, this isn't very convenient. We want the cursor inside the quotation marks, like this: hx-get="|".

This can be achieved by using IAsyncCompletionCommitManager.

 internal class HtmxCompletionCommitManager : IAsyncCompletionCommitManager
 {
     // ...
     public CommitResult TryCommit(IAsyncCompletionSession session, ITextBuffer buffer, CompletionItem item, char typedChar, CancellationToken token)
     {
         // Check if this is one of your custom completions
         if (item.InsertText.StartsWith("hx") && item.InsertText.EndsWith("=\"\""))
         {
             var span = session.ApplicableToSpan;

             // Commit the completion
             using (var edit = buffer.CreateEdit())
             {
                 edit.Replace(span.GetSpan(buffer.CurrentSnapshot), item.InsertText);
                 edit.Apply();
             }

             // Move the caret inside the quotes
             var newPosition = span.GetStartPoint(buffer.CurrentSnapshot).Position + item.InsertText.Length - 1;
             session.TextView.Caret.MoveTo(new SnapshotPoint(buffer.CurrentSnapshot, newPosition));

             Output.WriteInfo("HtmxCompletionCommitManager:TryCommit: committed completion.");
             return CommitResult.Handled;
         }

         return CommitResult.Unhandled;
     }
 }

The implementation here is straightforward. If we insert an hx- attribute, we move the caret inside the quotation marks.

Providing Selected Item Description

Method GetDescriptionAsync is responsible for obtaining an object to be rendered as a popup window with a description.

This popup window is different from the one rendered by IntelliSense. I believe It is intended to show less information, like text-only help. However, due to convenience, I implemented a single ContainerElement for both cases.

public Task<object> GetDescriptionAsync(IAsyncCompletionSession session, CompletionItem item, CancellationToken token)
{
    if (ToolTipsProvider.Instance.TryGetValue(item.DisplayText, out var element))
    {
        // add some spacing between text paragraphs (should really cache that as well)
        var elements = element.Elements.ToList();
        var newElements = new object[elements.Count * 2 - 1];
        for (int i = 0; i < elements.Count; i++)
        {
            newElements[i * 2] = elements[i];
            if (i < elements.Count - 1)
            {
                newElements[i * 2 + 1] = new ClassifiedTextElement(new ClassifiedTextRun(PredefinedClassificationTypeNames.WhiteSpace, " "));
            }
        }
        element = new ContainerElement(element.Style | ContainerElementStyle.Wrapped, newElements);
        return Task.FromResult((object)element);
    }

    return Task.FromResult<object>(null);
}

You can see that I had to add an empty line between paragraphs in the popup window because the renderer ignores ContainerElementStyle.VerticalPadding. Also link element is not supported in the code-completion window.

I will explore how to build ContainerElement later, as I initially built it for IntelliSense.

Source Provider

Interface IAsyncCompletionSourceProvider is responsible for providing the completion source for code completion. This is a MEF component and should be exported with the [ContentType] and [Name] attributes, and optionally the [TextViewRoles] attribute.

The completion feature will request data from all exported IAsyncCompletionSources whose ContentType matches the content type of any buffer at the completion's trigger location.

These content types are a bit tricky, so I started with [ContentType("html")] and [ContentType("razor")] and was very surprised that they do not work for .html files. I checked all available documentation and did not find out why. The problem is that in VS2022, ContentType("html-delegation") is used. You will not find this information in the documentation.

To figure this out, I was forced to set [ContentType("text")], which is the basic type for all text files, and then catch textView.TextBuffer.ContentType in the GetOrCreate method.

The final list of content types becomes quite extensive.

[Export(typeof(IAsyncCompletionSourceProvider))]
[Name("htmx completion source")]
[ContentType("html")]
[ContentType("htmlx")]
[ContentType("html-delegation")] // VS 2022
[ContentType("razor")]
[ContentType("LegacyRazorCSharp")] // VS 2022
internal class HtmxCompletionSourceProvider : IAsyncCompletionSourceProvider
{
    private readonly Lazy<HtmxCompletionSource> Source = new Lazy<HtmxCompletionSource>(() => new HtmxCompletionSource());

    /// <summary>
    /// Gets or creates an instance of <see cref="HtmxCompletionSource"/>.
    /// </summary>
    /// <param name="textView">The text view for which the completion source is requested.</param>
    /// <returns>An instance of <see cref="HtmxCompletionSource"/>.</returns>
    public IAsyncCompletionSource GetOrCreate(ITextView textView)
    {
        Output.WriteInfo("HtmxCompletionSourceProvider:GetOrCreate: got a request for a source.");
        return Source.Value;
    }
}

Also, notice that I use Lazy here to save memory and avoid creating anything unless it's requested. As I understand it, the lifecycle provider is created once, but GetOrCreate could be requested for each completion.

With our code completion feature in place, let's turn our attention to another critical aspect of developer assistance: IntelliSense. This feature works hand-in-hand with code completion to provide a comprehensive development experience.

IntelliSense Implementation

The IntelliSense feature displays additional information when hovering over an HTMX attribute. It checks if the attribute is within an HTML element and if it's an HTMX attribute before displaying the corresponding description.

The info popup itself provided through IAsyncQuickInfoSource

internal class HtmxQuickInfoSource : IAsyncQuickInfoSource
{
    public async Task<QuickInfoItem> GetQuickInfoItemAsync(IAsyncQuickInfoSession session, CancellationToken cancellationToken)
    {
        var (containerElement, applicableToSpan) = await BuildQuickInfoElementsAsync(session, cancellationToken);

        if (containerElement != null && applicableToSpan != null)
        {
            return new QuickInfoItem(applicableToSpan, containerElement);
        }

        return null;
    }

    // ... BuildQuickInfoElementsAsync
}

Building Container Element

A ContainerElement class represents a container of one or more elements for display in an IToolTipPresenter. It can contain other containers or ClassifiedTextRun elements, which represent parts of the text with applied styles.

Here is an example of how a typical tooltip is built. We have a ContainerElement with ClassifiedTextRun elements inside, each with different types.

This tooltip is created by parsing a markdown file into a set of containers. The code is straightforward, and if you want to check it out, feel free to look at the GitHub repo.

The link container is built a bit differently. We have a couple of factory methods in ClassifiedTextElement to create plain text and hyperlinks. So we could use it here:

public static ContainerElement CreateRichContent(string description, string link)
{
    var converter = new MarkdownConverter();

    var elements = converter.Convert(description);
    elements.Add(new ContainerElement(ContainerElementStyle.Wrapped,
        CreateHyperlink(link)));
    return new ContainerElement(ContainerElementStyle.Stacked | ContainerElementStyle.VerticalPadding,
        elements.ToArray());
}

private static ClassifiedTextElement CreateHyperlink(string url)
{
    return ClassifiedTextElement.CreateHyperlink("HTMX Reference", "Click here to see more details in official documentation", () =>
    {
        System.Diagnostics.Process.Start(url);
    });
}

Inside ClassifiedTextElement.CreateHyperlink is a simple text element with a navigation action set. This action will launch the default app to open the URL and navigate there.

return new ClassifiedTextElement(new ClassifiedTextRun("text", text, navigationAction, tooltip));

IntelliSense Controller

Interface IAsyncQuickInfoSource itself would not show quick info. To present a quick info tooltip we need to implement IIntellisenseController and handle the mouse event by ourselves.

internal class HtmxQuickInfoController : IIntellisenseController
{
    // ...
    public HtmxQuickInfoController(ITextView textView, IList<ITextBuffer> subjectBuffers, IAsyncQuickInfoBroker broker)
    {
        _textView = textView;
        _subjectBuffers = subjectBuffers;
        _broker = broker;

        _textView.MouseHover += this.OnTextViewMouseHover;
    }

    private async void OnTextViewMouseHover(object sender, MouseHoverEventArgs e)
    {
        // Debounce (not sure if needed)
        if ((DateTime.Now - _lastCheckTime).TotalMilliseconds < DebounceMs)
        {
            return;
        }

        _lastCheckTime = DateTime.Now;

        // find the mouse position by mapping down to the subject buffer
        var point = _textView.BufferGraph.MapDownToFirstMatch(new SnapshotPoint(_textView.TextSnapshot, e.Position),
                PointTrackingMode.Positive,
                snapshot => _subjectBuffers.Contains(snapshot.TextBuffer),
                PositionAffinity.Predecessor);

        if (point != null)
        {
            ITrackingPoint triggerPoint = point.Value.Snapshot.CreateTrackingPoint(point.Value.Position,
            PointTrackingMode.Positive);

            if (!_broker.IsQuickInfoActive(_textView))
            {
                _ = await _broker.
                    TriggerQuickInfoAsync(_textView, triggerPoint, QuickInfoSessionOptions.TrackMouse);
            }
        }
    }
}

The controller handles mouse movement and then triggers quick info through the broker. The appropriate quick info is shown based on whichever source returns the first quick info.

You might also notice a debounce logic there. I'm not entirely sure it's needed, but it seems to improve the experience, so I included it.

Source Provider

Obviously, we need to export our IIntellisenseController and IAsyncQuickInfoSource. This is done through source providers, similar to how completion sources work. The only difference is that they call TryCreate once, so there's no need for lazy initialization.

    [Export(typeof(IAsyncQuickInfoSourceProvider))]
    [Name("htmx tooltip quickInfo source")]
    [ContentType("html")]
    [ContentType("htmlx")]
    [ContentType("html-delegation")] // VS 2022
    [ContentType("razor")]
    [ContentType("LegacyRazorCSharp")] // VS 2022
    internal class HtmxQuickInfoSourceProvider : IAsyncQuickInfoSourceProvider
    {
        [Import]
        internal ITextStructureNavigatorSelectorService NavigatorService { get; set; }

        public IAsyncQuickInfoSource TryCreateQuickInfoSource(ITextBuffer textBuffer)
        {            
            Output.WriteInfo("HtmxQuickInfoSourceProvider:TryCreateQuickInfoSource: got a request for a source.");
            return new HtmxQuickInfoSource(NavigatorService, textBuffer);
        }
    }

    [Export(typeof(IIntellisenseControllerProvider))]
    [Name("htmx tooltip quickinfo controller")]
    [ContentType("html")]
    [ContentType("htmlx")]
    [ContentType("html-delegation")] // VS 2022
    [ContentType("razor")]
    [ContentType("LegacyRazorCSharp")] // VS 2022
    internal class HtmxQuickInfoControllerProvider : IIntellisenseControllerProvider
    {
        [Import]
        internal IAsyncQuickInfoBroker QuickInfoBroker { get; set; }

        public IIntellisenseController TryCreateIntellisenseController(ITextView textView, IList<ITextBuffer> subjectBuffers)
        {
            Output.WriteInfo("HtmxQuickInfoControllerProvider:TryCreateIntellisenseController: got a request for a controller.");

            return new HtmxQuickInfoController(textView, subjectBuffers, QuickInfoBroker);
        }
}

Cross-Version Support Challenges

Initially, my goal was to support both Visual Studio 2019 and 2022. However, due to architectural differences (x86 vs. x64) and API changes, the focus shifted to Visual Studio 2022 only.

When I set manifest, I could add different install targets, based on the Visual Studio version and architecture.

Targeting multiple versions of Visual Studio requires setting up different targets, using different SDKs, and sharing projects. There is a comprehensive guide available that I might explore later.

Packaging and Publishing

The extension is packaged as a .vsix file and published on the Visual Studio Marketplace. This process is very simple. When you build as release, Visual Studio packs your .vsix file. I recommend installing it locally first to ensure it works correctly.

The next step is to create an account on Visual Studio Marketplace and upload the .vsix file.

Most of the information will be taken from the manifest, but you can write a README and select categories and tags.

The marketplace also provides useful analytics, so you can monitor the growth of your user base.

Lessons Learned and Future Plans

Writing an extension was a very rewarding experience. I got to explore how the internals of Visual Studio work, reviewed documentation and examples and significantly improved my htmx developer experience.

Here are some key lessons I want to share:

1. API Documentation Gap: Current documentation, especially the manuals and examples, focuses on older methods, making it difficult to work with newer APIs.

2. Community Resources: Existing GitHub projects and issues often provide valuable insights into new APIs, so study them thoroughly.

3. Version Focus: Concentrating on a single Visual Studio version simplifies development. If I ever need to support the 2019 version, I would approach it with a fresh perspective.

4. Experimentation: Understanding the completion subsystem required hands-on experimentation. The debugger works great, so use it to explore all the details.

In the future, I might add some improvements to the extension:

1. Syntax highlighting to make hx-attributes more noticeable

2. More completion options for complex attributes like hx-on: and others

3. Additional features based on user feedback

Useful Links

• AsyncCompletion source code (with examples)

• AsyncCompletion sample project

• QuickInfo sample project

• Microsoft.VisualStudio.Language.Intellisense.AsyncCompletion documentation

• Microsoft.VisualStudio.Language.Intellisense.IIntellisenseController documentation

• htmx-pal source code

Conclusion

The htmx-pal extension enhances Visual Studio's capabilities for HTMX development, offering code completion and quick info features. I spent around 12 hours building and publishing it, and I'm extremely delighted with how smooth the experience was.

There were moments when I almost gave up, such as when adding hx-... to the default code completion. However, these issues don't significantly affect the developer experience, so it's okay.

The most important part is that I now have a better way to write htmx apps, and so do you.

The extension is open source, and the code is available on GitHub. The extension itself is published on the marketplace. If you find it useful, I would be grateful if you rate it.

We will explore built-in validation options, how we can adapt ASPNET's built-in validation to work efficiently with htmx, or how we can skip it completely and use HTML5 for validation.

To understand this article, you should already be familiar with Razor Pages and htmx. If not, I recommend reading a more introductory article in the series.

History of validation in ASPNET

In ASP-NET applications, validation has been built right into the framework using Data Annotations and unobtrusive JavaScript since early versions. You can define validation rules in your model classes with attributes like [Required], [StringLength], or [Range]. These rules would be used on both the server and client sides.

For client-side validation, the jquery.validate.unobtrusive library steps in. It applies validation rules using data attributes in the HTML elements. The Razor Pages engine uses tag helpers (like asp-for) to generate input tags with all the necessary attributes.

<!-- generated input with validation for use with jquery.validate.unobtrusive -->
<label for="FirstName">First Name</label>
<input type="text" data-val="true" 
    data-val-length="First Name cannot be longer than 50 characters" 
    data-val-length-max="50" 
    data-val-required="First Name is required" 
    id="FirstName" 
    maxlength="50" 
    name="FirstName" value="">

The jquery.validate.unobtrusive library was introduced with the ASP.NET MVC 3 release on January 13, 2011. In ASP.NET MVC 2, released in March 2010, server-side validation was more common. While client-side validation was possible, it required more manual setup. Developers had to use the jQuery Validation plugin and write custom JavaScript code for the validation logic.

For server-side validation, user-submitted data must follow certain rules before it can be processed. The rules are defined using Data Annotations in model classes. During form submission, the model binding process maps the form data to the model properties and runs the validation framework.

public record UserRegistrationForm
{
    // annotatied property
    [Required(ErrorMessage = "First Name is required")]
    [StringLength(50, ErrorMessage = "First Name cannot be longer than 50 characters")]
    [Display(Name = "First Name")]
    public string FirstName { get; init; }
}

If any data doesn't meet the defined rules, the framework sets the ModelState to invalidate and record the validation errors. This information could be used to build a response page and display server-side validation errors on the form.

Project set-up

To test different types of validation, I created a simple Razor Pages project using pico CSS as the default design library. I did not use Bootstrap or any third-party JavaScript libraries except for jquery, jquery.validation, and htmx.

Each case has a separate page with the same partial _FormContent for the form's internals. We can reuse the same partial and almost the same page models for any type of validation: htmx, non-htmx, HTML5, and jquery.validation.

@page
@model Xakpc.RazorHtmx.Validation.Pages.RazorPageFormModel

@{
    ViewData["Title"] = "User Registration";
}

<hgroup>
    <h2>User Registration - Unobtrusive</h2>
    <p>Regular POST of the form with <mark>jquery.validate.unobtrusive</mark> validation</p>
</hgroup>

<article>
    <form method="post">
        <partial name="_FormContent" model="@Model.UserRegistration"/>
    </form>
</article>

@section Scripts {
    <partial name="_ValidationScriptsPartial" />
}

The page model would be also almost the same for each validation: a bound property and a single OnPost handler.

    public class RazorPageFormModel : PageModel
    {
        [BindProperty]
        public UserRegistrationForm UserRegistration { get; set; }

        public void OnGet()
        {
        }

        public IActionResult OnPost()
        {
            if (User.PhoneNumber.Length < 4) {
                ModelState.AddModelError("PhoneNumber", "Phone format is wrong");   
            }

            if (!ModelState.IsValid)
            {
                return Page();
            }

            // Store the user data in TempData
            TempData["User"] = JsonSerializer.Serialize(UserRegistration);
            return RedirectToPage("Success");
        }
    }

Fancy Validation States

Pico CSS supports some fancy validation states using the aria-invalid attribute. All pages include custom code to set this attribute during server-side validation and also on the client side for HTML5 validation, as it does not do this by default.

Managing validation state on the server side is done using TagHelpers, which are convenient and powerful tools for generating HTML. I use a set of tag helpers in my Razor Pages projects, both with and without htmx.

Specifically, the ValidationStateInputTagHelper is applied to all input tags where the asp-for attribute is present. It adds the aria-invalid attribute based on the value and error state.

[HtmlTargetElement("input", Attributes = "asp-for")]
[HtmlTargetElement("select", Attributes = "asp-for")]
public class ValidationStateInputTagHelper : TagHelper
{
    [HtmlAttributeNotBound]
    [ViewContext]
    public ViewContext ViewContext { get; set; }

    [HtmlAttributeName("asp-for")]
    public ModelExpression For { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        var model = For.Model;

        // Check if the field has a value
        bool hasValue = model != null && !string.IsNullOrEmpty(model.ToString());

        // Check if there are any validation errors for this field
        var modelState = ViewContext;
        bool hasError = modelState != null &&
                        modelState.ViewData.ModelState.TryGetValue(For.Name, out var entry) &&
                        entry.Errors.Count > 0;

        // Set the aria-invalid attribute based on the value and error
        if (hasValue)
        {
            output.Attributes.SetAttribute("aria-invalid", hasError ? "true" : "false");
        }
    }
}

The full code for this article is available on GitHub, feel free to explore it.

Razor Pages "default" Validation

As I mentioned earlier, In ASP.NET web applications, including Razor Pages, default validation is built upon validation attributes and the jquery.validate.unobtrusive library. This setup ensures seamless integration of client-side and server-side validation.

When data is submitted via a POST request, the validation process kicks in before the data reaches the OnPost handler. This means that any data entered by the user is checked against the specified validation rules defined by attributes such as [Required], [StringLength], [Range], and custom validation attributes.

Client-side

For example, if we define a typical input field with label and span for validation message:

<label asp-for="FirstName"></label>
<input asp-for="FirstName"/>
<span asp-validation-for="FirstName" class="text-danger"></span>

And we have property with attributes like that

[Required(ErrorMessage = "First Name is required")]
[StringLength(50, ErrorMessage = "First Name cannot be longer than 50 characters")]
[Display(Name = "First Name")]
public string FirstName { get; set; }

It would be translated into the next code:

<label for="FirstName">First Name</label>
<input type="text" 
    data-val="true" 
    data-val-length="First Name cannot be longer than 50 characters" 
    data-val-length-max="50" data-val-required="First Name is required" 
    id="FirstName" 
    maxlength="50" 
    name="FirstName" value="">
<span class="text-danger field-validation-valid" data-valmsg-for="FirstName" data-valmsg-replace="true"></span>

The rendered page transfers all model's data contract validations to HTML and utilizing data-* attributes to perform validation on change and submission. When something is wrong, an error message is injected into the span and aria-invalid attribute is set automatically.

Server-side Validation

By default, in Razor Pages, submitting a form triggers a POST request that results in a full page reload. In the case of POST in Razor Pages, we usually add an OnPost handler that might look like this:

 public IActionResult OnPost()
 {
    if (!ModelState.IsValid)
    {
        return Page();
    }

    // Store the user data in TempData
    TempData["User"] = JsonSerializer.Serialize(UserRegistration);
    return RedirectToPage("Success", UserRegistration);
 }

ModelState is a ModelStateDictionary. After the POST request is accepted but before the OnPost handler called, the framework would perform validation and fill it with validation results:

If there are no validation errors, ModelState.IsValidwill be true, and we will continue processing with a redirect to the success page.

But if we introduce any validation error

if (UserRegistration.PhoneNumber.Length < 4) {
    ModelState.AddModelError("User.PhoneNumber", "Phone format is wrong");   
}

We will have this information in the ModelState for the related property.

ModelState.IsValid will be false, and Razor Page will render the page with this error information put in place of the related tag helper.

Since we have a [BindProperty] attribute on the User model, returning the Page() will populate this model with data from the request. Therefore, all the data we input (except passwords) will be automatically filled back in.

<!-- template tag helper -->
<label asp-for="PhoneNumber"></label>
<input asp-for="PhoneNumber"/>
<span asp-validation-for="PhoneNumber" class="text-danger"></span>

<!-- rendered tag -->
<span class="text-danger field-validation-error" 
    data-valmsg-for="PhoneNumber" 
    data-valmsg-replace="true">Phone format is wrong</span>

This is how default Razor Pages validation works, and ASP.NET validation in general. If you want you could explore it in detail in official Microsoft documentation.

But how could we adapt this validation to use it with htmx?

Unobtrusive Validation with htmx

Htmx integrates with the HTML5 Validation API and will not issue a request for a form if a validatable input is invalid. However, since we do not use HTML5 when we use jquery.validate.unobtrusive we need to hook into the submit process to prevent submission if any client-side validation error is found.

Server-side we would need to render and return Partial - our server-side validated form instead of the whole page.

Client-side

First, let's set up the form as a separate partial _Form . We would require to get the user model and ViewData with some additional properties like handler route or trigger.

@model Xakpc.RazorHtmx.Validation.UserRegistrationForm

@{
    var handler = (string)ViewData["Handler"];
    var trigger = (ViewData["Trigger"] as string) ?? "submit";
}

<form method="post" hx-post="@handler" hx-swap="outerHtml" hx-trigger="@trigger">
    <partial name="_FormContent" model="@Model" />
</form>

We would use _Form partial like this

@page
@model Xakpc.RazorHtmx.Validation.Pages.UnobtrusiveHtmxModel
@{
    ViewData["Title"] = "User Registration";
    ViewData["Handler"] = Url.Page("UnobtrusiveHtmx");
    ViewData["Trigger"] = "valid-form";
}

...

<article>
    <partial name="_Form" model="Model.UserRegistration" view-data="ViewData" />
</article>

Note ViewData["Trigger"] = "valid-form" that would be rendered as hx-trigger="valid-form". By default, AJAX requests are triggered by the “natural” event of an element. For a form, this is the submit event.

However, this won't work because the submit event is emitted even if there are validation errors. The solution here is to intercept the event and emit our own event if the form is valid.

$(document).ready(function () {
    $('form').on('submit', function (e) {
        var form = $(this);
        if (form.valid()) {
            // Form is valid, allow htmx to handle the submission
            htmx.trigger("form", "valid-form");
            e.preventDefault();                    
            return true;
            } else {
            e.preventDefault();
            return false;
        }
    });
});

When the form is valid the event valid-form would trigger hx-post and submit the form.

Server-side

Server-side validation works the same way in this case, but the way we produce the response changes. Razor Pages are smart enough to handle binding and validation even for AJAX/htmx requests (same thing).

public IActionResult OnPost()
{
    if (UserRegistration.PhoneNumber.Length < 4)
    {
        ModelState.AddModelError("PhoneNumber", "Phone format is wrong");
    }

    if (!ModelState.IsValid)
    {
        Response.StatusCode = 422;
        return Partial("_FormContent", UserRegistration);
    }

    // no need to use temp data to pass user object to another page
    return Partial("_SuccessUser", UserRegistration);
}

Note the return code 422 Unprocessable Entity - it is a smart way to tell the client that the form data has an error and cannot be processed. Unfortunately, htmx would not process requests with such a code - we need to set it up.

$(document).on('htmx:beforeSwap', function (event) {
    var evt = event.originalEvent; // Get the original event details
    if (evt.detail.xhr.status === 422) {
        // Allow 422 responses to swap as we are using this as a signal that
        // a form was submitted with bad data and want to rerender with the errors
        //
        // Set isError to false to avoid error logging in console
        evt.detail.shouldSwap = true;
        evt.detail.isError = false;
    }
});

Unobtrusive validation is great and very powerful, but it requires using jQuery. While this is absolutely fine, it does add some weight to our page: jquery-3.3.2.min.js + jquery.validate.min.js + jquery.validate.unobtrusive.min.js = 112 KB.

Could we omit that?

HTML5 Validation

Now let's remove jquery.validation and jQuery, and disable built-in validation with the setting ViewContext.ClientValidationEnabled = false. With this option disabled, Razor Pages will not convert Data Annotation attributes to HTML attributes.

On the server side, not much will change because it does not rely on client validation.

Client-side

We would lose quite a lot of generated code. Remember the input snippet?

<label asp-for="FirstName"></label>
<input asp-for="FirstName"/>
<span asp-validation-for="FirstName" class="text-danger"></span>

Here is how it would look without client validation enabled - all data attributes and validation messages are gone.

<label for="FirstName">First Name</label>
<input type="text" id="FirstName" maxlength="50" name="FirstName" value="">
<span class="text-danger"></span>

Razor Pages has very limited support for HTML5 validation, and Microsoft has somewhat given up on improving it or replacing jQuery. From what I found, it only supports type and maxlength, not even required, which is a shame because supporting other built-in attributes could easily be done with tag helpers.

Here is an example of a tag helper that adds the required attribute to inputs, as well as a custom data-err-required attribute with an error message.

[HtmlTargetElement("input", Attributes = "asp-for")]
[HtmlTargetElement("textarea", Attributes = "asp-for")]
public class RequiredInputTagHelper : TagHelper
{
    [HtmlAttributeName("asp-for")]
    public ModelExpression For { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        var attribute = For.ModelExplorer.Metadata.ValidatorMetadata.FirstOrDefault(
            attr => attr is RequiredAttribute) as RequiredAttribute;

        if (attribute != null)
        {
            output.Attributes.SetAttribute("required", null);

            if (!string.IsNullOrEmpty(attribute.ErrorMessage))
            {
                output.Attributes.SetAttribute("data-err-required", attribute.ErrorMessage);    
            }
        }
    }
}

I collected some more tag helpers for my personal use.

As you can see, these tag helpers not only set up built-in HTML5 validation but also add a data-err-* attribute that can be used to customize the validation message.

To achieve this, we need to write some JavaScript and attach event listeners to handle the invalid event. Then, we can use setCustomValidity for custom validation messages.

document.addEventListener('DOMContentLoaded', function () {
    const inputs = document.querySelectorAll('input'); 

    inputs.forEach(function (input) {
        // Check if the input has any data-err-* attributes
        if (input.dataset.errRequired ||
            input.dataset.errLength ||
            input.dataset.errMinmax) {

            input.addEventListener('invalid', function (event) {
                const target = event.target;
                let customMessage = '';

                if (target.validity.valueMissing && target.dataset.errRequired) {
                    customMessage = target.dataset.errRequired;
                } else if ((target.validity.tooLong || target.validity.tooShort) && target.dataset.errLength) {
                    customMessage = target.dataset.errLength;
                } else if ((target.validity.rangeUnderflow || target.validity.rangeOverflow) && target.dataset.errMinmax) {
                    customMessage = target.dataset.errMinmax;
                }

                target.setCustomValidity(customMessage);
            });

            input.addEventListener('input', function (event) {
                event.target.setCustomValidity(''); // Clear custom message on input
            });
        }
    });
});

Example of HTML5 validation with a custom message

Server-side Validation

Server-side validation would work the same as in the default way in this case, no changes needed.

In the end, we did lose some client-side features, like the Password and Confirmation Password do not match validation, but this would be handled server-side luckily. The main benefit is that we got rid of heavy jQuery libraries, simplified our HTML, and set a foundation for htmx to take over.

If built-in validation is not enough (many such cases), you can use any validation library you wish. Some are more convenient for use with Razor Pages, while others are less so.

HTML5 Validation with htmx

For me, this is usually a preferred setup for validation. I like to keep it simple, so built-in client validation is enough for me in 90% of cases.

It is not slightly different from the HTML5 and htmx we explored before.

Client-side

We need to make some minor changes on the client side to make it work. Since htmx is integrated with the HTML5 Validation API and will not send a request for a form if a validatable input is invalid, we can remove the custom trigger hx-trigger="valid-form".

The default trigger for the form is submit so no hx-trigger attribute needed.

@page
@model Xakpc.RazorHtmx.Validation.Pages.Html5HtmxModel
@{
    ViewData["Title"] = "User Registration";
    ViewData["Handler"] = Url.Page("Html5Htmx");
    ViewContext.ClientValidationEnabled = false;    
}

<hgroup>
    <h2>User Registration - HTML5 with htmx</h2>
    <p>htmx form submit with <mark>HTML5</mark> validation</p>
</hgroup>

<article>
    <partial name="_Form" model="@Model.UserRegistration" view-data="ViewData"/>
</article>

We also would not need to prevent form submission anymore, but we would need to reattach events on the form after the swap is done (DOM is settled).

document.addEventListener('DOMContentLoaded', function () {
    setupValidation();

    document.body.addEventListener('htmx:afterSettle', function (evt) {
        if (evt.detail.xhr.status === 422) {
            setupValidation();
        }
    });
});

Server-side Validation

Server-side, nothing has changed. The server does not care about how we validate on the client side.

public class Html5HtmxModel : PageModel
{
    [BindProperty]
    public UserRegistrationForm UserRegistration { get; set; }

    public void OnGet()
    {
    }

    public IActionResult OnPost()
    {
        if (UserRegistration.PhoneNumber.Length < 4)
        {
            ModelState.AddModelError("PhoneNumber", "Phone format is wrong");
        }

        if (!ModelState.IsValid)
        {
            Response.StatusCode = 422;
            return Partial("_FormContent", UserRegistration);
        }

        // no need to use temp data to pass user object to another page
        return Partial("_SuccessUser", UserRegistration);
    }
}

As expected we have HTML5 validation with a custom message, submitted by htmx

Hypermedia-Friendly way

One of the somewhat controversial, but clever, ideas behind the hypermedia-friendly way to use htmx is inline scripting: writing your scripts directly within hypermedia, rather than placing them in an external file.

This can be done by using the hx-on attribute and incorporating functions or even inline code snippets to execute our JavaScript. For example, if we need to set the aria-invalid attribute based on the input's validity, instead of using input.addEventListener('input', function (event) {...}, we could use something like this:

<form hx-post="@handler" hx-swap="outerHtml"
      hx-on:focusout="event.target.setAttribute('aria-invalid', 
        event.target.validity.valid && event.target.value !== '' ? 'false' : 'true')">

      ...
</form>

This would set the attribute when we leave focus from any input on the form.

If we need to run a lot of code, we can put it into a function in the partial or, better yet, on the page where the partial is used.

<form hx-post="@handler" hx-swap="outerHtml"/>
     <label asp-for="FirstName"></label>
     <input asp-for="FirstName" hx-on:invalid="setCustomValidity(event.target)" />
     <span asp-validation-for="FirstName" class="text-danger"></span>

     <label asp-for="LastName"></label>
     <input asp-for="LastName" hx-on:invalid="setCustomValidity(event.target)" />
     <span asp-validation-for="LastName" class="text-danger"></span>

     <label asp-for="Email"></label>
     <input asp-for="Email" hx-on:invalid="setCustomValidity(event.target)" />
     <span asp-validation-for="Email" class="text-danger"></span>
     ...
</form>

<script>
    function setCustomValidity(target) {
        let customMessage = '';

        if (target.validity.valueMissing && target.dataset.errRequired) {
            customMessage = target.dataset.errRequired;
        } else if ((target.validity.tooLong || target.validity.tooShort) && target.dataset.errLength) {
            customMessage = target.dataset.errLength;
        } else if ((target.validity.rangeUnderflow || target.validity.rangeOverflow) && target.dataset.errMinmax) {
            customMessage = target.dataset.errMinmax;
        }

        target.setCustomValidity(customMessage);
    }
</script>

Finally, when everything is validated on both the client and server, we would see the success screen.

Conclusion

Integrating htmx with .NET Razor Pages for form validation offers a streamlined and efficient approach to both client-side and server-side validation. By leveraging built-in validation mechanisms, customizing them with tag helpers, and utilizing HTML5 validation APIs, we can create robust and user-friendly forms.

It still has some rough edges and missing parts, but nothing that can't be figured out with a few hours of work (or by using AI), and it provides a lot of room for exploring different ways to handle validation:

• Built-in Razor Pages validation (is extremely powerful but somewhat outdated),

• More modern variations like aspnet-client-validation,

• HTML5 validation with vanilla JS,

• or any third-party validation library.

You can choose whichever you prefer, and with minor code adjustments in tag helpers, you can achieve both client-side and server-side validation while fully supporting the DRY principle.

Feel free to explore the full code on GitHub to see these concepts in action and improve your form validation workflows, also feel free to subscribe to the series where I explore more htmx + dotnet crap, or ping me on X if you have any questions.

But this sitemap file is broken!

It's not a problem for most users, but if you want to help Google index your blog better, you could provide a sitemap to Google Search Console.

When I tried to do this, I got an error: Sitemap could not be read

I checked several times that a sitemap is available. I put it into an XML validator to validate it. But it simply looks like the generated sitemap is incompatible with Google Search Console.

So, what is wrong with the sitemap here?

Here is the diff between what was not working and the fixed version. It looks like the sitemap built by Hasnode is incorrect enough to confuse Google Search Console. All these spaces make me think it's generated "manually" by a concatenating string.

My fix

As a dotnet developer, I fixed this problem with code. I built a simple Azure Function that consumes the original sitemap and does a minor cleanup to create a valid sitemap.xml.

Google Search Console would not allow adding any link as a source for a sitemap file, only the link from the blog site.

Luckily, Hashnode provides a way to handle it.

Where you could map any path to any link for redirect.

That would satisfy Google, and it would accept your sitemap.xml

A complete code of a function is pretty simple:

• get a current sitemap

• deserialze invalid structure

• serialize without errors

• return as a result

If you want to reproduce it yourself, create a new Azure Function Project, add the file, and then deploy it to Azure.

If you have any questions, feel free to ping me at @xakpc

However, after watching a video from @t3dotgg I was convinced that htmx might be helpful here and that it could fit me nicely. So, I decided to go through some use cases for it and do some tests to check if it is any good.

1. Introduction

First, let me briefly introduce what htmx and Razor Pages are:

htmx is a js library that gives access to AJAX, CSS Transitions, WebSockets, and Server Sent Events directly in HTML, using attributes. The library is built around "Hypermedia-Driven Application Architecture," which, in simple terms, could be described as "return HTML instead of JSON."

Razor Pages extends ASP.NET Core MVC, making coding page-focused scenarios easier and more productive than controllers and views. Razor Pages group the action (called a handler) and the viewmodel (called a PageModel) in one class and link it to a view. It uses a routing convention based on location and name in a Pages folder. This tends to keep Razor Pages and its handlers smaller and more focused while at the same time making it easier to find and work with.

I also want to mention pico.css. This is a minimal CSS framework for semantic HTML. It focuses on using simple native HTML tags as much as possible and provides consistent adaptive spacings and typography on all devices.

2. Background

Before I dive into integrating htmx and Razor Pages, let me briefly describe each technology. Both are praised for simplifying web development, but what are they?

2.1. htmx

htmx started as an intercooler.js - a small helper library to make AJAX calls through HTML tag attributes.

  <!-- This anchor tag posts to '/click' when it is clicked -->
  <a ic-post-to="/click">
    Click Me!
  </a>

Around three years ago, intercooler 2.0 (renamed to htmx 1.0) has been released. It was smaller, more expressive, and no longer depended on jQuery.

  <!-- have a button POST a click via AJAX -->
  <button hx-post="/clicked" hx-swap="outerHTML">
    Click Me
  </button>

htmx intend to help web developers to create dynamic, interactive web content without the overhead of complex JavaScript frameworks.

Leveraging HTML attributes allows seamless partial page updates, delivering the power of AJAX, CSS Transitions, WebSockets, and Server-Sent Events.

I would not talk about WebSockets and SSE or try them, though, because:

• They have experimental support

• If I want WebSockets and SSE, I probably would use Blazor and SignalR

2.1.1. AJAX

The core of htmx is a set of attributes that allow you to issue AJAX requests directly from HTML:

Each of these attributes takes a URL to issue an AJAX request to. The element will issue a request of the specified type to the given URL when the element is triggered:

<div hx-put="/messages">
    Put To Messages
</div>

This tells the browser:

When a user clicks on this div, issue a PUT request to the URL /messages and load the response into the div

By default, AJAX requests are triggered by the “natural” event of an element:

• input, textarea & select are triggered on the change event

• form is triggered on the submit event

• everything else is triggered by the click event

The hx-trigger attribute could change this to specify which event will cause the request. Here is a div that posts to /mouse_entered when a mouse enters it:

<div hx-post="/mouse_entered" hx-trigger="mouseenter">
    [Here Mouse, Mouse!]
</div>

2.1.2. CSS Transitions

htmx makes it easy to use CSS Transitions without javascript. Imagine that we need to replace content by htmx via an AJAX request with this new content:

<div id="div1">Original Content</div>
<!-- replaced -->
<div id="div1" class="red">New Content</div>

Note two things:

• The div has the same id in the original and the new content

• The red class has been added to the new content

Given this situation, we can write a CSS transition from the old state to the new state:

.red {
    color: red;
    transition: all ease-in 1s ;
}

When htmx swaps in this new content, it will do so in such a way that the CSS transition will apply to the new content, giving you a smooth transition to the new state. It happened because we keep its id stable across requests.

2.1.3. The philosophy behind "Hypermedia-Driven Applications"

I would not delve into details here, but it is worth mentioning because it's a pretty interesting concept. They wrote a book on it, read it sometime.

In short, it's all about the central role of HTML (or hypermedia) in driving and representing the state of web applications. Instead of relying heavily on intricate client-side scripting or full-page reloads to reflect changes in application state, this principle endorses the use of hypermedia itself.

The application state evolves fluidly by allowing individual page pieces to update in response to user actions or events, reducing the need for heavy JavaScript while promoting a more resilient and accessible web experience.

We did this with early ASP.NET MVC applications, utilizing jQuery to render partials, and now the proposal is to revert to this method for the sake of simplicity.

2.2. Razor Pages

Razor Pages, introduced in ASP.NET Core 2.0, offer a streamlined alternative to the MVC UI pattern, which Microsoft has supported since 2009.

While MVC promotes separation of concerns, it often creates a sprawling structure of controllers, views, and viewmodels across multiple folders. In contrast, Razor Pages encapsulate the action (referred to as a handler) and the viewmodel (now the PageModel) in a single class, directly tied to a corresponding Razor Page.

All these pages reside in a central Pages folder, following a naming-based routing convention. Handlers, prefixed with HTTP verbs like OnGet, simplify actions, typically returning the associated page by default. This structure enables concise, focused pages, making an application's navigation and updates more intuitive.

Razor Pages overall a vast topic, but I want to point out two essential for the htmx parts of it: handlers and partials

2.2.1. Razor Pages Handlers

Handler methods are the public methods in Razor Pages PageModel and they are automatically executed on a request, implicitly returning a result for the current page.

The Razor Pages framework uses a naming convention to select the appropriate handler method to execute. The default convention works by matching the HTTP method used for the request to the name of the method, which is prefixed with "On": OnGet(), OnPost(), OnPut() or async versions OnPostAsync(), OnGetAsync(), etc.

Handler methods can return void, Task if asynchronous, or an IActionResult (or Task<IActionResult>).

public class ValidationModel : PageModel
{
    public void OnGet()
    {
    }

    public IActionResult OnPost()
    {
        return Page();
    }
}

Razor Pages include a feature called "named handler methods". This feature enables you to specify multiple methods that can be executed for a single verb.

    public IActionResult OnGetItem()
    {
        return Partial("_ItemPartial");
    }

    public IActionResult OnPostItem()
    {
        return Partial("_ItemPartial");
    }

We could use tag helpers to generate links like /validation?handler=Item , where the handler would be set as a query parameter. There is also an option to generate path links like /validation/Item by setting a page route @page "{handler?}"

<!-- Razor code -->
<article>
    <a asp-page="Validation" asp-page-handler="Item">Link</a>
</article>

<!-- HTML code -->
<article>
    <a href="/validation?handler=Item">Link</a>
</article>

Unfortunately, these Tag Helpers exist only for <a> and <form> tags. One of the questions htmx trying to solve is Why should only <a> and <form> be able to make HTTP requests? so we could call handlers from any tag. MVC provides a way to generate a handler with a helper function: @Url.Page("BulkUpdate", "Activate") - would generate /BulkUpdate?handler=Activate .

But in htmx context, handlers usually belong to the same page, so to make it easier, I wrote a simple URL helper method:

public static class UrlHandlerExtensions
{
    public static string Handler(this IUrlHelper urlHelper, string handler, object? values = null)
    {
        // Convert the values object to a dictionary
        var routeValues = new RouteValueDictionary(values)
        {
            ["handler"] = handler // Add the handler to the dictionary
        };

        var url = urlHelper.RouteUrl(new UrlRouteContext
        {
            Values = routeValues
        });

        return url;
    }
}

It could be used with any HTML tag to set the handler URL to a htmx attribute:

<button class="outline" hx-delete="@Url.Handler("Item", new { id = Model.Id })" antiforgery="true">
    Delete
</button>

2.2.2. Razor Pages Partials

Partial Views in Razor Pages contain reusable HTML and code snippets that simplify complex pages by breaking them into smaller units.

Partial Views in ASP.NET MVC were introduced with the initial release of ASP.NET MVC itself. ASP.NET MVC 1.0 was officially released in March 2009, and from that first version, developers could use partial views to encapsulate and reuse parts of their views.

Partial Views are set up as cshtml files that do not take part in routing, so they do not have @page directive. Usually, partials are used to reuse some code on razor pages with the use of partial tag helper.

<partial name="_ItemPartial" model="Model.UserInfo" />

On top of that PageModel provides a set of methods that implement IActionResult , one of them: Partial - would apply the model, render a partial HTML view to the response, and return it as a response body.

That gives us the ability to define razor partial view

@model Xakpc.RazorHtmx.Data.UserInfoViewModel

<tr>
    <td>@Model.FirstName</td>
    <td>@Model.Email</td>
    <td>
        <button class="outline" hx-get="@Url.Handler("EditItem", new { id = Model.Id })">
            Edit
        </button>
    </td>
</tr>

and return it as generated HTML in a response

    public IActionResult OnGetItem(int id)
    {
        var item = TestData.Users.First(x => x.Id == id);

        return Partial("_TableRow", item);
    }

<tr>
    <td>Krystal</td>
    <td>krystal.heaney@bergnaummetz.us</td>
    <td>
        <button class="outline" hx-get="/edit-row?id=2&amp;handler=EditItem">
            Edit
        </button>
    </td>
</tr>

And we could also re-use the exact partial for the initial page generation

        <tbody hx-target="closest tr" hx-swap="outerHTML">
        @foreach (var userInfo in Model.Users)
        {
            <partial name="_TableRow" model="userInfo"/>
        }
        </tbody>

In my opinion this feature is a single reason why Razor Pages could even work with htmx.

3. Setting the Stage: Prerequisites and Initial Setup

To start, you don't need much - an installed dotnet core SDK and a favorite editor. I use Visual Studio because it's been my default editor since version VS 2013. But VS Code, or VS on Mac, or anything else, is fine. Check official tutorial if you feel stuck.

Run the following command to create a new Razor Pages project:

dotnet new webapp -o RazorHtmx

It would create a default project with Bootstrap and jQuery applied by default. I prefer to use pico.css in my projects, so I have a reduced version (you can check it here), but unfortunately, it's not a template yet.

3.1. Integrating htmx into Razor Pages

To integrate htmx, you should include the js file into _Layout. Choose whatever option you prefer from docs#installing. I downloaded and included htmx.min.js to a head tag of _Layout.cshtml

<head>
    <!-- rest of the code -->
    <script src="~/js/htmx.min.js" asp-append-version="true"></script>
</head>

4. Making First htmx Call in Razor

As I mentioned earlier, my aim was to explore each example from the htmx examples page to understand what is possible and how that could be helpful. The first example is click-to-edit, which is my perfect use case.

The click-to-edit pattern provides a way to offer inline editing of all or part of a record without a page refresh.

The example ended with several files

• _Partial.cshtml to present record

• _Edit.cshtml to present form for editing

• ClickToEdit.cshtml to present the page

• ClickToEdit.cshtml.cs for PageModel

• UserInfoViewModel.cs for model

Let me describe each of them.

UserInfoViewModel.cs

It's a pretty generic model class. Each property has data annotation to render labels in forms.

    public class UserInfoViewModel
    {
        public int Id { get; set; }

        [Display(Name = "First Name")]
        public string FirstName { get; set; }

        [Display(Name = "Last Name")]
        public string LastName { get; set; }

        [Display(Name = "Email")]
        public string Email { get; set; }

        [Display(Name = "Status")]
        public string? Status { get; set; }

        public Guid RowId { get; set; } = Guid.Empty;
    }

ClickToEdit.cshtml.cs

PageModel for this page consists of all required handler methods, basic OnGet for initial loading, a couple named GET handlers to show the edit form and view form, and PUT method to update form data.

public class ClickToEditModel : PageModel
{
    public UserInfoViewModel UserInfoViewModel { get; set; }

    public void OnGet()
    {
        UserInfoViewModel = GetUserInfo(1);
    }

    public IActionResult OnGetPartial(int id)
    {
        UserInfoViewModel = GetUserInfo(id);
        return Partial("_Partial", UserInfoViewModel);
    }

    public IActionResult OnGetEdit(int id)
    {
        UserInfoViewModel = GetUserInfo(id);
        return Partial("_Edit", UserInfoViewModel);
    }

    public IActionResult OnPutEdit(UserInfoViewModel userInfoViewModel)
    {
        UserInfoViewModel = userInfoViewModel;
        return Partial("_Partial", UserInfoViewModel);
    }
}

ClickToEdit.cshtml

The page itself is nothing other than a placeholder for partials. Instead of using <partial> tag helper, I'm using Html.PartialAsync helper method, but the outcome would be the same.

@page "/click-to-edit"
@model ClickToEditModel

<article>
    @await Html.PartialAsync("_Partial", Model.UserInfoViewModel)
</article>

Now, about partials. We have two of them - one renders a form, and another renders a view. Note that none of the HTML tags have classes because I use the semantic HTML CSS library pico.css. This approach significantly reduces the size of the partial. Consider the bulk that would be added if you were to use a class loaded with Tailwind CSS attributes.

First, _Partial.cshtml

@model Xakpc.RazorHtmx.Data.UserInfoViewModel

<div hx-target="this" hx-swap="outerHTML">
    <p>
        <strong><label asp-for="@Model.FirstName"></label></strong>
        @Model.FirstName
    </p>
    <p>
        <strong><label asp-for="@Model.LastName"></label></strong>
        @Model.LastName
    </p>
    <p>
        <strong><label asp-for="@Model.Email"></label></strong>
        @Model.Email
    </p>
    <button hx-get="@Url.Page("ClickToEdit", "Edit", new { id = Model.Id })">
        Click To Edit
    </button>
</div>

• hx-target="this" makes a div that updates itself when changed. It's also inherited, so it works when placed on the parent element.

• hx-swap="outerHTML" instructs to replace the entire target element with the response.

• hx-get="@Url.Page("ClickToEdit", "Edit", new { id = Model.Id })" would generate a URL to ClickToEdit.OnGetEdit handler method and would pass id query parameter.

<button hx-get="/click-to-edit?id=1&handler=Edit">
        Click To Edit
</button>

_Edit.cshtml

@model Xakpc.RazorHtmx.Data.UserInfoViewModel

<form hx-put="@Url.Page("ClickToEdit", "Edit")"
      hx-target="this" hx-swap="outerHTML">

    @Html.AntiForgeryToken()
    <input asp-for="Id" type="hidden"/>

    <label asp-for="@Model.FirstName"></label>
    <input asp-for="@Model.FirstName" type="text" required/>

    <label asp-for="@Model.LastName"></label>
    <input asp-for="@Model.LastName" type="text" required/>

    <label asp-for="@Model.Email"></label>
    <input asp-for="@Model.Email" type="email" required/>

    <div class="grid">
        <button>Submit</button>
        <button hx-get="@Url.Page("ClickToEdit", "Partial", new { id = Model.Id })" class="secondary">Cancel</button>
    </div>
</form>

• @Html.AntiForgeryToken() will generate a hidden field with an anti-forgery token to prevent CSRF vulnerabilities. More on this later.

• hx-put="@Url.Page("ClickToEdit", "Edit")" will perform PUT a request to OnPutEdit handler because updates should be PUT according to RESTful best practices.

• hx-target="this" makes a div that updates itself when changed. It's also inherited and works when placed on the parent element.

• hx-swap="outerHTML" instructs to replace the entire target element with the response.

• hx-get="@Url.Page("ClickToEdit", "Partial", new { id = Model.Id })" will perform GET request to OnGetPartial handler and set query parameter id to model id. This query would return rendered HTML of the record view:

    <div hx-target="this" hx-swap="outerHTML">
        <p>
            <strong><label for="FirstName">First Name</label></strong>
            Kennedy
        </p>
        <p>
            <strong><label for="LastName">Last Name</label></strong>
            Heaney
        </p>
        <p>
            <strong><label for="Email">Email</label></strong>
            kennedy_heaney@botsford.uk
        </p>
        <button hx-get="/click-to-edit?id=1&amp;handler=Edit">
            Click To Edit
        </button>
    </div>

As a result, a fully functional click-to-edit form in Razor Pages and htmx with 100-120 lines of code.

5. Exploring Other htmx Use-Cases

I surely could not even try to describe every feature htmx has. I selected a couple of examples that might be useful references for any web application.

5.1. Progress Bar

The progress bar is a very simple partial, just two lines. Having it as a separate file is almost a crime, but unfortunately, it's how it is.

@model int

<progress id="progress" value="@Model" max="100"></progress>

But I want to show you here is a _ProgresPartial, which hosts a progress bar.

Based on the progress model (is progress done or not), we could alter how this partial is rendered and what hx-trigger value is set. This is a primary function of Razor markup syntax.

Therefore, we could decide on the application's state and what should be returned as a view on the backend, which is very convenient.

@model Progress

<div hx-trigger="done" hx-get="@Url.Handler("Progress")" hx-swap="outerHTML" hx-target="this">
    @if (Model.Done)
    {
        <h3 role="status" tabindex="-1" autofocus>Complete</h3>
    }
    else
    {
        <h3 role="status" tabindex="-1" autofocus>Running</h3>
    }

    <div
        hx-get="@Url.Handler("Progress")"
        hx-trigger="@(Model.Done ? "none" : "every 600ms")"
        hx-target="this"
        hx-swap="innerHTML">
        <partial name="_ProgressBarPartial" model="@Model.Value"/>
    </div>

    @if (Model.Done)
    {
        <button hx-post="@Url.Handler("Start")" antiforgery="true" classes="add show:600ms">
            Restart Job
        </button>
    }
</div>

5.2. Table Scroll, Edit, Delete

Building interactive tables is a common task of any web application. With the help of htmx, we could easily expand a static table with scroll loading in place of edit and deletion.

I implemented several tests related to tables:

• Infinite Scroll

• Table Row Edit

• Table Row Delete

For infinite scroll, we have a partial in the tbody

        <tbody id="tbody">
            @await Html.PartialAsync("_TableBody", Model.UsersTable)
        </tbody>

The partial would draw table rows, and the last row would add hx-get attribute with revelaed trigger.

@foreach (var userInfo in Model.Users)
{
    @if (userInfo == Model.Users.Last())
    {
        <tr hx-get="@Url.Page("InfiniteScroll", "Page", new { page = Model.Page + 1 })"
            hx-trigger="revealed"
            hx-swap="afterend"
            hx-indicator="#ind">
            <td>@userInfo.FirstName @userInfo.LastName</td>
            <td>@userInfo.Email</td>
            <td>@userInfo.RowId.ToString("N").ToUpperInvariant()</td>
        </tr>
    }
    else
    {
        <tr>
            <td>@userInfo.FirstName @userInfo.LastName</td>
            <td>@userInfo.Email</td>
            <td>@userInfo.RowId.ToString("N").ToUpperInvariant()</td>
        </tr>
    }
}

The handler method load and render the next page of rows. There is also Task.Delay to simulate some loading.

    public async Task<IActionResult> OnGetPageAsync(int page)
    {
        await Task.Delay(1000);

        var data = TestData.Users.GetRange(page * PageSize, PageSize);

        return Partial("_TableBody", data);
    }

Here is how it works:

For table editing, I have two partials, for presenting and for editing, which are swapped on the button click.

<tr>
    <td>@Model.FirstName</td>
    <td>@Model.Email</td>
    <td>
        <button class="outline" hx-get="@Url.Handler("EditItem", new { id = Model.Id })">
            Edit
        </button>
    </td>
</tr>

<tr>
    <td>
        <input type="text" asp-for="@Model.FirstName"/>
    </td>
    <td>
        <input type="email" asp-for="@Model.Email"/>
    </td>
    <td>
        <button hx-get="@Url.Handler("Item", new { id = Model.Id })" class="secondary" style="margin-bottom: 6px;">
            Cancel
        </button>
        <button hx-put="@Url.Handler("Item", new { id = Model.Id })" hx-include="closest tr" antiforgery="true">
            Save
        </button>
    </td>
</tr>

Handlers for this page are straightforward: get item, get item form, update (put) item

    public IActionResult OnGetItem(int id)
    {
        var item = TestData.Users.First(x => x.Id == id);

        return Partial("_TableRow", item);
    }

    public IActionResult OnGetEditItem(int id)
    {
        var item = TestData.Users.First(x => x.Id == id);

        return Partial("_TableRowForm", item);
    }

    public IActionResult OnPutItem(UserInfoViewModel user)
    {
        var item = TestData.Users.First(x => x.Id == user.Id);
        item.FirstName = user.FirstName;
        item.Email = user.Email;

        return Partial("_TableRow", item);
    }

And now we can easily update table rows

Delete Row has a similar table row partial, but with hx-delete handler, because REST.

<tr>
    <td>@Model.FirstName @Model.LastName</td>
    <td>@Model.Email</td>
    <td>@Model.Status</td>
    <td>
        <button class="outline" hx-delete="@Url.Handler("Item", new { id = Model.Id })" antiforgery="true">
            Delete
        </button>
    </td>
</tr>

On the delete call, the handler would return 200 OK with an empty body instructing htmx to remove the row. We also use hx-confirm tag to confirm deletion

        <tbody hx-confirm="Are you sure?" hx-target="closest tr" hx-swap="outerHTML swap:1s">
        @foreach (var userInfo in Model.Users)
        {
            @await Html.PartialAsync("_TableRow", userInfo)
        }
        </tbody>

There is also some transition animation

Let's look at a couple of practical scenarios where htmx and Razor Pages integration shines.

5.3. Dialogs and tabs

A full code listing of how HTML5 dialogs could be created with htmx and Razor Pages. In this example, I used some JavaScript to show and hide the dialog.

At the same time, when dialog is shown, htmx would issue a get request to get data from the page handler and set the result as dialog content.

Actual dialog content would be generated on the backend from Razor partial.

<!-- DialogsHtml.cshtml --> 
@page "/dialogs-html"
@model DialogsHtmlModel

<!-- The Dialog -->
<dialog id="myDialog">
    <article id="dialogContent">
    </article>
</dialog>

<article>
    <!-- Trigger buttons -->
    <button data-target="myDialog"
            hx-get="@Url.Handler("Modal")"
            hx-target="#dialogContent"
            hx-trigger="click"
            onClick="showDialog()">
        Show Dialog
    </button>
</article>

@section Scripts
{
    <script>
        function showDialog() {
            const dialog = document.getElementById('myDialog');
            dialog.showModal(); // Opens the dialog
        }

        function closeDialog() {
            const dialog = document.getElementById('myDialog');
            dialog.close(); // Closes the dialog
        }
    </script>

}

<!-- DialogsHtml.cshtml.cs --> 
public class DialogsHtmlModel : PageModel
{
    public void OnGet()
    {
    }

    public IActionResult OnGetModal()
    {
        return Partial("_ModalPartial", ("Model Content Header", """
                Nunc nec ligula a tortor sollicitudin dictum in vel enim.
                Quisque facilisis turpis vel eros dictum aliquam et nec turpis.
                Sed eleifend a dui nec ullamcorper.
                Praesent vehicula lacus ac justo accumsan ullamcorper.
                """));
    }
}

<!-- _ModalPartial.cshtml -->
@model (string Header, string Text)

<header>
    <a href="#close" aria-label="Close" class="close" onclick="closeDialog(); return false;"></a>
    @Model.Header
</header>
<div>
    <p>
        @Model.Text
    </p>
</div>

A full code listing of how tabs could be created with htmx and Razor Pages. Here, I have tabs div, which is replaced with tab partial.

The interesting part is a load trigger, which is fired on page load to get the initial tab. That could be done through a razor like I did previously, as well.

<!-- Tabs.chtmls -->
@page "/tabs-hateoas"
@model TabsModel

<div id="tabs"
     hx-get="@Url.Handler("Tab1")"
     hx-trigger="load delay:100ms"
     hx-target="#tabs"
     hx-swap="innerHTML">
</div>

<!-- Tabs.chtmls.cs -->
public class TabsModel : PageModel
{
    public void OnGet()
    {
    }

    public IActionResult OnGetTab1()
    {
        return Partial("_Tab1Partial");
    }

    public IActionResult OnGetTab2()
    {
        return Partial("_Tab2Partial");
    }

    public IActionResult OnGetTab3()
    {
        return Partial("_Tab3Partial");
    }
}

<!-- _Tab1Partial.cshtml -->
<div class="grid">
    <button hx-get="@Url.Handler("Tab1")">Tab 1</button>
    <button hx-get="@Url.Handler("Tab2")" class="outline">Tab 2</button>
    <button hx-get="@Url.Handler("Tab3")" class="outline">Tab 3</button>
</div>

<article>
    <div>
        some text...
    </div>
</article>

<!-- _Tab2Partial.cshtml -->
<div class="grid" role="tablist">
    <button hx-get="@Url.Handler("Tab1")" class="outline">Tab 1</button>
    <button hx-get="@Url.Handler("Tab2")">Tab 2</button>
    <button hx-get="@Url.Handler("Tab3")" class="outline">Tab 3</button>
</div>

<article>
    <div>
        some text 2...
    </div>
</article>

<!-- _Tab3Partial.cshtml -->
<div class="grid" role="tablist">
    <button hx-get="@Url.Handler("Tab1")" class="outline">Tab 1</button>
    <button hx-get="@Url.Handler("Tab2")" class="outline">Tab 2</button>
    <button hx-get="@Url.Handler("Tab3")">Tab 3</button>
</div>

<article>
    <div>
        some text 3...
    </div>
</article>

Tabs, in my case, are buttons, but it still looks good

5.4. Live search feature on a Razor Page

Here we use keyup trigger to send a search query to OnPostSearch handler, which would render partial based on search results.

<!-- ActiveSearch.cshtml -->
@page "/active-search"
@model ActiveSearchModel

<article>
    <h3>
        Search Contacts
        <span class="htmx-indicator" aria-busy="true">Searching...</span>
    </h3>

    <input type="search" name="search"
           placeholder="Begin Typing To Search Users..."
           hx-post="@Url.Handler("Search")"
           hx-trigger="keyup changed delay:500ms, search"
           hx-target="#search-results"
           hx-indicator=".htmx-indicator"
           antiforgery="true"/>

    <table class="table">
        <thead>
        <tr>
            <th>First Name</th>
            <th>Last Name</th>
            <th>Email</th>
        </tr>
        </thead>
        <tbody id="search-results">
        </tbody>
    </table>
</article>

<!-- ActiveSearch.cshtml.cs -->
public class ActiveSearchModel : PageModel
{
    public void OnGet()
    {
    }

    public IActionResult OnPostSearch(string search)
    {
        if (search == null || string.IsNullOrEmpty(search))
        {
            return Partial("_TableBody", new List<UserInfoViewModel>());
        }

        var users = TestData.Users.Where(u => u.Email.Contains(search.ToLowerInvariant())).ToList();

        if (users.Any())
        {
            return Partial("_TableBody", users);
        }

        return Partial("_TableBody", TestData.Users.Take(7).ToList());
    }
}

<!-- _TableBody.cshtml -->
@model List<Xakpc.RazorHtmx.Data.UserInfoViewModel>

@foreach (var userInfo in Model)
{
    <tr>
        <td>@userInfo.FirstName</td>
        <td>@userInfo.LastName</td>
        <td>@userInfo.Email</td>
    </tr>
}

Here is how it works

5.5 Animations

While my primary focus wasn't on aesthetics during testing, it's worth noting that it could be done. htmx supports CSS transitions so we could apply some cool animations to our partials.

@page "/animations"
@model AnimationsModel

<article>
    <h2>Using the View Transition API</h2>
    <div class="slide-it">
        <partial name="_SwapContentPartial", model="@("Initial Content", "Swap It")"/>
    </div>
</article>

@section Styles
{
  <style>
   @@keyframes fade-in {
     from { opacity: 0; }
   }

   @@keyframes fade-out {
     to { opacity: 0; }
   }

   @@keyframes slide-from-right {
     from { transform: translateX(90px); }
   }

   @@keyframes slide-to-left {
     to { transform: translateX(-90px); }
   }

   .slide-it {
     view-transition-name: slide-it;
   }

   ::view-transition-old(slide-it) {
     animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
   }
   ::view-transition-new(slide-it) {
     animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
   }
</style>
}

In partial, we instruct htmx to use transition.

@model (string Title, string Button)

<h6>@Model.Title</h6>
<button hx-get="@Url.Handler("NewContent")" hx-swap="innerHTML transition:true" hx-target="closest div">
    @Model.Button
</button>

This gives us nice animation.

6. Benefits of the Integration

Simplicity, simplicity, simplicity.

I am a huge advocate of simplicity. I work with highly complex systems in my daily job, where dozens of microservices process gigabytes of data 24/7.

Probably, that's why I wouldn't say I like to overcomplicate anything. And like Razor Pages was invented to simplify MVC web development, pico.css was invented to simplify web design, so as far as I see, htmx could be the tool to simplify interactivity.

But these are all personal preferences. Let's evaluate what actual benefits Razor Pages together with htmx might produce.

6.1. Speed and Efficiency: Faster page loads and enhanced user experience.

htmx allows for seamless partial page updates, meaning web pages can reflect real-time data changes without requiring a complete page refresh. This leads to a more interactive and immersive user experience, particularly beneficial for applications where up-to-the-minute data display is crucial, like dashboards or monitoring systems.

Due to the lightweight nature of htmx, only necessary data is transferred between client and server. This minimizes the bandwidth usage and server processing power required for each user interaction, making it possible to serve more users without a proportional resource increase.

6.2. Maintainability: Separation of concerns with Razor's code-behind model and htmx's lightweight nature.

Razor Pages is MPA (Multi-Page Application) framework. It is designed for creating web applications where each user interaction or action corresponds to a different web page loaded from the server.

Historically, dotnet developers relied on JavaScript and jQuery to add interactivity. I believe there was never a "best-way" of how to organize JavaScript: there was a custom colocation option cshtml.js, section @Scripts , setup grunt and npm aside dotnet project, but most of the time, js was simply dumped into wwwroot folder.

htmx takes razor page concept of self-contained Page with its associated logic, data model, and view and adds interactivity there but keeps it clean and maintainable.

6.3. Simplified Development Workflow

By merging Razor Pages and htmx, developers can enjoy a more streamlined development process. The inherent structure of Razor Pages, which emphasizes a clear delineation between view and logic, combined with the straightforward integration of htmx, reduces the learning curve for new team members.

This synergy minimizes the need for extensive reliance on JavaScript for dynamic content, which can often introduce complexities. As a result, development teams can bring features to market faster and address bugs or changes with greater agility.

7. Potential Challenges and Solutions

While the benefits of this integration are numerous, like all technologies, it comes with its set of challenges.

7.1. Antiforgery Token

Running the code below to update data will result in the error: Response Status Error Code 400 from /click-to-edit?handler=Edit

<form hx-put="@Url.Page("ClickToEdit", "Edit")" 
        hx-target="this" 
        hx-swap="outerHTML"> 
   <!-- form body -->
</form>

This is because any POST or PUT request to the razor page requires AntiforgeryToken to prevent CSRF attacks.

Cross-Site Request Forgery (CSRF) is an attack where a malicious entity tricks a user's browser into performing undesired actions on a trusted site where the user is authenticated. This is possible because browsers automatically include cookies, including session cookies, with requests.

To counteract this, many sites employ CSRF tokens, generated server-side. These tokens, which can be created per session or request, ensure that every action taken on a site is genuinely intended by the authenticated user.

The server validates the token with every request; if they don't match, the request is denied, potentially flagging it as a CSRF attempt.

Antiforgery Token check could be disabled by applying [IgnoreAntiforgeryToken(Order = 1001)] attribute on the page model, but that is a security risk.

You could manually expand forms and add anti-forgery token with a helper method @Html.AntiForgeryToken(). This would provide tokens as a hidden field and include it into form data.

Tokens also could be provided as a header. It is considered a more secure option, and we could add a header to our htmx request using hx-headers attribute.

<form hx-put="@Url.Page("ClickToEdit", "Edit")" 
    hx-headers='{"RequestVerificationToken": "@Model.AntiforgeryToken"}'
    hx-target="this" hx-swap="outerHTML" >

For forms, it is better to use the helper method. But to add tokens to other HTML elements, such as <button> or <input> I created a helper tag class. It would generate hx-headers tag and set token value when I add an attribute antiforgery="true" to element.

[HtmlTargetElement("input", Attributes = AntiForgeryAttributeName)]
[HtmlTargetElement("button", Attributes = AntiForgeryAttributeName)]
public class AntiForgeryHeaderTagHelper : TagHelper
{
    [HtmlAttributeNotBound]
    [ViewContext]
    public ViewContext ViewContext { get; set; }

    [HtmlAttributeName(AntiForgeryAttributeName)]
    public bool AntiForgery { get; set; }

    private const string AntiForgeryAttributeName = "antiforgery";
    private readonly IAntiforgery _antiforgery;

    public AntiForgeryHeaderTagHelper(IAntiforgery antiforgery)
    {
        _antiforgery = antiforgery;
    }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        if (AntiForgery)
        {
            var token = _antiforgery.GetAndStoreTokens(ViewContext.HttpContext).RequestToken;
            var currentHeaderValue = output.Attributes["hx-headers"]?.Value.ToString();
            var newHeaderValue = $"\"RequestVerificationToken\": \"{token}\"";

            if (string.IsNullOrEmpty(currentHeaderValue))
            {
                output.Attributes.SetAttribute("hx-headers", newHeaderValue);
            }
            else
            {
                // Append the anti-forgery token to existing hx-headers
                newHeaderValue = $"{currentHeaderValue}, {newHeaderValue}";
                output.Attributes.SetAttribute("hx-headers", newHeaderValue);
            }
        }
    }
}

7.2. Validation

MVC and DataAttributes provide a lot of helpers to generate validation. Unfortunately, most of it is designed for jquery.validate.js and jquery.validate.unobtrusive.js.

On the other hand, htmx is designed to utilize HTML5 validation.

Of course, we could disable client-side validation and write everything by hand, but that sounds annoying.

services.AddRazorPages()
    .AddViewOptions(options =>
    {
        options.HtmlHelperOptions.ClientValidationEnabled = false;
    });

At the moment I didn't found a good solution for that. I could see a several options here:

• Link together HTML 5 and MVC-generated validation, by writing custom js code

• Link together MVC-generated validation and htmx, but keep using jquery.validate

If you know a solution to that problem, feel free to ping me.

8. Conclusion

To sum it up, I tried different use cases of htmx and dotnet Razor Pages during my tests. In this article, I presented the history of htmx and Razor Pages, and show you how they can be integrated seamlessly.

I was impressed by how a technology from 2009, partials, integrates so well with htmx. It also fits well with Razor Pages and pico.css, which I often use for side projects. I only have positive impressions here:

• It works with razor and MVC partials perfectly

• It's a good fit with semantic HTML CSS libraries

• It's two times smaller than jQuery

• It's straightforward to use

Regarding the negative aspects

• There is no IntelliSense support of htmx tags in Visual Studio yet (there is for Visual Studio Code)

• Need to figure out validation to reuse all that helpers Razor Pages provides

• Some kind of fragments would be nice

• htmx might not be accepted by enterprises where dotnet is most used

That would be all. Once again, the source code of my tests is available on github, the demo project deployed on Azure, and if you have any questions, feel free to ping me on Twitter, sorry, on 𝕏.

9. Further Reading/References

In the future, I might explore some more advanced scenarios, like validation, boosting, history, and maybe even touch hyperscript (but I doubt that; it does not bring me joy at first glance).

Some useful resources

• Microsoft Razor Pages documentation

• Learn Razor Pages by Mike Brind

• htmx Documentation

The following information is related to Microsoft.AspNetCore.App version 7.0.7.

In general, creating a sitemap.xml for web applications can significantly enhance their search engine visibility. A sitemap provides a roadmap for search engine bots, enabling them to index your website content more efficiently.

Step 1: Understand the Structure of sitemap.xml

A sitemap XML file lists URLs for a site along with additional metadata about each URL (when it was last updated, how often it changes, and its importance relative to other URLs).

Here is a very basic XML sitemap that includes the location of a single URL:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://www.example.com/foo.html</loc>
        <lastmod>2022-06-04</lastmod>
    </url>
</urlset>

There are more parameters defined in the protocol specification, but Google claims to ignore them, so I think they could be omitted:

• Google ignores <priority> and <changefreq> values.

• Google uses the <lastmod> value if it's consistently and verifiably (for example by comparing to the last modification of the page) accurate.

Step 2: Create a Model for the Sitemap

First, I created a model for the sitemap node. This model will represent individual URLs, their priority, and other metadata.

    public class SitemapNode
    {
        public SitemapFrequency? Frequency { get; set; }
        public DateTime? LastModified { get; set; }
        public double? Priority { get; set; }
        public string Url { get; set; }
    }

    public enum SitemapFrequency
    {
        Never,
        Yearly,
        Monthly,
        Weekly,
        Daily,
        Hourly,
        Always
    }

There is another approach if I wanted to use serialization, which would look a bit clearer, but it takes twice as many lines of code, so I skipped it.

[XmlRoot("urlset", Namespace = "http://www.sitemaps.org/schemas/sitemap/0.9")]
public class SitemapUrlSet
{
    [XmlElement("url")]
    public List<SitemapNode> SitemapNodes { get; set; } = new List<SitemapNode>();
}

public class SitemapNode
{
    [XmlElement("loc")]
    public string Url { get; set; }

    [XmlElement("lastmod")]
    public DateTime? LastModified { get; set; }

    [XmlElement("changefreq")]
    public SitemapFrequency? Frequency { get; set; }

    [XmlElement("priority")]
    public double? Priority { get; set; }
}

public enum SitemapFrequency
{
    [XmlEnum("never")]
    Never,

    [XmlEnum("yearly")]
    Yearly,

    [XmlEnum("monthly")]
    Monthly,

    [XmlEnum("weekly")]
    Weekly,

    [XmlEnum("daily")]
    Daily,

    [XmlEnum("hourly")]
    Hourly,

    [XmlEnum("always")]
    Always
}

Step 3: Setting Up the Method to Generate Sitemap Nodes

I needed a service or method that will generate the sitemap nodes based on my website's content. To generate URLs for Razor Pages, you typically could use PageLink or LinkGenerator. I used the last one:

    public class SitemapModel : PageModel
    {
        private readonly LinkGenerator _linkGenerator;

        public SitemapModel(LinkGenerator linkGenerator)
        {
            _linkGenerator = linkGenerator;
        }

        // ... rest of the code
    }

Creating a sitemap for static pages is easier by hardcoding them. Blog pages or other dynamic content are taken from a database or file system (in my case) based on where they are stored.

Method GetUriByPage from provides an absolute URL based on page name - handy.

    public class SitemapModel : PageModel
    {   
        // ... rest of the code   
        public IReadOnlyCollection<SitemapNode> GetSitemapNodes()
        {
            var nodes = new List<SitemapNode>
            {
                new()
                {
                    Url = _linkGenerator.GetUriByPage(HttpContext, "/Index"),
                    Priority = 1,
                },
                new()
                {
                    Url = _linkGenerator.GetUriByPage(HttpContext, "/Tools/CreateCode"),
                    Priority = 0.9
                },
                new()
                {
                    Url = _linkGenerator.GetUriByPage(HttpContext, "/Legal/Privacy"),
                    Priority = 0.6
                },
                new()
                {
                    Url = _linkGenerator.GetUriByPage(HttpContext, "/Legal/TermsOfService"),
                    Priority = 0.6
                }
            };

            foreach(...)
            {
                // fill nodes from blog index
            }

            return nodes;
        }
    }

Step 4: Creating the Sitemap Page

Then I added a new Razor Page Sitemap.cshtml that will be responsible for generating the sitemap.xml. When users or search engine bots access this page, it should return the sitemap in XML format. This is an elegant trick: we return the razor page Sitemap.cshtml as an XML file.

@page "/sitemap.xml"
@model Xakpc.Project.Pages.SitemapModel
@{
    Layout = null;
    Response.ContentType = "text/xml";
}
<?xml version="1.0" encoding="UTF-8" ?>
@Html.Raw(Model.RawXmlData)

Step 5: Formatting the XML

On the sitemap Razor Page model, I formatted the sitemap nodes into XML format. For that, I manually built XML file with XElements

    public class SitemapModel : PageModel
    {   
        // ... rest of the code  

        /// <summary>
        /// Serializes to raw XML
        /// </summary>
        public string GetSitemapDocument(IEnumerable<SitemapNode> sitemapNodes)
        {
            XNamespace xmlns = "http://www.sitemaps.org/schemas/sitemap/0.9";
            var root = new XElement(xmlns + "urlset");

            foreach (var sitemapNode in sitemapNodes)
            {
                var urlElement = new XElement(
                    xmlns + "url",
                    new XElement(xmlns + "loc", Uri.EscapeUriString(sitemapNode.Url)),
                    sitemapNode.LastModified == null ? null : new XElement(
                        xmlns + "lastmod",
                        sitemapNode.LastModified.Value.ToLocalTime().ToString("yyyy-MM-ddTHH:mm:sszzz")),
                    sitemapNode.Frequency == null ? null : new XElement(
                        xmlns + "changefreq",
                        sitemapNode.Frequency.Value.ToString().ToLowerInvariant()),
                    sitemapNode.Priority == null ? null : new XElement(
                        xmlns + "priority",
                        sitemapNode.Priority.Value.ToString("F1", CultureInfo.InvariantCulture)));
                root.Add(urlElement);
            }

            var document = new XDocument(root);
            return document.ToString();
        }
    }

The other option is to use serialization (if you map classes with attributes - I skipped that part)

public string GetSitemapDocument(IEnumerable<SitemapNode> sitemapNodes)
{
    var sitemapUrlSet = new SitemapUrlSet { SitemapNodes = sitemapNodes.ToList() };

    var xmlSerializer = new XmlSerializer(typeof(SitemapUrlSet));

    using var stringWriter = new StringWriterUtf8();
    using var xmlTextWriter = XmlWriter.Create(stringWriter, new XmlWriterSettings { Indent = true });

    xmlSerializer.Serialize(xmlTextWriter, sitemapUrlSet);

    return stringWriter.ToString();
}

And all that is left is to call methods in OnGet method and set bound property

    public class SitemapModel : PageModel
    {   
        // ... rest of the code  

        /// <summary>
        /// Gets the raw XML data
        /// </summary>
        [BindProperty(SupportsGet = true)]
        public string RawXmlData { get; set; }

        public void OnGet()
        {
            var nodes = GetSitemapNodes();
            RawXmlData = GetSitemapDocument(nodes);
        }
    }

Step 6: Register the Sitemap with Search Engines

After the sitemap is successfully set up, it's a good idea to register it with major search engines like Google and Bing. This will ensure that they know your sitemap's existence and can crawl your website more effectively.

1. Google: Use Google Search Console to submit your sitemap.

2. Bing: Use Bing Webmaster Tools to submit your sitemap.

Conclusion

Final Sitemap.xml

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://contoso.com/</loc>
        <priority>1.0</priority>
    </url>
    <url>
        <loc>https://contoso.com/make-code</loc>
        <priority>0.9</priority>
    </url>
    <url>
        <loc>https://contoso.com/legal/privacy</loc>
        <priority>0.6</priority>
    </url>
    <url>
        <loc>https://contoso.com/legal/termsofservice</loc>
        <priority>0.6</priority>
    </url>
    ...
</urlset>

As you can see, setting up a sitemap.xml in a Razor Pages application is straightforward. Following the steps above and adding the appropriate code ensures your website is more visible and accessible to search engines.

And then I found out that #PlanetScaleHackathon launched the same month and I decided to take a part in it. I required a database and PlanetScale looks like a new and interesting solution to play with.

So what kind of chatbot we are building here? I believe that messenger could be the most convenient way to gather feedback in almost any scenario, but especially in the physical world. But sharing your messenger contacts with anyone will bring spam, trolls, and sometimes unwanted night calls.

Recently Telegram became one of the top-5 downloaded apps worldwide in 2022 and now has over 700 million monthly active users, so the timing is quite good.

It would be nice to have the ability for your customers, clients, or subscribers to contact you directly in Telegram without telegraphing your personal account to everyone.

In this bot scenario we would actually have two bots:

• MasterBot will have master users who receive and answer the messages
• ClientBot will be attached to the master user and receive messages from clients to resend them to the master user.

Clients will not know the master user's private account name, and masters could know client users' names if they have a username set in their telegram profile.

WhatsApp does this as part of its separate Business App. So let's build a similar solution for Telegram.

What is a Telegram Chatbot

(Chat)Bots are like small programs that run right inside Telegram. They are made by third-party developers. Bots are safe to use. They can see your public name, username, and profile pictures, and they can see messages you send to them, that's it. They can't access your last seen status and don't see your phone number (unless you decide to give it to them yourself).

What is a Durable Function?

The official definition

Durable Functions is an extension of Azure Functions that lets you write stateful functions in a serverless compute environment.

There are two types of durable functions: orchestrator functions and entity functions.

In easy words, the orchestrator function is a function that contains orchestrator, and it could be stopped and resumed at any moment. The main purpose of the orchestrator is to launch other functions (they are called activity functions) and the result could be stored in local variables, durable entities, and used in logic constructions.

This allows the implementation of a lot of cool patterns in a serverless environment, like function chaining for example. You could read more about it in docs.

The entity function is again, a function, that allows saving, reading, and manipulating data in a serverless environment. I think it could be treated as a repository: we have data and a set of operations to manipulate it. The data is stored serialized as JSON in Azure Table Storage.

Entity function provides convenient class-based syntax where entities and operations are represented as classes and methods.

Now when we are familiar with tech, let's design ourselves a chatbot.

Chatbot design

Chatbots always contain some kind of state machine under the hood.

There is an entire theory behind that, but in simple words applied to our case:

• a user always is in some state (p0-p5)
• any message a user sends to a chatbot will move him into another state (a,b,...)
• each time the state changes, our application performs some action and returns a response message to be sent back to the user.

Each state implies some logic it could do and the next state where it could navigate. To implement it in a scalable (and a bit overengineering) way we would use State design pattern.

You might ask yourself: do I need that? Well, the answer is "it depends". If you building a simple chatbot with a couple of commands, or plan to connect your chatbot to a question-answering "AI" or plan to heavily depend on some chatbot framework or engine - you probably could make a several ifs and that would be enough. Because you should K.I.S.S.

State Machine design

Our state machine will be only for the MasterBot. Client bots are extremely simple: they forward messages to the master user, and forward responses back.

For the master bot we would need the next operations:

• /start - this operation will move the master user to a MainState
• /add - attach new client bot
• /remove - detach client bot
• /subscribe - update to pro-plan (we want to pay for hosting somehow)
• /unsubscribe - mandatory
• /qr - generate QR code with client bot invite
• Reply - not a command, but an actual reply to a client message, it requires a state.
• Ban - is not a command and does not require a state

Not everything here requires a state, a lot of operations have only one step and could be done by going from MainState to MainState.

Each arrow would have an associated Activity Function with it, so each time we change the state of the master user we will execute some action, then generate and send a response back.

The state machine will not be doing any hard work by itself. It will validate input, execute steps and return a name of Activity Function to be executed by the orchestrator.

State Machine Implementation

To implement our state machine in the serverless environment we need three main components:

1. We need a Context - it defines the interface to clients and maintains a reference to an instance of a State subclass, which represents the current state of the User.
2. We need our states - all of them will be inherited from the base State abstract class and implement a do-step method.
3. We need a Durable Entity to store the current user state.

But it's not that easy with Durable Entity. As I mentioned earlier it is stored serialized as JSON by the Newtonsoft.JSON library. And because we want to use inheritance and we want the State to have reference to a user Context - it really messes up serialization.

There is a way to set up Newtonsoft.JSON to store type names and deserialize them into concrete classes by applying TypeNameHandling = TypeNameHandling.All setting. For durable functions it's TypeNameHandling.None by default.

To change this setting we need to override IMessageSerializerSettingsFactory in the Startup class like that

public class Startup : FunctionsStartup
{       
    public override void Configure(IFunctionsHostBuilder builder)
    {
        ...
        builder.Services.AddSingleton<IMessageSerializerSettingsFactory, CustomMessageSerializerSettingsFactory>();
    }

    internal class CustomMessageSerializerSettingsFactory : IMessageSerializerSettingsFactory
    {
        public JsonSerializerSettings CreateJsonSerializerSettings()
        {
            return new JsonSerializerSettings
            {
                TypeNameHandling = TypeNameHandling.All,
                DateParseHandling = DateParseHandling.None,         
            };
        }
    }
}

Unfortunately, that didn't work for me for some reason. I decide to go another way and add two extra components

1. States enum to store
2. StateFactory to rebuild concrete state class from stored enum value.

1. Context class

First of all, we need a user context. Context holds the current user state, allows perform transition to other states, and has a single method GetAction.

public class Context
{
    // A reference to the current state of the Context.
    public State State { get; set; }

    public Context(State state)
    {
        TransitionTo(state);
    }

    // The Context allows changing the State object at runtime.
    public void TransitionTo(State state)
    {
        Console.WriteLine($"Context: Transition to {state.GetType().Name}.");
        State = state;
        State.SetContext(this);
    }

    // The Context delegates part of its behavior to the current State
    // object.
    public StateAction GetAction(string messageText) => State?.GetAction(messageText);
}

2. Base State

Base State classes require each inherited class to implement which States it represents. It is required for the factory to reconstruct user context based on Durable Entity which stores user state.

/// <summary>
/// The base State class declares methods that all Concrete State should implement
/// </summary>
public abstract class State
{
    /// <summary>
    /// Property should be implemented in concrete state for our factory to construct concrete type of state
    /// </summary>
    /// <remarks>
    /// It could be Type if we want to use reflection
    /// </remarks>
    public abstract States Type { get; }

    protected Context _context;

    /// <summary>
    /// a backreference to the Context object, associated with the State. 
    /// This backreference can be used by States to transition the Context to another State.
    /// </summary>
    public void SetContext(Context context)
    {
        _context = context;
    }

    /// <summary>
    /// Get Activity Function name
    /// </summary>
    public abstract StateAction GetAction(string messageText);
}

We also create a StateAction record as a result of the GetAction method. This record returns to the orchestrator what needs to be done next: either just send the response, or perform an activity, or maybe both.

public record StateAction(MasterBotResponse Response = default, string Activity = default);

I will not show an implementation of all states, just a couple of classes to understand the pattern.

Main state

This would be the starting point for every user. Based on the input of this state our chatbot will provide one or another answer.

If input a valid command MainState would return either message or activity to launch.

If an input is an unknown command the fallback message is sent back to a user.

class MainState : State
{
    public override States Type => States.Main;

    public override StateAction GetAction(string messageText)
    {
        switch (messageText)
        {
            case "/start":
                return new StateAction(Response: new MasterBotResponse(@"Welcome to a Feedbacks Master Bot"), Activity: nameof(MasterBotActivityFunctions.ActivityRegisterMasterUser));
            case "/add":
                _context.TransitionTo(new AddState());
                return new StateAction(Response: new MasterBotResponse("Create client-facing chatbot through @BotFather and send me generated UserToken"));
            case "/remove":
                return new StateAction(Activity: nameof(MasterBotActivityFunctions.ActivityDoRemove));
            case "/qr":
                return new StateAction(Activity: nameof(MasterBotActivityFunctions.ActivityCreateQrCode));
        }

        return new StateAction(Response: new MasterBotResponse("Unknown command, press **Menu** button for list of commands", Markdown: true));
    }

Workflows

Based on this design it's very easy to combine several steps (states) into a workflow. Imagine a user who wants to delete an item. The flow looks like that

1. Send /add command
2. Bot prompt to send bot token
3. Send token
4. Validate token, perform the action
5. Back to the main

Code of the state might look something like that

public class AddState : State
{
    public override States Type => States.Add;

    bool IsValidToken(string messageText)
    {
        return Regex.IsMatch(messageText, "[0-9]{9}:[a-zA-Z0-9_-]{35}");
    }

    public override StateAction GetAction(string messageText)
    {
        if (messageText.Equals("/cancel", StringComparison.OrdinalIgnoreCase))
        {
            _context.TransitionTo(new MainState());
            return new StateAction(new MasterBotResponse("Cancelled"));
        }

        if (IsValidToken(messageText))
        {
            _context.TransitionTo(new MainState());
            return new StateAction(Activity: nameof(MasterBotActivityFunctions.ActivityDoAdd));
        }

        return new StateAction(new MasterBotResponse("Invalid input, try again or /cancel"));
    }
}

Users could send the /cancel command to undo the adding.

Responding State

If other states are triggered by a sent message, this state is triggered by replying. When a user responds to any message it will be forced to RespondingState. We also save a MessageReferenceId from our storage of received messages to use later in the activity function.

Here is what we should add to MasterBotWebhook to handle replies:

// the message is a reply, so we process it into reply state
if (update.Message.ReplyToMessage != null)
{
    var reply = update.Message.ReplyToMessage;
    var messageReference = await _database.GetClientMessageReference(messageId: reply.MessageId);

    if (messageReference == null)
    {
        log.LogError("Message to answer not found");
        return new OkResult();
    }

    // change user to responding state
    var userEntity = new EntityId(nameof(DurableUserState), update.Message.From.Id.ToString());
    await durableClient.SignalEntityAsync<IDurableUserState>(userEntity, us => us.SetUserState(States.Responding));

    // store original message id                    
    await durableClient.SignalEntityAsync<IDurableUserState>(userEntity, us => us.SetReplyToMessageId(messageReference.Id));
}

After that, we start the orchestrator function as usual.

In RespondingState we handle /cancel, we handle sending other command and we launch ActivityResponse

public class RespondingState : State
{
    public override States Type => States.Responding;

    public override StateAction GetAction(string messageText)
    {
        if (messageText.Equals("/cancel", StringComparison.OrdinalIgnoreCase))
        {
            _context.TransitionTo(new MainState());
            return new StateAction(new MasterBotResponse("Cancelled"));
        }          

        var ms = new MainState();
        _context.TransitionTo(ms);

        if (messageText.StartsWith("/"))
        {
            return ms.GetAction(messageText);
        }

        return new StateAction(Activity: nameof(MasterBotActivityFunctions.ActivityResponse));
    }
}

The ActivityResponse function

[FunctionName(nameof(ActivityResponse))]
public async Task<MasterBotResponse> ActivityResponse([ActivityTrigger] Message message, [DurableClient] IDurableEntityClient client, ILogger log)
{
    // update message (icon)
    await _telegramService.SetAnsweredAsync(message); // todo not working

    // get client chat messageRef and botToken
    var entityId = new EntityId(nameof(DurableUserState), message.From.Id.ToString());
    var userState = await client.ReadEntityStateAsync<DurableUserState>(entityId);
    var messageRef = await _database.GetClientMessageReference(messageReferenceId: userState.EntityState.MessageReferenceId);
    var botToken = await _database.GetClientBotToken(messageRef.ClientBotChatId);

    // send responce to a client chat
    await _telegramService.ResponseAsync(new MasterBotResponse(message.Text, messageRef.OriginalFromId), botToken);

    // no answer needed
    return default;
}

3. Durable User State Implementation

This is the place where we use the full power of durable function. On the call, our function will execute the GetAction method of the current state and will navigate to the next state by sending a fire-and-forget signal to itself.

A durable user state is defined by Interface IDurableUserState.

public interface IDurableUserState
{
    Task<States> GetUserState();
    void SetUserState(States state);
    void SetReplyToMessageId(long messageReferenceId);
}

This allows to access Durable Entity in a safe way:

// get user context (user state) from durable entity
var userState = await userProxy.GetUserState();
...
// save new state            
userProxy.SetUserState(userContext.State.Type);

And this is how it's stored in Azure Storage

4. States enum

Our states enum currently is very small and required only for ContextFactory

public enum States
{
    Main,
    Add,
    Responding
}

5. Context Factory

Context Factory is required for restoring stored user State enum value to a State object. It simplifies serialization and deserialization but made code a bit bulkier.

Note that by default we put the user into a Main state.

public class ContextFactory
{
    public Context RestoreContext(States userState)
    {
        var state = RestoreState(userState) ?? RestoreState(States.Main);
        var context = new Context(state);
        return context;            
    }

    private State RestoreState(States state)
    {
        switch (state)
        {
            case States.Main:
                return new MainState();
            case States.Add:
                return new AddState();
            case States.Responding:
                return new RespondingState();
            default:
                return null;
        }
    }
}

Functions design and implementation

Let's design our functions

The flow goes like this

1) The HTTP-trigger function accepts the telegram webhook and launches the orchestrator function

[FunctionName("FeedbackBotsWeebhook")]
public static async Task<IActionResult> HttpStart(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a webhook.");

    // Function input comes from the request content.
    Message message = await GetMessageFrom(req);

    // Start MessageProcessFunctions Orchestration function
    string instanceId = await starter.StartNewAsync(MessageProcessFunctions, message);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

    return new OkResult();
}

2) Orchestration function process incoming message in this way

• Get the current User Context from the Durable Entity associated with it by ChatId
• Feed a Message to the current state, get an Action to execute
• Execute the Action Function, which will provide a response
• Send the response

[FunctionName(MessageProcessFunctions)]
public async Task RunOrchestrator([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var message = context.GetInput<Message>();

    // create unique id of DurableUserState based on user id
    var userEntity = new EntityId(nameof(DurableUserState), message.From.Id.ToString());
    var userProxy = context.CreateEntityProxy<IDurableUserState>(userEntity);

    // get user context (user state) from durable entity
    var userState = await userProxy.GetUserState();

    // restore context
    var userContext = contextFactory.RestoreContext(userState);

    // do FSM step and get action to execute
    var action = userContext.GetAction(message.Text);

    // save new state            
    userProxy.SetUserState(userContext.State.Type);

    // execute action and get response
    var response = await context.CallActivityAsync<MasterBotResponse>(action, message);

    // send response
    await context.CallActivityAsync(SendResponse, response);
}

It's important to understand how the orchestrator will process this code. You can read all technical details here, but in easy words:

1. The function executes until it meets await and then will be stopped, and another function (activity or entity) will be launched. If you have a good understanding of the async-await pattern, this is very similar to it.
2. After the other function is finished the orchestrator wakes up and re-executes the entire function from the start to rebuild the local state.

During the replay, if the code tries to call a function (or do any other async work), the Durable Task Framework consults the execution history of the current orchestration. If it finds that the activity function has already executed and yielded a result, it replays that function's result and the orchestrator code continues to run.

With this in mind, here how the function calls look like:

[2022-07-22T00:05:23.459Z] Executing 'FeedbackBotsWeebhook' (Reason='This function was programmatically called via the host APIs.', Id=69435207-90fa-4da5-97b5-d15d2aa2c4fb)
[2022-07-22T00:05:23.472Z] C# HTTP trigger function processed a webhook.
[2022-07-22T00:05:23.559Z] Got message: User sent message 53 to chat ... at 22.07.2022 0:05:23. It is a reply to message  and has 1 message entities.
[2022-07-22T00:05:23.682Z] Started orchestration with ID = '7eb2fffba7a54e979c7cf05666812f28'.
[2022-07-22T00:05:23.698Z] Executed 'FeedbackBotsWeebhook' (Succeeded, Id=69435207-90fa-4da5-97b5-d15d2aa2c4fb, Duration=270ms)
[2022-07-22T00:05:23.813Z] Executing 'MessageProcessFunctions' (Reason='(null)', Id=f04ab79e-8cf3-42cf-a38b-99ac7ce0b594)
[2022-07-22T00:05:23.892Z] Executed 'MessageProcessFunctions' (Succeeded, Id=f04ab79e-8cf3-42cf-a38b-99ac7ce0b594, Duration=92ms)
[2022-07-22T00:05:24.000Z] Executing 'DurableUserState' (Reason='(null)', Id=46997e18-95a9-4523-af0c-3fc029a17b8c)
[2022-07-22T00:05:24.045Z] Executed 'DurableUserState' (Succeeded, Id=46997e18-95a9-4523-af0c-3fc029a17b8c, Duration=45ms)
[2022-07-22T00:05:24.089Z] Executing 'MessageProcessFunctions' (Reason='(null)', Id=6308c902-06eb-4c25-953e-2a95690d39a5)
Context: Transition to MainState.
[2022-07-22T00:05:28.187Z] Executed 'MessageProcessFunctions' (Succeeded, Id=6308c902-06eb-4c25-953e-2a95690d39a5, Duration=4098ms)
[2022-07-22T00:05:28.232Z] Executing 'DurableUserState' (Reason='(null)', Id=6d918bbe-f647-4c6a-bb22-b8c185512922)
[2022-07-22T00:05:28.241Z] Executed 'DurableUserState' (Succeeded, Id=6d918bbe-f647-4c6a-bb22-b8c185512922, Duration=9ms)
[2022-07-22T00:05:28.254Z] Executing 'ActivityWelcome' (Reason='(null)', Id=ca71be23-192c-4881-8483-84316492425f)
[2022-07-22T00:05:28.264Z] Executed 'ActivityWelcome' (Succeeded, Id=ca71be23-192c-4881-8483-84316492425f, Duration=14ms)
[2022-07-22T00:05:28.313Z] Executing 'MessageProcessFunctions' (Reason='(null)', Id=64f4b18d-746f-48ef-a039-e309be39b63e)
Context: Transition to MainState.
[2022-07-22T00:05:33.383Z] Executed 'MessageProcessFunctions' (Succeeded, Id=64f4b18d-746f-48ef-a039-e309be39b63e, Duration=5069ms)
[2022-07-22T00:05:33.417Z] Executing 'ActivitySendResponse' (Reason='(null)', Id=3da5cf30-be33-463f-804c-36791a791a1e)
Feedback Bots Master sent message 54 to chat ... at 22.07.2022 0:05:34. It is a reply to message  and has  message entities.
[2022-07-22T00:05:33.795Z] Executed 'ActivitySendResponse' (Succeeded, Id=3da5cf30-be33-463f-804c-36791a791a1e, Duration=380ms)
[2022-07-22T00:05:33.832Z] Executing 'MessageProcessFunctions' (Reason='(null)', Id=23177e66-1113-43c7-9a56-8a8f3391083c)
Context: Transition to MainState.
[2022-07-22T00:05:33.845Z] Executed 'MessageProcessFunctions' (Succeeded, Id=23177e66-1113-43c7-9a56-8a8f3391083c, Duration=13ms)

Note that message from restoring context Context: Transition to MainState. was repeated 3 times here. That's because MessageProcessFunctions was relaunched 3 times. This is why the orchestrator function code must be deterministic - always returns the same value given the same input, no matter when or how often it's called.

Activity Functions

For simplicity, I combined all state's activity functions under a single class, except ActivitySendResponse. Activity functions are a place where all hard work is done. They are designed to consume Telegram messages, process them in some way, and return responses.

For example DoAdd function read client input, extracts token from it, and attach a new chatbot.

[FunctionName(nameof(ActivityDoAdd))]
public async Task<MasterBotResponse> ActivityDoAdd([ActivityTrigger] Message message, ILogger log)
{
    log.LogInformation($"Adding client bot for {message.From.Id}");
    var botToken = Regex.Match(message.Text, "[0-9]+:[a-zA-Z0-9_-]{35}").Value;
    var bot = await _telegramService.GetBot(botToken);

    await _database.AddUserTokenAsync(message.From.Id, botToken, bot.Id, bot.Username);
    await _telegramService.Setup(message.From.Id, botToken);

    return new MasterBotResponse($"Chatbot {bot.Username} attached as a client bot");
}

And DoRemove do the opposite

[FunctionName(nameof(ActivityDoRemove))]
public async Task<MasterBotResponse> ActivityDoRemove([ActivityTrigger] Message message, ILogger log)
{
    log.LogInformation($"Removing client bot for {message.From.Id}");

    var botToken = await _database.GetMasterBotToken(message.From.Id);
    var bot = await _telegramService.GetBot(botToken);
    await _telegramService.UnSetup(botToken);

    return new MasterBotResponse($"Chatbot {bot.Username} detached as client bot");
}

I like how every activity function becomes an independent testable piece of functionality. Separation of concerns at its best.

Storage

Because I love to try new things I decided to try PlanetScale as a database for the project.

First of all, I love when a database is compatible with something common used. It's frustrating to have a custom API for each DB out there. But this usually comes with some trade-off, fortunately, non of the existing limitations of PlanetScale will prevent us from using it in the project.

We will need a database in several places

• To store user profile
• To store user-attached bots
• To store attached bots message references (we will not store messages themselves)

For simplicity all database operations will be provided by a single service:

public interface IDatabase
{
    Task<MasterBotUser> NewMasterUser(long fromId, string userName);
    Task AddUserTokenAsync(long fromId, string botToken, long chatId, string botName);

    Task<string> GetClientBotToken(long clientBotChatId);
    Task<string> GetClientBotName(long fromId);
    Task<long> GetMasterBotChatId(string clientToken);        
    Task<long> GetMasterBotFromId(string clientToken);
    Task<string> GetMasterBotToken(long fromId);

    Task<long> SaveClientMessageReference(string clientToken, long clientId, int messageId, int resendMessagId);
    Task<ClientBotsMessageReference> GetClientMessageReference(long? messageReferenceId = default, long? messageId = default);
}

Maybe I overdid it with the atomization of getting a master bot user, it's a tiny anyway.

Database Structure

Right now our database schema contains only three tables

The banned user's table does not exist yet but will be added in the future.

To store user profile

This table will store the user profile, its limits and link paddle account for handling user subscription.

CREATE TABLE MasterBotUsers (
  FromId BIGINT NOT NULL PRIMARY KEY,
  Username varchar(255) NOT NULL,
  IsPro TINYINT NOT NULL default 0,
);

To store user-attached bots

CREATE TABLE ClientBots (
  ChatId BIGINT NOT NULL PRIMARY KEY,
  Name varchar(255) NOT NULL,
  Token varchar(255) NOT NULL,  
  MasterFromId BIGINT,
  KEY master_from_id_idx (MasterFromId)
);

To store attached bots message references

Here we store the original message id and original token to be able to send answers, the id of resending the message to handle replies, and IsAnswered flag to use in the future for statistics.

CREATE TABLE ClientBotsMessageReference (
  Id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,

  OriginalMessageId INT NOT NULL,
  OriginalFromId BIGINT NOT NULL,
  ResendMessageId INT NOT NULL,

  IsAnswered TINYINT NOT NULL default 0,
  ClientBotChatId BIGINT,
  KEY client_chat_id_idx (ClientBotChatId)
);

Database queries

First I think about using EF here because EF Code First is very good. But in fact, most of the data manipulation is quite simple here, so I used Dapper for my SQL mapping and that's it.

I will not show you all queries, you could check them in github if you wish, only couple to understand the pattern.

Here we have an upsert operation with INSERT IGNORE for adding a new master user.

public async Task<MasterBotUser> NewMasterUser(long fromId, string userName)
{
    var masterBot = new MasterBotUser
    {
        FromId = fromId,
        Username = userName,
    };

    string sqlQuery = "INSERT IGNORE INTO MasterBotUsers (FromId, Username) VALUES(@FromId, @Username)";
    await _connection.ExecuteAsync(sqlQuery, masterBot);

    return masterBot;
}

Here we store information about attached client chatbot

public Task AddUserTokenAsync(long fromId, string botToken, long chatId, string botName)
{
    var clientBot = new ClientBot
    {
        ChatId = chatId,
        Token = botToken,
        MasterFromId = fromId,
        Name = botName
    };

    string sqlQuery = "INSERT IGNORE INTO ClientBots (ChatId, Name, Token, MasterFromId) VALUES(@ChatId, @Name, @Token, @MasterFromId)";
    return _connection.ExecuteAsync(sqlQuery, clientBot);
}

Getting MessageReferencesId

Usually in MySQL to get an auto-generated primary key value after INSERT we could use select LAST_INSERT_ID();

But instead of results, Dapper returns exception The given key '0' was not present in the dictionary when trying to execute the select. I didn't figure out why this happens and wonder if it could be a limitation on the PlanetSide part.

Official Vitess project board mentions that LAST_INSERT_ID with attributes is not supported yet, but nothing about an attributeless.

So I was forced to manually get the latest inserted value in SaveClientMessageReference:

var messageRef = new ClientBotsMessageReference
{
    OriginalMessageId = messageId,
    OriginalFromId = clientId,
    ClientBotChatId = await GetMasterBotChatId(clientToken),

    IsAnswered = false,
    ResendMessageId = resendMessagId,
};

// insert new client message ref
string sqlQuery = @"INSERT INTO ClientBotsMessageReference (OriginalMessageId, OriginalFromId, ClientBotChatId, IsAnswered, ResendMessageId) 
    VALUES(@OriginalMessageId, @OriginalFromId, @ClientBotChatId, @IsAnswered, @ResendMessageId);";
await _connection.ExecuteAsync(sqlQuery, messageRef);

// get latest ID        
var result = await _connection.ExecuteScalarAsync<long>("SELECT Id FROM ClientBotsMessageReference WHERE " +
    "OriginalMessageId = @OriginalMessageId AND OriginalFromId = @OriginalFromId AND ResendMessageId = @ResendMessageId",
    new { messageRef.OriginalMessageId, messageRef.OriginalFromId, messageRef.ResendMessageId });

return result;

Deploying

Deploying and setup of Master Chatbot might be a bit complicated at the moment. Maybe in the future, I would be able to add an ARM Template and make a one-click setup. But for now, to deploy you should do the next:

Deploy

1. Deploy Feedback bots to Azure, open Azure Function App configuration
2. Create Database tables from Database.sql in PlanetScale and publish it to production

Setup Azure Function App

1. Set Uri to a FQDN of your Azure Function App (without https://)
2. Set ConnectionString:Default to a connection string of your MySQL-compatible database
3. Create a Host key for your functions in App Keys blade of your Azure Function App
4. Set ClientId to a created key - it will be used to auth webhooks

Setup Master Bot

1. Create a Master Bot using @BotFather
2. Set MasterToken setting to the chatbot token obtained from BotFather
3. Execute api/setup function with the admin key - this will setup the webhook for your master bot
4. Send /start to master bot, check logs of MasterBotWebhook for message like Got message: User sent message 123 to chat **123456789** at 30.07.2022 22:23:14.
5. Set MasterChatId to your chat number id

Setup Client Bots Now your Master Bot is operational and you are ready to add client bots

1. Create a Client Bot using @BotFather
2. Send /add command to Master Bot
3. Send the client bot's token to a master bot, the confirmation message should return

Setup is done, now any message to the Client Bot will be forwarded to a Master Bot. Reply to the Message in Master Bot to send back an answer.

Conclusion and SaaS version

Now you have a fully functional chatbot based on Azure Durable Functions. The source code is available on GitHub with an AGPL license.

Feel free to deploy and use it for yourself.

If you don't want to bother with deployment and just want to set up your feedback chatbot I also built a SaaS version of FeedbackBots available here. It's exactly the same, only multi-tenant with a subscription.

What is the future of the project?

I like how it's looking so far. Azure grant 1 million function executions per month for free, Azure Storage costs a penny, and PlanetScale has a free plan, so I will not spend anything until (with strong if) the product gets some traction.

I'm not fully happy with that though

• My payment provider Paddle temporarily suspended my account yesterday - beautiful timing, until I provide them with some legal documents. So right now subscription does not work.
• I need to implement the Block feature, it requires a new database table and another action function.
• Add support of different types of answers: image, videos, locations (maybe even pay link?)
• I don't really like the current texts on the landing page and in a chatbot. I need to invest in some better wording.
• Maybe ProductHunt? Nah, probably it's not good enough.

Anyway, thanks for your attention, and if you have any questions feel free to contact me on the bot @FeedbackBotsSupportBot or on Twitter

Note for Hackathon Judges

The easiest way to test a FeedbackBots solution is

• use @FeedbackBotsMasterBot
• create your own client bot with @BotFather
• attach your client bot to MasterBot with /add command
• send some messages to the client bot and answer them in the master bot

Part of the game was a countdown on top, which is a separate Blazor component I made.

In this article, I will demonstrate to you how to create an easy Blazor countdown component. A full code of component available here.

Intro

A component is a self-contained portion of the user interface (UI) with processing logic to enable dynamic behavior.

Let's deep dive into this component to understand how it works and how you could make the same countdown for your Blazor app.

The countdown component consists of several parts:

• HTML Markup
• C# code
• CSS styles

Which could be isolated into separate files

• Countdown.razor
• Countdown.razor.cs
• Countdown.razor.css

Or it could be combined into a single Countdown.razor file for simplicity. But for me, isolation is a better practice, especially if I plan to expand the component further.

When we isolate code into separate files with proper naming Visual Studio will combine them under one nifty tree

HTML Markup

For markup, we have a div container and a h1 item inside of it to make our countdown big enough. We will make our container flex with CSS later to easily center our timer.

Time will be our property to hold the string value of the timer.

<div class = "clock">
    <h1>@Time</h1>
</div>

C# code

First, we need to declare the timer, field to store seconds left, and Time property for the UI part. For the timer itself dotnet provide us with several options, we will use System.Timers.Timer as the simplest one.

    private System.Timers.Timer _timer = null!;
    private int _secondsToRun = 0;

    protected string Time { get; set; } = "00:00";

To properly use it we need a Start and Stop methods to launch the timer and some kind of callback to handle time out. Note that we should manually call here StateHasChanged to notify Blazor that the component needs to redraw. This is because we call Start programmatically by code.

    [Parameter]
    public EventCallback TimerOut { get; set; }

    public void Start(int secondsToRun)
    {
        _secondsToRun = secondsToRun;

        if (_secondsToRun > 0)
        {
            Time = TimeSpan.FromSeconds(_secondsToRun).ToString(@"mm\:ss");
            StateHasChanged();
            _timer.Start();
        }
    }

    public void Stop()
    {
        _timer.Stop();
    }

The TimerOut event has an additional attribute - Parameter to make it accessible from outside of the component.

We need to set up the timer, we could make it in the OnInitialized event override

    protected override void OnInitialized()
    {
        _timer = new System.Timers.Timer(1000);
        _timer.Elapsed += OnTimedEvent;
        _timer.AutoReset = true;
    }

This timer will exist in the scope of a single user (because it's owned by a component, which is owned by a page, which exists in the scope of a single-user connection). It will tick every second, firing OnTimedEvent until stopped.

The event should decrease the number of seconds left, update the Time value and check if the timer is out to stop it and fire TimerOut event.

    private async void OnTimedEvent(object? sender, ElapsedEventArgs e)
    {
        _secondsToRun--;

        await InvokeAsync(() =>
        {
            Time = TimeSpan.FromSeconds(_secondsToRun).ToString(@"mm\:ss");
            StateHasChanged();
        });

        if (_secondsToRun <= 0)
        {
            _timer.Stop();
            await TimerOut.InvokeAsync();
        }
    }

Because the callback is invoked outside of Blazor's synchronization context, the component must wrap the logic of OnTimedEvent in ComponentBase.InvokeAsync to move it onto the renderer's (UI) synchronization context. StateHasChanged can only be called from the renderer's synchronization context and throws an exception otherwise. We do not care in what context the timer stops, so we could not wrap it.

And finally System.Timers.Timer need to be properly disposed with the component. For that, we implement IDisposable interface in our class.

public partial class Timer : ComponentBase, IDisposable
{
    ...

    public void Dispose()
    {
        _timer.Dispose();
    }
}

CSS styles

For style, we go for a simple flexbox with centered content. No additional styles are required right now. Timer.razor.css file will be bundled into {ASSEMBLY NAME}.styles.css file and included in your application.

.clock {
    color: var(--color-tone-1);
    font-family: sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    flex-grow: 1;
    overflow: hidden;
}

Usage

To use the component we simply add it to our page

<Countdown @ref="timer" TimerOut="TimerOutCallback"/>

With @ref attribute we obtain a reference to an HTML element, which we could use to call our Start and Stop methods. For example, we could start the timer after the page is rendered and display a message after it is timed out.

    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender)
        {
            timer.Start(10);
        }
    }

    protected Shared.Countdown timer;

    private void TimerOutCallback()
    {
        ...
    }

Conclusion

That concludes our countdown component. There is not much left to be done to improve codebase of it.

The visuals of the countdown might be improved but here is a catch: Blazor is not very suitable to work with CSS animation as JS does.

It is definitely possible but requires either a lot of "hacks" or JS functions to call from Blazor. Maybe one day I will deep dive into it.

But I'm ready to challenge you and prove that C# might be the best first language and you should consider starting your developer path from it.

I worked with it for more than 10 years, and tried almost anything: Desktop, IoT, Mobile, Web, Cloud - and everywhere C# and .NET perfectly fitted (except maybe early days of Xamarin TBH), and here are my thoughts about it.

C# is a programming language, .NET is a software framework built upon it. For simplicity when I say C# I assume it with combination with .NET and vice versa.

1. .NET allows you to build anything everywhere.

With a single language and a single framework you could build any kind of application: Desktop and Mobile, you can create games, and explore AI. And .NET is cross-platform: you could build applications for Windows, Linux, Android, iOS, and even for IoT devices. That's a lot when you are not sure where you want to move next.

Imagine that you could adopt a single language, try every direction, and improve your skills in the process. You still would need to study direction specifics though.

After that, you could improve in the direction you love most or you could even begin to work with languages and tools more specific for selected fields if you wish. For example, for mobile dev, I have seen people move from Xamarin to native development on iOS or Android.

2. C# is the fifth popular language.

According to the TIOBE Index (index of the popularity of programming languages based on search engine results), C# holds a solid 5th place as the most popular language. During the last 20 years, it has always been in the top 10.

And even more - due to fast growth in popularity this year C# might get the "TIOBE index programming language of the year award" for its highest increase in ratings in 2021.

3. C#/.NET has one of the best learning materials.

Microsoft and .NET Community provided tons of materials in any form: articles, videos, courses, tutorials, and books to give you the ability to become a successful .NET developer.

You could check all available materials on Microsoft Learning Portal

The community provides amazing all-included roadmaps to master the skills and knowledge you need to achieve success, like this ASP.NET Core roadmap for a backend developer. You could easily google roadmaps for other directions.

And Microsoft itself trying to do different fun activities to engage more developers. For example, this NFT badge is awarded to ones who proved their knowledge of building modern web apps and services with .NET 6 and Azure in the .NET Conf 2021 Cloud Skills Challenge

If you looking for where to start I recommend you to check these places

• C# 101 Course by Microsoft with Scott Hanselman and Kendra Havens
• Video tutorials by Mosh Hamedani

4. .NET 6 simplified a quick-start to the ground.

The latest version of .NET took a huge step to simplify the getting started experience. The Minimal API feature gave us a way to create HTTP APIs with minimal dependencies, in a single file, with clean code.

You need exactly 4 lines of code that can be created by a single command dotnet new web -o MinimalApiSample to start your web app with .NET 6.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

If you wish to try it for yourself check the tutorial from Microsoft.

Summary.

In conclusion, when choosing a first language you should ask yourself two questions:

1. Is it a good programming language to learn if you want to get a job?
2. Is it a good language to start learning to program?

For C# my answer is definitely yes. There is high demand for C#/.NET developers, it's a C-like language with a strong object-oriented approach, and the learning curve becomes more and more acceptable for each version.

But, as you probably already figured out, I am a fanboi 😅, so try it and decide it for yourself. Good luck in your learnings, and if you decided to join: welcome to #dotnet

To do so AAM provides an Analytics tab where all information aggregated. The problem here that this is usage analytics, not product analytics, and it's also not very convenient to use.

To solve this you could use the power of Application Insights to build a custom dashboard, or, as I prefer, built a simple reporting into a chatbot.

In this article, I describe my experience of how you could use Azure Functions to build product analytics and setup daily reports into a chatbot with it. We would connect and use Azure SDK with MSAL, HTTP-triggered and Timer-based functions, and API.chat proactive API.

Functions

You would need two Azure Functions with one ProductAnalytics service class. Service will be gathering and calculating analytics through Azure SDK and functions will provide data to the chatbot on request and on daily basis.

Service ProductAnalytics

To better understand AAM users you should monitor at least the next metrics

• DAU - daily active users, how many users use your API yesterday
• MAU - monthly active users, same but for month
• Failed Request - how many requests failed, good to find some peaks.

You would most likely need a separate set of metrics for each AAM product you have.

That's how AnalyticsResult class might look

class AnalyticsResult
 {
     public int Dau { get; set; }
     public int Mau { get; set; }
     public int FailedRequests { get; set; }
 }

Credentials

Because you would use Azure SDK, first you should get credentials to access your AAM. To do so you should register a new application on the App registrations tab of your Azure Active Directory blade

Register it with the Single tenant account type and leave Redirect Uri blank - you don't need it.

Store Client ID, Tenant ID and create new Client secret on Certificates & secrets

Auth

To authenticate the client you could use several ways. The latest, and probably the most valid, way is to use MSAL.

Starting June 30th, 2020 we will no longer add any new features to Azure Active Directory Authentication Library (ADAL) and Azure AD Graph. We will continue to provide technical support and security updates but we will no longer provide feature updates. Applications will need to be upgraded to Microsoft Authentication Library (MSAL) and Microsoft Graph.

To use it, first, you need to add an Identity package

Install-Package Microsoft.Identity.Client -Version 4.28.0

And then you should implement a token provider for AAM to use in the Azure SDK client later, like this

public class ApiManagementTokenProvider : ITokenProvider
{
    private const string ScopeApiManagement = "https://management.azure.com/.default";

    private readonly string _tenantId;
    private readonly string _clientId;
    private readonly string _clientSecret;

    public ApiManagementTokenProvider()
    {
        // Bad example here, plz don't store secrets in code
        _tenantId = "...";
        _clientId = "...";
        _clientSecret = "...";
    }

    public async Task<AuthenticationHeaderValue> GetAuthenticationHeaderAsync(CancellationToken cancellationToken)
    {
        // For app only authentication, we need the specific tenant id in the authority url
        var tenantSpecificUrl = $"https://login.microsoftonline.com/{_tenantId}/";

        // Create a confidential client to authorize the app with the AAD app
        IConfidentialClientApplication clientApp = ConfidentialClientApplicationBuilder
                                                                        .Create(_clientId)
                                                                        .WithClientSecret(_clientSecret)
                                                                        .WithAuthority(tenantSpecificUrl)
                                                                        .Build();
        // Make a client call if Access token is not available in cache
        var authenticationResult = await clientApp
            .AcquireTokenForClient(new List<string> { ScopeApiManagement })
            .ExecuteAsync();

        return new AuthenticationHeaderValue("Bearer", authenticationResult.AccessToken);
    }
}

Client

To get Analytics from AAM with Azure SDK first you need to add relevant NuGet to your project

Install-Package Microsoft.Azure.Management.ApiManagement -Version 6.0.0-preview

To get the analytics you need to use the Reports endpoint.

These endpoints get data filtered by OData, so you would need to build several queries.

To get MAU and DAU you should use ListByUsers. Note what filter operation does it support - it's quite limited, to be honest.

Check this for example. Here is 100% valid code for creating ODataFilter, even better - it's built with LINQ and SetFilter method

var filter = new ODataQuery<ReportRecordContract>()
{
    OrderBy = "callCountTotal desc"
};
filter.SetFilter(i => i.ProductId == productId && i.Timestamp >= dateOnly && i.Timestamp <= dateEnd);

Here is a resulting filter string productId eq 'unlimited' and timestamp ge '2021-03-20T21:00:00Z' and timestamp le '2021-03-21T21:00:00Z'

But this filter string is not valid for Azure SDK! The error is Invalid filter clause specified: '...'.

It needs to be modified or rewritten like so to work: (timestamp ge 2021-03-21T21:00:00.000Z and timestamp le 2021-03-22T11:29:59.999Z) and (productId eq 'unlimited'). What the difference you ask? AAM OData doesn't like single quotes around dates.

Annoying thing: AAM OData require datetime in exact 2021-03-22T11:29:59.999Z format, which is neither standard UniversalSortableDateTimePattern or SortableDateTimePattern formats of DateTime.ToString().

Another annoying thing: ODataQuery does not allow to set $select parameter. Anyway,

DAU

var dateStart = date.Date;
var dateEnd = date.Date.AddDays(1);
var filter = new ODataQuery<ReportRecordContract>($"productId eq '{productId}' and timestamp ge {dateStart:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'} and timestamp le {dateEnd:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'}")
{
    OrderBy = "callCountTotal desc"
};

MAU

var dateStart = new DateTimeOffset(date.Year,date.Month,1,0,0,0,date.Offset);
var dateEnd = date.Date.AddDays(1);
var filter = new ODataQuery<ReportRecordContract>($"productId eq '{productId}' and timestamp ge {dateStart:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'} and timestamp le {dateEnd:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'}")
{
    OrderBy = "callCountTotal desc"
};

ListByUser call returns paginated data wrapped into the IPage interface. Page 'size' be changed by setting $skip and $top parameters. And I am not sure about the default max page size. That forces us to read page by page until we get a user with zero callCountTotal - because we need only active users. Full method

private async Task<List<ReportRecordContract>> GetReports(DateTimeOffset dateStart, DateTimeOffset dateEnd, string productId)
{
    var apiManagement = new ApiManagementClient(new TokenCredentials(_tokenProvider))
    {
        SubscriptionId = _subscriptionId
    };
    var filter = new ODataQuery<ReportRecordContract>($"productId eq '{productId}' and timestamp ge {dateStart:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'} and timestamp le {dateEnd:yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'}")
    {
        OrderBy = "callCountTotal desc",
    };

    var result = new List<ReportRecordContract>();
    bool hasMore = true;

    while (hasMore)
    {
        var page = await apiManagement.Reports.ListByUserAsync(filter, _resourceGroupName, _serviceName);
        result.AddRange(page);

        hasMore = page.Any() && page.Last().CallCountTotal > 0;
    }
    return result.ToList();
};

After you got our data you could calculate metrics.

Actual Functions

First of all, to make it easier you could override ToString of the AnalyticsResult class

        public override string ToString()
        {
            var sb = new StringBuilder();

            sb.AppendLine($"_DAU_: {Dau}");
            sb.AppendLine($"_MAU_: {Mau}");
            sb.AppendLine($"_Failed_: {FailedRequests}");

            return sb.ToString();
        }

Request

Let's start with a request. This function will receive a GET request and return a bot-compatible response. It will support today(default), yesterday, and date input which would be provided by the chatbot.

[FunctionName("GetDailyReports")]
public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "reports/daily")] HttpRequest req,
            ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    DateTimeOffset date = DateTimeOffset.UtcNow.Date;
    string day = req.Query["day"];

    if (!string.IsNullOrEmpty(day) && !day.Equals("today", StringComparison.InvariantCultureIgnoreCase))
    {
        if (day.Equals("yesterday", StringComparison.InvariantCultureIgnoreCase))
            date = DateTimeOffset.UtcNow.AddDays(-1).Date;
        else
            DateTimeOffset.TryParse(day, out date);
    }

    var result = new StringBuilder();

    await AppendPlan(date, result, "*Personal Plan*", "personal");
    await AppendPlan(date, result, "*Team Plan*", "team");
    await AppendPlan(date, result, "*Business Plan*", "business");
    await AppendPlan(date, result, "*Ultimate Plan*", "ultimate");

    return new OkObjectResult(new { Messages = new List<string>() { result.ToString() } });

    static async Task AppendPlan(DateTimeOffset date, StringBuilder result, string title, string plan)
    {
        var service = new Services.AnalyticsService();
        result.AppendLine(title);
        var personalReport = await service.GetDailyAnalytics(date, plan);
        result.AppendLine(personalReport.ToString());
        result.AppendLine();
    }
}

Here you should first check the date parameter, then form an answer and send it to a user in a single message. You could split it into several messages, but IMO it would be a bit spammy.

Daily

The daily function is basically the same, but instead of responding to the chatbot, it sends a proactive message into the bot.

[FunctionName("SendDailyReport")]
public static async Task Run([TimerTrigger("0 0 13 * * ?")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");

    var date = DateTimeOffset.UtcNow.Date;
    var result = new StringBuilder($"Report for *{date:d}*.");

    await AppendPlan(date, result, "*Personal Plan*", "personal");
    await AppendPlan(date, result, "*Team Plan*", "team");
    await AppendPlan(date, result, "*Business Plan*", "business");
    await AppendPlan(date, result, "*Unlimited Plan*", "unlimited");

    // send push to a chatbot
    await SendToChatbot(result.ToString());
}

For SendToChatbot you would need to obtain Subscription-Key, set botName and channel from the API.chat developer portal. The easiest way to do that is to navigate to Proactive API page, fill all data under your account, and copy generated C# code.

To obtain your chat id send a special /chatid command to the bot.

private static async Task SendToChatbot(string message)
{
    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Cache-Control", "no-cache");
    client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{your-api-key}");

    var uri = "https://bot.api.chat/proactive/{your-bot}/{your-channel}/{your-chat-id}";

    using var content = new StringContent(JsonConvert.SerializeObject(new { Messages = new List<string>() { message } }), Encoding.UTF8, "application/json");
    var response = await client.PostAsync(uri, content);
}

Chatbot

For the chatbot, you could use my API.chat chatbot platform. The platform allows building a chatbot based on an XML-based scenario with the ability to perform third-party HTTP requests. Here is the simple scenario for the chatbot.

<bot>
  <state name="Start">
    <transition input="/report" next="Report" buttons="Today,Yesterday">Select or enter the day</transition>
    <transition input="*" next="Start" buttons="Report">echo: {msg}</transition>
  </state>
  <state name="Report">
    <transition input="*" morphology="msg" next="Start" action="http://contoso.azurewebsites.net/api/reports/daily?day={msg}"></transition>
  </state>
</bot>

User stays in Start state, send /report command and either press buttons or send a date. That will call the Azure function, provide answers and return the user into the Start state. Actually on any message in the Report state user will trigger the action. You could prevent it by expanding the scenario with regex validation of the user input.

<state name="Report">
    <transition input="today" next="Start" action="http://contoso.azurewebsites.net/api/reports/daily?day"/>
    <transition input="yesterday" next="Start" action="http://contoso.azurewebsites.net/api/reports/daily?day=yesterday"/>
    <transition input="@(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}" morphology="msg" next="Start" action="http://contoso.azurewebsites.net/api/reports/daily?day={msg}"/>
    <transition input="*" morphology="msg" next="Report">Invalid date format.</transition>
</state>

All that is left is to connect API.chat chatbot to a telegram, and test it.

Future usage

From this point, the chatbot might be expanded even more. More complex analytics reports, more data, generated charts images - anything that you might need to monitor your Azure API Management usage.

One of the obvious improvements - rewrite GetDailyReports as an asynchronous HTTP Request, because building the report might take a lot of time if you have many users.

Check Part 1 here

1. Introduction
2. Understand how to provide and monetize our API
3. Delegate SignIn/SignUp and write a code to process and redirect AAM sign-in to AAD B2C
4. Use Azure SDK REST API to create and authorize users
5. Delegate subscription management and write your own custom subscription process with Paddle.
6. Use Azure SDK REST API to manage subscriptions
7. Delegate all other operations like ChangePassword, ChangeProfile, CloseAccount, SignOut, Renew
8. Stick with as little code as possible
9. Open source solution app to save you some time

Before diving into part 2, I would like to expand Part 1 a little with recent findings.

Azure API Management Delegation verification formulas

When you delegate operations it's recommended to verify that the request is coming from Azure API Management. To do so you need to calculate the HMAC-SHA512 hash. The problem here that documentation provides hash formulas only for two operations, while there are at least four different formulas needed.

Azure API Management delegate the next operations:

public enum Operations
{
    SignUp,
    SignIn,
    ChangePassword,
    ChangeProfile,
    CloseAccount,
    SignOut,
    Subscribe,
    Unsubscribe,
    Renew
}

For validation purposes, these operations can be split into four blocks with corresponding formulas

SignIn, SignUp

HMAC(salt + '\n' + returnUrl)

ChangePassword, ChangeProfile, SignOut, CloseAccount

HMAC(salt + '\n' + userId)

Subscribe

HMAC(salt + '\n' + productId + '\n' + userId)

Renew, Unsubscribe

HMAC(salt + '\n' + subscriptionId)

GitHub user API

AAD B2C GitHub auth does not give any information about a user (which is odd, probably due to missing claims or bindings). Luckily after auth, we get a token we can use to request user data from GitHub user API. The minimal required information for new AAM users is email, name, and surname.

First, we need to ensure that our sign-up flow returns the Identity provider token

To get emails we will perform GET request on the emails endpoint

private const string GitHubApiForEmail = "https://api.github.com/user/emails";

private async Task<string> FindGitHubEmail(string accessToken, string email)
{
    if (string.IsNullOrEmpty(accessToken))
        throw new ArgumentNullException(nameof(accessToken));

    var client = new RestClient(GitHubApiForEmail);
    var request = new RestRequest(Method.GET);
    request.AddHeader("Authorization", $"Basic {Base64Encode("xakpc:" + accessToken)}");
    var gitResult = await client.ExecuteAsync(request);

    if (gitResult.IsSuccessful)
    {
        var emails = JsonConvert.DeserializeObject<List<EmailGitHub>>(gitResult.Content);
        email = emails.First(o => o.primary == true).email;
    }

    return email;
}

GitHubApiForEmail will return all user email, only one of them will be marked as primary - we would use it.

To get token from claims

httpContext.User.FindFirst(IdpAccessToken)?.Value

Filling user profile with additional data

I found out that by default Azure AD B2C fills nothing in the extended user profile. At least we need an email. If a user created a new account email is stored in the User Principal Name. But if GitHub is used for registration - it does not store at all. That limits my possibilities to reach users if needed.

To fix it I need to use Microsoft.Graph API to manually fill parameters after a user is created.

That's how you can do it

Setup secret key for App in Azure AD B2C Tenant and give it ReadAll rights

We already have an application we use for AAD B2C auth flows - we only need to create a secret key and give proper rights to it.

So we add new client secret

And read/write access to Azure Graph. Don't forget to press Grant admin consent, because we use here Client Credentials Provider for backend-only authentication.

Add NuGet Packages

To work with Graph we need to install two packages

1. Microsoft.Graph
2. Microsoft.Graph.Auth - this one is available only in preview, so check Include prerelease or use Install-Package Microsoft.Graph.Auth -PreRelease

Create client and update user after AAM

Rest you can easily peek from the docs

Build auth provider

_confidentialClientApplication = ConfidentialClientApplicationBuilder
                .Create(configuration["AzureAdB2C:ClientId"])
                .WithTenantId(configuration["AzureAdB2C:TenantId"])
                .WithClientSecret(configuration["AzureAdB2C:ClientSecret"])
                .Build();
ClientCredentialProvider authProvider = new ClientCredentialProvider(_confidentialClientApplication);

Create a user to patch

var user = new User
{
    Mail = parameters.Email,                           
};

Do update

await graphClient.Users[userId]
                    .Request()
                    .UpdateAsync(user);

Now we have all the required information about users, let's move to subscriptions.

Delegate subscription management and write your own custom subscription process with Paddle.

Subscription delegation starts with the same delegation endpoint where you can perform a redirect based on the operation.

http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

Based on the type of operation we could prepare a redirect link and navigate the user to the subscription management page.

public IActionResult OnGet()
{
    var operation = Enum.Parse<Operations>(Request.Query["operation"].FirstOrDefault());
    var returnUrl = Request.Query["returnUrl"].FirstOrDefault();

    if (!ValidateHmac(operation, returnUrl))
    {
        return Unauthorized();
    }

    switch (operation)
    {
        ...
        case Operations.Subscribe:
        case Operations.Unsubscribe:
            var urlPaddle = new UriBuilder("https", host)
            {
                Path = "PaddlePay",
                Query = Request.QueryString.Value
            };
            return Redirect(urlPaddle.Uri.ToString());
        default:
            break;
    }
}

PaddlePay page is the only page of the project that actually contains the frontend part. This is done because I use Paddle Overlay Checkout. But the frontend is extremely simple

@page
@model ApiChat.Web.Auth.Pages.PaddlePayModel
@{
    Layout = "_LayoutBack";
}

<div class="checkout-container"></div>

@{
}

Subscribe

On subscribe, AAM provides you with a product name, which should be matched to the Paddle Subscription Plan.

AAM Products

Paddle Subscription Plans

We should manually match Paddle Id with product name, for example through the dictionary

if (operation == Operations.Subscribe)
{
    UserId = HttpContext.User.FindFirst(SignInDelegationModel.NameIdentifierSchemas).Value;
    if (string.IsNullOrWhiteSpace(UserId)) return Unauthorized();

    Product = Request.Query["productId"].FirstOrDefault();
    if (string.IsNullOrWhiteSpace(Product)) return BadRequest(Product);
    ProductId = Products[Product];
    if (ProductId == 0) return BadRequest(Product);
    ...

Then we need to extract user email and optionally user Country to make the Paddle experience a bit smoother

    ...
    var user = await _apiManagementService.GetUser(UserId);
    Email = user.Email;

    var country = HttpContext.User.FindFirst("country")?.Value;
    if (country != null)
    {
        var regions = CultureInfo.GetCultures(CultureTypes.SpecificCultures).Select(x => new RegionInfo(x.LCID));
        Region = regions.FirstOrDefault(region => region.EnglishName.Contains(country))?.TwoLetterISORegionName;
    }
}

All this information will be passed to the JavaScript function OpenPaddle. You can check more about parameters here

function OpenPaddle(ProductId, UserId, ProductName, SuccessUrl, Email, Region) {
        Paddle.Checkout.open({
            product: ProductId,
            email: Email,
            country: Region,
            passthrough: UserId + ':' + ProductName,
            allowQuantity: false,
            disableLogout: true,
            success: SuccessUrl,
            closeCallback: function (data) {
                console.log(data.eventData);
                history.back();
            },
        });
    }

And to setup

@:SetupPaddle(@Model.VendorPaddle);
@:OpenPaddle(@Model.ProductId, '@Model.UserId', '@Model.Product', '@Model.ProfileUrl', '@Model.Email', '@Model.Region');

Full PaddlePay page source code.

Handle Subscription Success

To handle subscription successes you need to add a webhook - that would be the APIController POST method. This method will handle paddle answers and will use already familiar to you ApiManagementClient to create or update subscription.

[HttpPost]
public IActionResult Post()
{
    var request = new PaddleWebhookRequest(Request.Form);

    var productId = request.Passthrough.Split(':').Last();
    var userId = request.Passthrough.Split(':').First();

    // subscription processing moved to background worker for quick reply
    _backgroundQueue.Enqueue(async ct =>
    {
    Trace.TraceInformation($"Subscription alert: {request.AlertId}|{request.AlertName}|{request.Status}; User:{request.UserId}; Sub:{request.SubscriptionId}; Plan:{request.SubscriptionPlanId}");
    switch (request.AlertName)
    {
        case "subscription_created":
            if (request.Status == "active")
            {
                await AddOrUpdateProductSubscribtion(productId, userId, request.SubscriptionId, SubscriptionState.Active);
            }
            break;
     ...
      }
   }
}

Unsubscribe

Unsubscribe works similarly, but all that you have here is a subscriptionId. When you created a subscription earlier, you used the subscriptionId that Paddle provided. And to cancel it we need a cancel URL.

Usually, it comes back with a subscription webhook and should be stored, but as another option, you can request it separately for every user from Paddle API.

if (operation == Operations.Unsubscribe)
{
    var subscriptionId = Request.Query["subscriptionId"].FirstOrDefault();

    if (string.IsNullOrWhiteSpace(subscriptionId)) return BadRequest(subscriptionId);
    var user = await _paddleService.GetSubscriptionUsers(subscriptionId);

    if (user == null) return BadRequest(subscriptionId);

    CancelUrl = WebUtility.UrlDecode(user.cancel_url);
}

Use Azure SDK REST API to manage subscriptions

Here I will only show you the required methods to manage subscriptions, it's all standard.

To Subscribe you need to create and set Subscription as Active

public Task SubscribeAsync(string productId, string userId, string subscriptionId)
{
    return AddOrUpdateProductSubscribtion(productId, userId, subscriptionId, SubscriptionState.Active);
}

To Cancel you need to set the Subscription state as Cancelled.

public Task UnsubscribeAsync(string productId, string userId, string subscriptionId)
{
    return AddOrUpdateProductSubscribtion(productId, userId, subscriptionId, SubscriptionState.Cancelled);
}

And finally, we do an Upsert operation

public async Task SubscribtionCreateOrUpdateAsync(string sid, SubscriptionCreateParameters parameters)
        {
            try
            {
                var apiManagement = new ApiManagementClient(new TokenCredentials(_tokenProvider))
                {
                    SubscriptionId = _subscriptionId
                };

                await apiManagement.Subscription.CreateOrUpdateAsync(_resourceGroupName, _serviceName, sid, parameters, true);
            }
            catch (Exception ex)
            {
                Trace.TraceInformation(ex.ToString());
                throw;
            }
        }

Delegate all other operations like ChangePassword, ChangeProfile, CloseAccount, SignOut, Renew

Most of these operations will be handled by Azure AD B2C. CloseAccount and Renew are not handled by me for now, but I will probably add them in the future.

All these operations can be handled by proper redirection by our auth web app.

switch (operation)
{
    case Operations.ChangePassword:
        return Redirect($"/MicrosoftIdentity/Account/ResetPassword");
    case Operations.ChangeProfile:
        return Redirect($"/MicrosoftIdentity/Account/EditProfile");
    case Operations.CloseAccount:
        break;
    case Operations.SignOut:
        return Redirect($"/MicrosoftIdentity/Account/SignOut");
}

The only thing I want to add here is a SignOut. By default, if you use MicrosoftIdentity NuGet SignOut will redirect you to the /SignedOut page.

You don't need it, because you already have a default signed-out page of the AAM: developer portal.

To override this redirect you should replace SignedOut.cshtml, you can do it by adding a file with the same name into the same directory, like this It will produce a warning message

Warning    CS0436    The type 'Areas_MicrosoftIdentity_Pages_Account_SignedOut' in 'C:\Users\...\ApiChat.Web.Auth\obj\Debug\net5.0\Razor\Areas\MicrosoftIdentity\Pages\Account\SignedOut.cshtml.g.cs' conflicts with the imported type 'Areas_MicrosoftIdentity_Pages_Account_SignedOut' in 'Microsoft.Identity.Web.UI.Views, Version=1.6.0.0, Culture=neutral, PublicKeyToken=0a613f4dd989e8ae'. 
Using the type defined in 'C:\Users\...\ApiChat.Web.Auth\obj\Debug\net5.0\Razor\Areas\MicrosoftIdentity\Pages\Account\SignedOut.cshtml.g.cs'.    
ApiChat.Web.Auth    C:\Users\...\ApiChat.Web.Auth\obj\Debug\net5.0\Razor\Areas\MicrosoftIdentity\Pages\Account\SignedOut.cshtml.g.cs

But on the run when SignOut, it will be redirected to your page which should contain a redirect to the AAM developer portal

public IActionResult OnGet()
{
    return Redirect(AamHome.ToString());
}

Conclusion

It took me and my team almost 2 months to learn everything and create a fully operational API with Azure B2C AD, API Management, GitHub, and Paddle for API.chat.

Hope it saves you some time.

I'm tracking the number of days off each person in my company in google sheets, where I manually add/subtract their remaining days off. Can a telegram bot show them how many days off they have left once they search for their names?

The answer is yes, and here is how to do that with Google Cloud Functions and API.chat chatbot platform in under 100 lines of code.

Setup Google Functions

First, you need to set up cloud functions and give them access to our document.

Overall you will need two functions: gsheet-get to provide answers and gsheet-add to register users. Let's create them.

We do not care about the function code yet. When you set up the first function GCloud will probably ask you to enable Billing and, most importantly, will create a Service account - App Engine default service account. Usage of this account will allow you to perform server to server, app-level authentication later.

But you do need to give access rights to our document to this account.

The document itself is quite simple

Function google-sheet-add

This function will store the user channel (telegram in the case), chat id, and a name to your table. Google Functions support different languages, including .net core 3.1, but I found out that node.js gives more compact code, so let's stick to it, and sorry for dotnetish code-style

const { google } = require('googleapis');

exports.main = async (req, res) => {
  let auth = await google.auth.getClient({ scopes: ['https://www.googleapis.com/auth/spreadsheets'] });  
  let sheets = google.sheets({ version: 'v4', auth });
  try
  {
    await sheets.spreadsheets.values.append({
      spreadsheetId: "INSERT-SHEET-ID-HERE",
      range: "Days!A:C",
      valueInputOption: "RAW",
      insertDataOption: "INSERT_ROWS",
      resource: {
        values: [
          [req.query.channel, req.query.id, req.query.name]
        ],
      },
      auth: auth
    });    
    res.status(200).send();
  }
  catch (err)
  {
    res.status(500).send({ err })
  }
};

The code here will append provided values as a new row to the Days sheet. API.chat will provide user data such as channel, chat id, and the name of the user.

Don't forget to add googleapis dependency into package.json

{
  "dependencies": {
    "googleapis": "^42"
  }
}

The main need for this function is to match actual people with their telegram account. There could be more sophisticated ways to do this, but for now this simple way: ask user name - is enough.

That will give you all the required information about the user and you could start calculating his day-offs.

Function google-sheet-get

The second function is for getting data from Google Spreadsheet.

const { google } = require('googleapis');

exports.main = async (req, res) => {
  const chatId = req.query.id;
  const auth = await google.auth.getClient({ scopes: ['https://www.googleapis.com/auth/spreadsheets'] });  
  const sheets = google.sheets({ version: 'v4', auth });
  try 
  {
    let sheet = await sheets.spreadsheets.values.get({
      spreadsheetId: 'INSERT-SHEET-ID-HERE',
      range: 'Days!A:D'
    });

    const rows = sheet.data.values;
    if (rows.length) {
      let finded = rows.find(el => el[1] === chatId)      
      if (finded === undefined) {     
        res.status(200).send({ CorrelationId: req.query.request, Messages: [ "Information not availible" ] });
      } else {      
        res.status(200).send({ CorrelationId: req.query.request, Messages: [ `You have ${finded[3]} days off` ] });
      }
    } else {
      console.warn('No data found.');
      res.status(200).send({ CorrelationId: req.query.request, Messages: [ "No data found" ] });
    }
    res.status(200).send();
  }
  catch  (err)
  {
    console.error('The API returned an error: ' + err)
    res.status(500).send({ err })
  }
};

The main thing I found out here is that google.sheets API filter does not allow you to filter on actual data - only on metadata. That's why you need to get the entire sheet and filter it in code. Like I said before, API.chat will provide your endpoint with chat-id for filtering. From there you can return a formatted string with the answer like that

{
  "Messages": [
    "You have 7 days off"
  ]
}

Chatbot Scenario

Now when you have all endpoints in place and working you can create an actual chatbot. I will use my very own chatbot builder API.chat. Scenario might be very simple, like that

<bot>
  <states>
    <state name="Start">
      <transition input="register" next="Registration">Please enter your name</transition>
      <transition input="*" next="Start" pending_keyboard="Register Me">Hello. Please Register first</transition>      
    </state>
    <state name="Registration">      
      <transition input="*" next="Registered" morphology="msg" action="https://us-central1-REDACTED.cloudfunctions.net/gsheet-add?name={msg}" no_stop="true">Welcome!</transition>
    </state>
    <state name="Registered">
      <transition input="days" next="Registered" action="https://us-central1-REDACTED.net/gsheet-get" pending_keyboard="Days Off"/>
      <transition input="*" next="Registered" pending_keyboard="Days Off">Press the button to get your Days off</transition>
    </state>
  </states>
</bot>

What we do here is register the user, asking his or her name, and pass it into gsheet-add action in query. After registration user stays in the Registered state forever with the ability to request their days-off through gsheet-get action at any time.

All that's left is to PUT this scenario to the chatbot scenario endpoint and our bot is ready to deliver.

curl -v -X PUT "https://bot.api.chat/v1/bots/botName/scenario"
-H "Content-Type: application/xml"
-H "Cache-Control: no-cache"
-H "Ocp-Apim-Subscription-Key: REDACTED"
--data-raw '<bot>
  <states>
    <state name="Start">
      <transition input="register" next="Registration">Please enter your name</transition>
      <transition input="*" next="Start" pending_keyboard="Register Me">Hello. Please Register first</transition>      
    </state>
    <state name="Registration">      
      <transition input="*" next="Registered" morphology="msg" action="https://us-central1-REDACTED.cloudfunctions.net/gsheet-add?name={msg}" no_stop="true">Welcome!</transition>
    </state>
    <state name="Registered">
      <transition input="days" next="Registered" action="https://us-central1-REDACTED.cloudfunctions.net/gsheet-get" pending_keyboard="Days Off"/>
      <transition input="*" next="Registered" pending_keyboard="Days Off">Press the button to get your Days off</transition>
    </state>
  </states>
</bot>'

Let's count code lines

• google-sheet-add: 25
• google-sheet-get: 30
• scenario: 15
• overall: 70 lines of code

Not bad

Full disclosure

I am a founder of API.chat and this article is based on my and my team's experience of connecting Azure API Management, Azure AD B2C, and Paddle for the needs of my product. I hope it will be useful for you if you ever want to monetize your APIs with Azure API Management and Paddle.

Please, note

• This article will not cover the setup of Azure API Management (thereof AAM), you can read more about it here
• This article will not cover the setup of Azure AD B2C (thereof AAD B2C), you can read more about it here
• This article will not cover the setup of the Paddle

Ok, now when all this out the way, let's begin.

Introduction

In 2015 Telegram introduced chatbots and I created the first version of XML-based Telegram chatbot builder. The idea was to give developers an easy way to build and host chatbots with XML-like language. Using our builder we built what I presume was the first in the world chatbot for selling apparel for Shopify (we called it "Siri for Shop" then) - which bring us victory on HackJunction hackathon in Helsinki, Finland in 2015. In the end, chatbots didn't become the future of e-commerce but rather took some small part in that market.

Anyway, soon after that, we moved to B2E and for the past five years used and improved our platform by building chatbots for HR and internal communications (you can call it "Siri for Employees").

But the idea of providing the easy way never left me, and a couple of months ago I decided to open a platform to every developer who wants it (if any ;)). But our builder consists of 6 microservices, some queues, SQL, and no-SQL databases combined with minimal UI - purely for in-house usage. To implement the idea I would need to build an entire client-oriented web app by myself with subscription management, payments, tokens, plans, etc. And that's for a tool that might be not used by anyone except my team.

Luckily today no-code has become a mighty thing, and there are new types of no-code tools: API Management. AWS has one, Azure has one, and there are some independent solutions as well. I, as a proficient Azure user, decided to use whatever Microsoft provides.

Azure API Management

Hybrid, a multi-cloud management platform for APIs across all environments

It is a set of tools that claim that you can easily wrap your API, build a developers portal, subscription management, and much more. And that's kinda true.

The problem, like in many no-code tools, comes when you need to move from standard patterns to something not-supported by the platform - like in the case of AAM - payments and GitHub auth. Let's explore how we solved it and hopefully, you can as well.

0. The Plan

The plan was quite simple:

1. Understand how to provide and monetize our API
2. Delegate SignIn/SignUp and write a code to process and redirect AAM sign-in to AAD B2C (docs)
3. Use Azure SDK REST API to create and authorize users
4. Delegate subscription management and write your own custom subscription process with Paddle.
5. Use Azure SDK REST API to manage subscriptions
6. Delegate all other operations like ChangePassword, ChangeProfile, CloseAccount, SignOut, Unsubscribe, Renew
7. Stick with as little code as possible
8. Open source solution app to save you some time

1. Introduction to AAM and how to monetize APIs with it.

To provide our APIs I decided to wrap it to an extra-layer that normalizes it, hides internal services, and presents a clean, properly versioned, and easy-to-use API from a single point. AAM provides us API gateway to do so.

It also must have convenient documentation, subscription management, reports, and the ability to test endpoint directly from the browser. AAM provides us with a developer portal filled with these features.

To monetize our APIs we stuck to Subscription Billing, where we charge customers a flat monthly fee to access APIs, according to the selected Plan. Plan (or Product in terms of AAM) will provide the limitations: a certain number of API calls per month, maximum users, a certain APIs access, and so on.

Most of these limitations can be defined in so-called Policies - a powerful feature of the API Management platform. Not every limitation can be defined through policy though: for example, we were forced to add max users limit manually.

Users can subscribe to a Plan/Product and get access to APIs on the Product terms. By default AAM allows users to request a subscription and allows the administrator (you) to accept or decline it. And you can create a Plan/Product that can be accepted by default, like for free or trial. To be honest, that's more than enough to start - just get subscription requests, bill users manually, and approve the access.

If you want more self-service here, like us, you need to delegate subscription management to third-party service, and that's where the hard part begins. You need a preferably out-a-box solution to process payments, manage recurrent payments and subscriptions. Stripe is a nice option, or Paddle if the first one is not supported in your area.

To make it all click together you need to match your Subscriptions in payment providers to your Products in AAM. Next, you will need to set up delegation redirects and callbacks to process subscribe, unsubscribe, renew. And that can't be done without setting up sign-in and sign-up delegation first.

The overall solution might look like this

You can read a bit more about it here

2. Delegate sign-in and sign-up to Azure AD B2C.

To allow developers to sign-in and sign-up through GitHub you need to delegate these processes from AAM to a third-party web-app, your web-app. To save a lot of time we used AAD B2C for user management in the web-app. We could use AAD B2C directly in AAM, but to delegate subscriptions management, we need to delegate sign-in anyway.

As an in-between service, I chose a simple .net razor app. In fact, .net provides ready-to-use template of a web-app with built-in AAD B2C auth.

2.1 Create in-between service from template

To create a web-app from the template you should use the dotnet new command

First, install templates from NuGet

dotnet new --install Microsoft.Identity.Web.ProjectTemplates::1.5.1

Next, create a new app from the template

dotnet new AuthApp --auth IndividualB2C

Don't forget to fill in AAD B2C settings in appsettings.json. I assume that you already created AAD B2C - there are good manuals on that

  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com/",
    "ClientId": "11111111-1111-1111-1111-111111111111",
    "CallbackPath": "/signin-oidc",
    "Domain": "contoso.onmicrosoft.com",
    "SignUpSignInPolicyId": "B2C_1_Default",
    "ResetPasswordPolicyId": "B2C_1_Password_Reset",
    "EditProfilePolicyId": "B2C_1_Profile_Edit"
  }

That will give you a fully-function AAD B2C app with sign-in, sign-out, profile, and password reset features. Don't mind the design or content of the app - it will not be shown in 80% of cases. I think it might be even possible to reduce this app to a couple of controllers without any visuals whats so ever.

To ensure the app works properly with AAM you need to do an additional setup of AAD B2C and its user-flows

• In your registered App page, on the Authentication tab, you should add the URL of your localhost test server. You can add it as Web or SPA - both will work fine (at least for me). You can add a production URL as well if it's ready.

Test URL can be seen in in Properties/Debug/Web Service Settings of your project

• Ensure that you add GitHub identity provider.
• Now it's a good time to setup Company Branding as well
• You should create user-flows at this point already, but for AAM we need setup it a bit more.
• Your sign-in user-flow should have GitHub as an identity provider
• AAM requires Name and Surname not to be null, and because you add GitHub as identity provider - you need to set relevant claims as well. These are user attributes that are required for AAM for sign-up (Country is not required, you can omit it) And these are claims that I return on sign-up and profile edit user-flows (Country is optional)

Hint

What I like to do with user-flows is to create two of them for sign-in/sign-up: for prod and for debug, and disable email validation for debugging. It saves a lot of time in testing.

To do so you need to create a new user-flow, get into Page Layouts of Local Sign-Up and disable email validation (set it to No) Note that this setting will reset every time you save this user-flow for some reason, so you need to disable it on every change.

You can sign in, sign up and do all other user-related stuff.

2.2 Add delegation handler

There are several ways to add a callback handler for delegation. The easiest way IMO is to add the Razor page with the backend and handle everything in the OnGet() method.

Let's add a new Razor Page ApimDelegation.cshtml. This page will come with the model ApimDelegation.cs.cshtml and it will be your primary entry point for all delegated calls. You should not care about page content itself, only for the OnGet method.

public async Task<IActionResult> OnGet()
{
...
}

For now, you want to handle only sign-in/sign-up operations. AAD B2C built in a way that you can't navigate directly to the sign-up page (or at least I didn't found the way), so both these operations should be handled together. First, let's introduce operations enum

public enum Operations
{
    SignIn,
    SignOut,
    ...
}

All required information will come in GET request from AAM

http://www.yourwebsite.com/apimdelegation?operation=SignIn&returnUrl={URL of source page}&salt={string}&sig={string}

which is very easy to process

var operation = Enum.Parse<Operations>(Request.Query["operation"].FirstOrDefault());
var returnUrl = Request.Query["returnUrl"].FirstOrDefault();

if (!_validationService.TryValidation(Request, returnUrl))
{
    return Unauthorized();
}

validationService.TryValidation- For security reasons you are advised to verify that the request is coming from Azure API Management. sig and salt parameters are used to calculate and verify the hash. If the hash does not match, we break the execution.

If validation OK you can go to sign-in/sign-up processing:

switch (operation)
{
    case Operations.SignUp:
    case Operations.SignIn:
    var parameters = HttpUtility.ParseQueryString(string.Empty);
    parameters[SignInDelegationModel.RequestQueryRedirectUrl] = returnUrl;

    var urlBuider = new UriBuilder("https", Request.Host.Host, (int)Request.Host.Port)
    {
        Path = "SignInDelegation",
        Query = parameters.ToString()
    };
    var returnUrlAfterSignIn = urlBuider.Uri.ToString();
    return Redirect($"/MicrosoftIdentity/Account/Challenge?redirectUri={returnUrlAfterSignIn}");
}

There is a built-in SingIn method coming with the template, but it's hardcoded to redirect to ~/. Instead of the built-in method, you should use the MicrosoftIdentity/Account/Challenge method where you could provide a custom redirect endpoint to the Razor page for sign-in processing.

Now, you need to create a separate endpoint for handling successful sign-in/sign-up. The easiest way is the same - create a new Razor page SignInDelegation.cshtml and use OnGet of its code-behind.

 public async Task<IActionResult> OnGet()
 {
     var returnUrl = Request.Query[RequestQueryRedirectUrl].FirstOrDefault();
     var user = HttpContext.User;

    if (!user.Identity.IsAuthenticated)
    {
        return Unauthorized();
    }
}

Here you get your User and all his claims. Now you can create and authorize User in AAM.

At this point, you can enable delegation in AAM settings and set it up to the newly created endpoint - after that when you press sing-in in your developers portal you would be redirected to web-app, then to AAD B2C, then back to web-app, which would redirect you back to AAM.

3 Use Azure SDK to create and authorize users

After you get authenticated User you can create it in AAM and authorize it. There are two options for how you can create a user: Management API available through AAM settings and Azure Resource Manager (ARM) available through Azure SDK You should never use Management API. In fact, there should not be any Management API - because it does not even have documentation available anymore anywhere. You can make fun of my frustration about that fact in this Twitter thread.

3.1 Azure Resource Manager (ARM) setup

ARM is used in the web-app through Azure SDK package Microsoft.Azure.Management.ApiManagement. It allows you to perform any operation that can be performed through portal UI and sometimes even more. There are separate packages for each service, but we interested only in AAM, and for now - only users

To use ARM REST API first you need to create an Application and service principal in Azure Tenant and provide access to AAM through this application. To do so you should navigate to Azure Active Directory blade of your tenant where AAM is located, then to App Registration and create new Registration.

You should give it a name and select Accounts in this organizational directory only (ChatFirst only - Single-tenant) - all other stuff can be left by default. It's all in details explained in the documentation.

That will give you an application on behalf of which you will be executing REST requests to Azure SDK API.

Next, you need to create a Client Secret on Certificates & secrets to use for subscribing REST requests.

Overall you need the next settings

  "AzureSdkClient": {
    "ClientSecret": "your-app-secret",
    "ClientId": "your-app-client-id-from-overview",
    "TenantId": "your-app-tenant-id-from-overview"
  }

And finally, you need to give access to AAM for the created service principal (Assign Role). That will ensure that the application has access only to AAM and nothing else.

3.2 Azure Resource Manager (ARM) usage

Performing any request to Azure SDK API always requires two steps:

1. You need to acquire a token with your application credentials
2. You need to perform REST request subscribed by the token

There are so many ways to get this token it's almost exhausting. Official manuals provide this way. We didn't use it.

Instead, we go with a much simpler, but the not-recommended way by using ClientSecretCredential from Azure.Identity.

public async Task<AccessToken> GetAccessTokenAsync()
{
    var credential = new ClientSecretCredential(_tenantId, _clientId, _clientSecret);
    return await credential.GetTokenAsync(new TokenRequestContext(new[] { ScopeApiManagement }));
}

Apparently, this should not be used, so we switch to the more valid method - custom ITokenProvider implementation

public class ApiManagementTokenProvider : ITokenProvider
    {
        ...
        public ApiManagementTokenProvider(IConfiguration config)
        {
            _config = config;
        }
        public async Task<AuthenticationHeaderValue> GetAuthenticationHeaderAsync(CancellationToken cancellationToken)
        {
            // For app only authentication, we need the specific tenant id in the authority url
            var tenantSpecificUrl = $"https://login.microsoftonline.com/{_tenantId}/";
            // Create a confidential client to authorize the app with the AAD app
            IConfidentialClientApplication clientApp = ConfidentialClientApplicationBuilder
                                                                            .Create(_clientId)
                                                                            .WithClientSecret(_clientSecret)
                                                                            .WithAuthority(tenantSpecificUrl)
                                                                            .Build();
            // Make a client call if Access token is not available in cache
            var authenticationResult = await clientApp
                .AcquireTokenForClient(new List<string> { ScopeApiManagement })
                .ExecuteAsync();
            return new AuthenticationHeaderValue("Bearer", authenticationResult.AccessToken);
        }
    }

Fill free to select whatever suits you best. There is probably an even more valid way, so feel free to add it in the comments.

Anyway, the process of using Azure SDK REST API is pretty straightforward. TokenCredentials is created with token or tokenProvider, depending on what method you use.

public async Task UserCreateOrUpdateAsync(string token, string userId, UserCreateParameters parameters)
{
    try
    {
        var apiManagement = new ApiManagementClient(new TokenCredentials(_tokenProvider))
        {
            SubscriptionId = _subscriptionId
        };
        await apiManagement.User.CreateOrUpdateAsync(_resourceGroupName, _serviceName, userId, parameters);
    }
    catch (Exception ex)
    {
          Trace.TraceInformation(ex.ToString());
          throw;
    }
}

To execute the request you would need SubscriptionId, ResourceGroupName, and ServiceName - this information available in the Overview tab of your AAM in the Azure portal.

UserCreateParameters populated from user claims in SignInDelegation.OnGet

public async Task<IActionResult> OnGet()
{
   ...
    var token = await _clientCredentialService.GetAccessTokenAsync();

    var userId = HttpContext.User.FindFirst(NameIdentifierSchemas).Value;
    var isNew = HttpContext.User.FindFirst(NewUser)?.Value;

    if (bool.TryParse(isNew, out var result))
    {
        if (result)
        {
            var email = HttpContext.User.FindFirst(EMailAddress)?.Value;
            var firstName = HttpContext.User.FindFirst(GivenNameSchemas)?.Value ?? "-";
            var lastName = HttpContext.User.FindFirst(SurnameSchemas)?.Value ?? "-";
            // Create corresponding account in API Management
            await _apiManagementService.UserCreateOrUpdateAsync(token.Token, userId, new UserCreateParameters(email, firstName, lastName,
                confirmation: "signup")); // we do not need invites - so let's skip invite email
        }
    }
}

isNew claim is used to determine the need for a new user. EmailAddress, GivenNameSchemas, SurnameSchemas might be null in claims and AAD B2C, but should not be in AAM. For better UX FirstName and Surname of the user is optional on sign-up, so you should put placeholders if they missing. Users can always add them later In profile. Note, that the code example here is a bit obsolete - I use a "not proper" method of getting tokens.

3.2 Authorizing user into AAM

Authorizing into AAM works exactly how docs specified

public async Task<IActionResult> OnGet()
{
   ...
    var tokenResult = await _apiManagementService.GetSharedAccessTokenAsync(token.Token, userId, new UserTokenParameters() { Expiry = DateTime.UtcNow.AddHours(3), KeyType = KeyType.Primary });

    var parameters = HttpUtility.ParseQueryString(string.Empty);
    parameters["token"] = tokenResult.Value;
    parameters["returnUrl"] = returnUrl;
    var urlBuider = new UriBuilder
    {
        Host = _ssoUrl,
        Scheme = "https",
        Path = "signin-sso",
        Query = parameters.ToString()
    };

    return Redirect(urlBuider.Uri.ToString());
}

1. You request Shared Access Token for User for AAM through Azure SDK REST API
2. You append a returnUrl parameter to the SSO URL you have received from the API call above
3. You redirect to AAM signin-sso endpoint.

You can check the entire method here

3.3 GitHub as an identity provider in AAD B2C

While adding GitHub I found out that after singing in through GitHub there are no email or user-name in claims. It looks like AAD B2C does not add the required scope or bindings into the request - which is quite sad, because we need this information to create an AAM user.

You might solve this by adding GitHub as an OpenID provider but GitHub does not implement OpenID Connect to spec: it does not support well-known/openid-connect-discovery and you have no option to manually set endpoints in AAD B2C.

So you should use Github user API to fetch all required data, that's how we do it:

1. Set Display Name and Identity Provider Access Token in Application Claims of your User Flow
2. On GitHub auth you will get name aka username and idp_access_token aka token
3. That allows us to call GitHub user API curl -u username:token https://api.github.com/user
4. By default user API returns a public user profile, which might not have a set email curl -u username:token https://api.github.com/user/emails will return all user associated emails
5. You will need the primary one

   {
    "email": "***@gmail.com",
    "primary": true,
    "verified": true,
    "visibility": "public"
   }
   

Part two here

In this post, I want to give you some advice on how and which Bootstrap components you can wrap into .razor components to make your code simpler, easier to maintain, and expandable.

📥 Sources to this article

All these components are alterations of what I use every day in my projects. Why not share the same? In real projects, there is usually some CSS template used that could alter the component significantly.

These examples use clean Bootstrap and can be the foundation that could be altered for your CSS template. That's why I usually just copy-paste them across projects and tune to fit the current CSS template, instead of moving them to separate NuGet package;

Bootstrap has more than 20 components, but for this article, I keep only the ones that used very often and make a great example for you where to go from hereby.

• Button
• Button Group
• Card
• Progress
• Spinner
• Toast
• Modals

Next time - Form and Form Components in Blazor with MVVM

Button

The most basic component is a button. Because I use MVVM my button is based on the ICommand interface

@using System.Windows.Input

<button type="button" class="@($"btn {Class}")" @onclick="Callback" @attributes="InputAttributes">@ChildContent</button>

@code {
    [Parameter]
    public ICommand Command { get; set; }

    [Parameter]
    public RenderFragment ChildContent { get; set; }

    [Parameter]
    public string Class { get; set; } = "btn-primary";

    [Parameter]
    public object Parameter { get; set; }

    [Parameter(CaptureUnmatchedValues = true)]
    public Dictionary<string, object> InputAttributes { get; set; } = new Dictionary<string, object>();

    private void Callback()
    {
        Command?.Execute(Parameter);
    }
}

When you add action to button's ICommand AddCommand = new Command<int>(DoAdd); take notice of the action

private void DoAdd(int p)
{
    Value += p;
    StateHasChanged(); // <--- not gonna work without it
}

I found out that onaction will re-render only the component it belongs to. Even if actual action changes something from another (parent) component. But when you use ViewModel there is no need in StateHasChanged call here because the View should be subscribed to INotifyPropertyChanged anyway.

Button Group

Button group wraps several command buttons in a single neat component. I usually use it for data table editing

@using System.Windows.Input

<div class="btn-group" role="group" aria-label="Basic example">
    <CommandButton class="btn-sm btn-primary" Command="EditCommand" Parameter="Parameter">Edit</CommandButton>
    <CommandButton class="btn-sm btn-danger" Command="DeleteCommand" Parameter="Parameter">Delete</CommandButton>
</div>

@code {
    [Parameter]
    public ICommand EditCommand { get; set; }
    [Parameter]
    public ICommand DeleteCommand { get; set; }
    [Parameter]
    public object Parameter { get; set; }
}

The component is rather simple, you can use icons instead of text for a better look, but the main thing that it nicely fits Blazor's way of building tables. You could pass commands and current items to ViewModel for processing. If you have a lot of tables in your app that saves tons of space also, you get consistency across tables and can easily adapt styles in the future.

<tbody>
    @foreach (var item in Items)
    {
        <tr>
            <td>@item</td>
            <td><RowButtonGroup 
                    EditCommand="EditItemCommand" 
                    DeleteCommand="DeleteItemCommand" 
                    Parameter="item"/></td>
        </tr>
    }
</tbody>

Card

For me, the card is the primary component of any web app. This component wrap most of the basic HTML card into several optional RenderFragments. You can expand it further to add an optional card-image or list-group block.

I noticed that some folks missing the fact that you can use several RenderFragment inside your component. Well, you can and it allows you to use your components like that

<Card Title="Special title treatment">
    <Body>
        <p class="card-text">With supporting text below as a natural lead-in to additional content.</p>
        <a href="#" class="btn btn-primary">Go somewhere</a>
    </Body>
    <Footer>
        2 days ago
    </Footer>
</Card>

Please note

[Parameter(CaptureUnmatchedValues = true)]
public Dictionary<string, object> InputAttributes { get; set; } 
    = new Dictionary<string, object>();

This parameter is used on the card to catch-all unmatched attributes that you want to assign to it <div class="card @Class" @attributes="InputAttributes">. It's usually a good practice to include such catch-all property to every custom component. Saves some time on unmatched exceptions later. But be aware where you put it, for some components, it might be wise to apply attributes to the child or not apply it at all.

Progress Bar

Small component but I want to show it here as an example of the power of Blazor components and proper MVVM usage.

<div class="progress @Class" style="@(Height == null ? "" : $"height: {Height}px")">
  <div class="progress-bar" role="progressbar" style="@($"width: {Progress}%")" aria-valuenow="@Progress" aria-valuemin="0" aria-valuemax="100">@ChildContent</div>
</div>

@code {
    [Parameter]
    public string Class {get;set;}
    [Parameter]
    public int Progress {get;set;}
    [Parameter]
    public int? Height {get;set;}
    [Parameter]
    public RenderFragment ChildContent { get; set; }
    [Parameter(CaptureUnmatchedValues = true)]
    public Dictionary<string, object> InputAttributes { get; set; } = new Dictionary<string, object>();
}