Paste a Windows header as it is

Intermediate · C#. SDK spellings, a tagged typedef with two aliases, a tagged inline union whose members are promoted, _ padding fields, and a PWSTR pointer compile as pasted from a Windows header or a dissect definition.

Run this example

Prerequisites: the repository's .NET 10 SDK and a checkout of this source. Run from the repository root:

dotnet run --project docs/examples/CStructSharp.Docs.Examples.csproj -c Release -- windows-header

The runner checks Magic 0x5A4D, promoted union members Major 10 and Build 12345, padding absent, and a 20-byte write with zeroed padding. Success includes PASS windows-header.

Try the related browser lesson.

Complete program

The layout, options, input bytes, helper methods, and required types are all included. To adapt it outside the repository, create a .NET 10 console project, add CStructSharp, and replace Program.cs with this complete file. These examples follow the source version; use a matching package when testing a release.

Download the complete C# source.

// Generated from executable documentation examples. Edit the source region, then regenerate.
using System;
using System.IO;
using System.IO.Pipelines;
using System.Linq;
using System.Buffers;
using System.Collections.Generic;
using System.Dynamic;
using System.Globalization;
using System.Numerics;
using System.Runtime.CompilerServices;
using System.Threading;
using System.Threading.Tasks;
using CStructSharp;
using CStructSharp.Codecs;
using CStructSharp.Diagnostics;
using CStructSharp.Introspection;
using CStructSharp.Values;

internal static partial class Program
{
    public static void Main()
    {
        WindowsHeader();
        Console.WriteLine("PASS windows-header");
    }

    private static void WindowsHeader()
    {
        // A header pasted from a Windows SDK or a dissect definition: SDK spellings, a repeated `_` padding
        // field, a tagged inline union whose members are promoted, and a pointer-to-string alias.
        const string definition = """
            typedef struct _RECORD {
                DWORD   Magic;
                WORD    Version;
                WORD    _;
                union version_information {
                    DWORD Packed;
                    struct { BYTE Major; BYTE Minor; WORD Build; };
                };
                DWORD   _;
                PWSTR   Name;
            } RECORD, *PRECORD;
            """;
        var layout = new CStruct(definition, pointerSize: 4, aligned: true);
        byte[] bytes = [0x4D, 0x5A, 0x00, 0x00, 0x02, 0x00, 0xFF, 0xFF, 0x0A, 0x00, 0x39, 0x30, 0xEE, 0xEE, 0xEE, 0xEE, 0x00, 0x00, 0x00, 0x00];
        StructValue record = layout.Parse(bytes, "RECORD");
        Equal(0x5A4DU, record.Get<uint>("Magic"));
        Equal((ushort)2, record.Get<ushort>("Version"));
        Equal((byte)10, record.Get<byte>("Major"));
        Equal((ushort)12345, record.Get<ushort>("Build"));
        Equal(0x3039000AU, record.Get<uint>("Packed"));
        True(!record.ContainsKey("_"), "padding is not a member");

        // The tag, the alias, and the pointer alias all name the same declaration; the promoted union writes
        // back through the member the data supplies and the padding as zeroes.
        Equal(20, layout.GetStructSizeInBytes("_RECORD"));
        byte[] written = layout.Serialize("RECORD", new Dictionary<string, object?> { ["Magic"] = 0x5A4DU, ["Version"] = (ushort)2, ["Packed"] = 0x3039000AU, ["Name"] = 0U });
        SequenceEqual([0x4D, 0x5A, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x0A, 0x00, 0x39, 0x30, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00], written);
    }

    private static void Equal<T>(T expected, T actual)
    {
        if (!EqualityComparer<T>.Default.Equals(expected, actual))
        {
            throw new InvalidOperationException($"Expected '{expected}', received '{actual}'.");
        }
    }

    private static void True(bool condition, string message)
    {
        if (!condition)
        {
            throw new InvalidOperationException(message);
        }
    }

    private static void SequenceEqual(byte[] expected, byte[] actual)
    {
        if (!expected.AsSpan().SequenceEqual(actual))
        {
            throw new InvalidOperationException(
                $"Expected {Convert.ToHexString(expected)}, received {Convert.ToHexString(actual)}.");
        }
    }
}

Try it and diagnose mistakes

Change the WORD _ padding bytes FF FF to 00 00.

Answer: Nothing in the parsed values changes: padding is read and discarded, and a write always zeroes it. The program contains assertions for its original inputs. When changing an input intentionally, update the expected assertion too; an unchanged assertion is not evidence that the new value is wrong.

Continue with the related guide or choose another recipe.