### Developer Setup Configuration: configuration.dsc.yaml

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Defines the necessary tools and SDKs for local developer setup, including Visual Studio, .NET SDK, and ILSpy.

```yaml
Visual Studio 2022 with VC++ tools (x86, x64, ARM64)
Windows 11 SDK (26100)
.NET 8.0 SDK
ILSpy (for inspecting .winmd files)
```

--------------------------------

### Example Content for libMappings.rsp

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Defines mappings between function names and their corresponding DLLs, such as mapping CreateFileW to kernel32.dll.

```text
CreateFileW=kernel32.dll
```

--------------------------------

### Example Content for emitter.settings.rsp

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Configuration for the emitter, specifying type imports, enum additions, enum flag generation, and member remapping.

```text
--typeImport, --enumAddition, --enumMakeFlags, --memberRemap
```

--------------------------------

### Example Content for supportedOS.rsp

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Specifies supported operating system platforms and versions, using the SupportedOSPlatform attribute with a version number.

```text
SupportedOSPlatform("windows5.1.2600")
```

--------------------------------

### Example Content for scraper.settings.rsp

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Shared configuration for the scraper, including options for remapping, type inclusion, exclusion, and library paths.

```text
--remap, --with-type, --exclude, --with-librarypath
```

--------------------------------

### Example Content for documentationMappings.rsp

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Provides mappings for documentation URLs, associating API elements with their online documentation links using the Documentation attribute.

```text
[Documentation("https://...")]
```

--------------------------------

### Enum Usage Annotation Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Demonstrates annotating parameters that should use enum types, using a custom macro for clarity and compatibility with existing annotation systems.

```c
// Annotate parameters that should use enum types:
// (This is conceptually what enums.json "uses" already express)
BOOL SetFileAttributesA(
    _In_ LPCSTR lpFileName,
    _W32M_anno1("enumtype", "FILE_ATTRIBUTE_FLAGS") DWORD dwFileAttributes
);
```

```c
#define _Enum_type_(name) _W32M_anno1("enumtype", #name)
```

--------------------------------

### Handle Type Annotation Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Illustrates how handle types are annotated in headers for RAII metadata, including closing APIs and invalid handle values.

```c
// Before (in autoTypes.json):
// { "Name": "HMODULE", "CloseApi": "FreeLibrary", "InvalidHandleValues": [0] }

// After (in header):
_Close_handle_with_(FreeLibrary)
_Invalid_handle_(0)
DECLARE_HANDLE(HMODULE);
```

--------------------------------

### C++ Define Group Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

Illustrates how constants are defined using #define in C++ headers. These are typically mapped to flags enums in metadata.

```cpp
#define STAP_ALLOW_NONCLIENT    (1UL << 0)
#define STAP_ALLOW_CONTROLS     (1UL << 1)
#define STAP_ALLOW_WEBCONTENT   (1UL << 2)
```

--------------------------------

### v17 Carrier-Parameter Pattern for Metadata

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

This C++ example demonstrates the v17 workaround for encoding function-level metadata by annotating the first parameter. It shows how metadata like 'func_setlasterror' and 'func_minversion' were carried.

```cpp
BOOL AltC_MetaOnFirstParam(
    __attribute__((annotate("w32m:func_setlasterror")))
    __attribute__((annotate("w32m:func_minversion=10.0.19041")))
    DWORD dwParam, HANDLE hObject);

// v17 output:
[CppAttributeList("w32m:func_setlasterror^w32m:func_minversion=10.0.19041")]
uint dwParam  // ✅ Function metadata carried on first param
```

--------------------------------

### Enum Definition Conversion Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Shows the conversion of C# define constants to a proper C enum type, including the desired structure and backwards compatibility defines.

```c
// Before (current SDK):
#define FILE_ATTRIBUTE_READONLY   0x00000001
#define FILE_ATTRIBUTE_HIDDEN     0x00000002
#define FILE_ATTRIBUTE_SYSTEM     0x00000004

// After (desired):
typedef enum FILE_ATTRIBUTE_FLAGS {
    FILE_ATTRIBUTE_READONLY = 0x00000001,
    FILE_ATTRIBUTE_HIDDEN   = 0x00000002,
    FILE_ATTRIBUTE_SYSTEM   = 0x00000004,
} FILE_ATTRIBUTE_FLAGS;
// Backwards compat #defines still present:
#define FILE_ATTRIBUTE_READONLY   FILE_ATTRIBUTE_FLAGS_FILE_ATTRIBUTE_READONLY
```

--------------------------------

### LDAP Referral Callback Structure

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/remaining-function-pointer-fixups.md

Example of a bare function typedef used as a struct field pointer. This requires a `reducePointerLevel` directive.

```c
typedef ULONG (_cdecl QUERYFORCONNECTION)(PLDAP, PLDAP, PWCHAR, ...);
// used in struct:
typedef struct LdapReferralCallback {
    QUERYFORCONNECTION *QueryForConnection;  // pointer applied at usage site
} LDAP_REFERRAL_CALLBACK;
```

--------------------------------

### Enum Declaration with Pragmas

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

This example demonstrates using custom `#pragma w32m` directives to define enum boundaries and members. This approach was rejected because `#pragma` directives do not survive into the Clang AST and would require text-level parsing.

```c
#pragma w32m enum_begin(THREAD_CREATION_FLAGS, flags)
#define THREAD_CREATE_RUN_IMMEDIATELY  0
#define THREAD_CREATE_SUSPENDED        4
#pragma w32m enum_end
```

--------------------------------

### Function Parameter with Enum Type Annotation

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

This example illustrates using the `_Enum_type_` annotation for function parameters. This approach is considered for cross-partition references where the enum type might not be directly visible, requiring emitter changes to process specific annotations.

```c
void SetThemeAppProperties(
    _Enum_type_(SET_THEME_APP_PROPERTIES_FLAGS) DWORD dwFlags
);
```

--------------------------------

### Header Inclusion Gaps Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/remaining-function-pointer-fixups.md

These JSON entries represent function pointer aliases where the declaring headers are not transitively included by the partition that scrapes them. This requires adding explicit includes to the relevant partition main.cpp files.

```json
{ "name": "LSA_GET_EXTENDED_CALL_FLAGS",                   "pointerType": "PLSA_GET_EXTENDED_CALL_FLAGS" }
{ "name": "_WHEA_ERROR_SOURCE_INITIALIZE_DEVICE_DRIVER",   "pointerType": "WHEA_ERROR_SOURCE_INITIALIZE_DEVICE_DRIVER" }
{ "name": "_WHEA_ERROR_SOURCE_UNINITIALIZE_DEVICE_DRIVER", "pointerType": "WHEA_ERROR_SOURCE_UNINITIALIZE_DEVICE_DRIVER" }
{ "name": "_WHEA_ERROR_SOURCE_CORRECT_DEVICE_DRIVER",      "pointerType": "WHEA_ERROR_SOURCE_CORRECT_DEVICE_DRIVER" }
```

--------------------------------

### Run ClangSharp for Annotation Validation

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

This command runs the ClangSharp PInvoke Generator to validate header annotations. Ensure ClangSharpPInvokeGenerator is installed and available in your PATH. The `--additional` flags are crucial for mimicking the real build environment.

```powershell
ClangSharpPInvokeGenerator `
  --file main.cpp --output output.cs --namespace Test --methodClassName Apis `
  --include-directory <sdk-inc-dirs> `
  --traverse test_annotations.h `
  --additional "-D_USE_DECLSPECS_FOR_SAL=1" `
  --additional "-D_PREFAST_=1" `
  --additional "-D_WIN32METADATA_=1" `
  --additional "-D_AMD64_=1" --additional "-m64" `
  --config compatible-codegen `
  --config generate-cpp-attributes `
  --config exclude-funcs-with-body
```

--------------------------------

### Root Build Properties: Directory.Build.props

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Sets default build configurations, output paths, package locations, and versioning strategy using Nerdbank.GitVersioning.

```xml
<Project>
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <OutputPath>bin\$(Configuration)\</OutputPath>
    <PackageOutputPath>bin\Packages\$(Configuration)\NuGet\</PackageOutputPath>
    <ToolsTarget>net8.0</ToolsTarget>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Nerdbank.GitVersioning" Version="3.5.119" />
  </ItemGroup>
  <PropertyGroup>
    <LastWin32MetadataReleaseVersion>69.0.7-preview</LastWin32MetadataReleaseVersion>
  </PropertyGroup>
</Project>
```

--------------------------------

### Top-Level Build Script: DoAll.ps1

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Orchestrates the entire build process, including cleaning outputs, restoring dependencies, scraping headers, building .winmd files, packaging, and running tests.

```powershell
DoAll.ps1
├── Get-VSPath.ps1              # Validate VS is installed
├── CleanOutputs.ps1            # (optional) Clean previous outputs
├── CommonUtils.ps1             # Load shared utilities
│   └── Install-BuildTools      # dotnet restore/build BuildTools
├── BuildMetadataBin.ps1        # Scrape headers + emit .winmd
│   ├── GenerateMetadataSource  # (internal) ClangSharp scraping
│   └── dotnet build EmitWinmd  # Compile C# → .winmd
├── DoPackages.ps1              # Pack NuGet packages
├── DoSamples.ps1               # Build C++ and C# samples
└── DoTests.ps1                 # Run all tests
    ├── dotnet test MetadataUtils.Tests
    └── TestWinmdBinary.ps1
        ├── dotnet test Windows.Win32.Tests
        └── CompareBinToLastRelease.ps1
```

--------------------------------

### Enum Declaration with Renamed Members

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

Example of an enum where member names differ from their corresponding #define macros. The preprocessor resolves the values correctly.

```cpp
enum class SET_THEME_APP_PROPERTIES_FLAGS : DWORD {
    ALLOW_NONCLIENT  = STAP_ALLOW_NONCLIENT,   // preprocessor resolves to 1
    ALLOW_CONTROLS   = STAP_ALLOW_CONTROLS,     // preprocessor resolves to 2
    ALLOW_WEBCONTENT = STAP_ALLOW_WEBCONTENT,    // preprocessor resolves to 4
};
```

--------------------------------

### DoAll.ps1 Key Parameters

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Common parameters for the DoAll.ps1 script to control the build process, such as cleaning, excluding components, and specifying architecture.

```powershell
-Clean, -ExcludePackages, -ExcludeTests, -ExcludeSamples, -SkipInstallTools, -arch (crossarch|x64|x86|arm64)
```

--------------------------------

### C# Flags Enum Example

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

Shows the equivalent representation of a C++ #define group as a C# flags enum in the metadata. This is the target format for constants.

```csharp
[Flags]
public enum SET_THEME_APP_PROPERTIES_FLAGS : uint {
    ALLOW_NONCLIENT  = 1,
    ALLOW_CONTROLS   = 2,
    ALLOW_WEBCONTENT = 4,
}
```

--------------------------------

### Update API Docs

Source: https://github.com/microsoft/win32metadata/blob/main/apidocs/README.md

Run these commands from the root of the repo to update the packed API documentation to the latest available version. Ensure you are in the 'ext\sdk-api' directory before executing git commands.

```cmd
cd ext\sdk-api
git fetch
git checkout origin/docs
cd ..
git add ext\sdk-api
```

--------------------------------

### Coexistence of SAL and Custom Annotations

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

Demonstrates how standard SAL annotations and custom Win32metadata annotations are handled together.

```APIDOC
## SAL + Custom Annotations Coexist

### Description
This example shows how both standard SAL annotations (like `_In_`, `_Out_`) and custom Win32metadata annotations (`_Sets_last_error_`, `_Com_out_ptr_w32m_`) are preserved and represented in the generated code.

### Method
N/A (Documentation of annotation usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```c
_Sets_last_error_
_Min_os_version_(10.0.10240)
BOOL TestWithSAL(
    _In_ LPCSTR lpFileName,
    _Out_ DWORD* pdwResult,
    _Com_out_ptr_w32m_ void** ppInterface);
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
```csharp
[NativeAnnotation("w32m:setlasterror")]
[NativeAnnotation("w32m:minversion=10.0.10240")]
public static extern int TestWithSAL(
    [CppAttributeList("Name=SAL_name; p1=\"_In_\"...")]
    [NativeAnnotation("Name=SAL_name; ...")]
    sbyte* lpFileName,
    ...
    [NativeAnnotation("w32m:comoutptr")]
    void** ppInterface);
```
```

--------------------------------

### SAL Annotation Expansion

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Illustrates how SAL annotations expand to nothing when no analysis tool is running (e.g., `_PREFAST_` is not defined), ensuring zero compilation cost.

```c
// When no analysis tool is running (_PREFAST_ not defined):
// All of the above expand to nothing — zero cost
```

--------------------------------

### Define a Native Typedef in autotypes.json

Source: https://github.com/microsoft/win32metadata/blob/main/CONTRIBUTING.md

Example of defining a native typedef for `BCRYPT_KEY_HANDLE` in `autotypes.json`. This specifies the underlying value type, the API to close the handle, and an invalid handle value.

```json
{
  "Name": "BCRYPT_KEY_HANDLE",
  "ValueType": "void*",
  "CloseApi": "BCryptDestroyKey",
  "AlsoUsableFor": "BCRYPT_HANDLE",
  "InvalidHandleValues": [ 0 ],
  "NativeTypedef": true
}
```

--------------------------------

### Build System Requirements: global.json

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Specifies the .NET SDK and MSBuild SDK versions required for the project. Ensures consistent build environments.

```json
{
  "sdk": {
    "version": "8.0.417",
    "rollForward": "feature"
  },
  "msbuild-sdks": {
    "Microsoft.Build.NoTargets": "3.0.4",
    "Microsoft.Build.Traversal": "3.0.23",
    "Microsoft.Windows.WinmdGenerator": "0.3.11-preview"
  }
}
```

--------------------------------

### Local Win32 Metadata Build Workflow

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

This script orchestrates the complete local build process for Win32 metadata. It includes validation, cleaning, building, packaging, and testing stages.

```powershell
DoAll.ps1
  1. Validate VS installation (Get-VSPath.ps1)
  2. Optionally clean (CleanOutputs.ps1)
  3. Install build tools (dotnet restore/build BuildTools)
  4. BuildMetadataBin.ps1 -arch crossarch:
     a. GenerateMetadataSource for each arch (x64, x86, arm64):
        - ClangSharp scrapes partition headers → C# files per arch
        - ConstantsScraper extracts constants → C# files (x86 only)
     b. EmitWinmd target:
        - CrossArchTreeMerger merges arch-specific C# files
        - NamesToCorrectNamespacesMover applies namespace overrides
        - MetadataSyntaxTreeCleaner applies remaps, attributes, manual types
        - ClangSharpSourceWinmdGenerator writes Windows.Win32.winmd
  5. DoPackages.ps1: Pack NuGet packages
  6. DoSamples.ps1: Build sample projects
  7. DoTests.ps1:
     a. Run MetadataUtils.Tests (unit tests)
     b. Run Windows.Win32.Tests (winmd integrity tests)
     c. Compare winmd to last release (CompareBinToLastRelease.ps1)
```

--------------------------------

### CI Build Workflow for Win32 Metadata

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

This diagram illustrates the CI build process using Azure Pipelines. It shows parallel scraping tasks, a unified build stage, and automated release publishing.

```azure-pipelines
  ┌──────────┐  ┌──────────┐  ┌────────────┐
  │scrape_x64│  │scrape_x86│  │scrape_arm64│   (parallel)
  └────┬─────┘  └────┬─────┘  └─────┬──────┘
       │              │              │
       └──────────────┼──────────────┘
                      ▼
              ┌───────────────┐
              │ build_winmd   │
              │ ├─ Merge      │
              │ ├─ Emit       │
              │ ├─ Sign       │
              │ ├─ Package    │
              │ ├─ Test       │
              │ └─ Publish    │
              └───────┬───────┘
                      │ (auto-release tag)
                      ▼
              ┌───────────────┐
              │ release.yml   │
              │ ├─ GitHub     │
              │ │   Release   │
              │ └─ nuget.org  │
              │     push      │
              └───────────────┘
```

--------------------------------

### Constructor Default Remappings in PInvokeGenerator

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-plan.md

The PInvokeGenerator constructor initializes default remappings for common types like GUID, IntPtr, and UIntPtr. This ensures basic type conversions are handled automatically.

```csharp
// Constructor seeds defaults: _GUID→Guid, intptr_t→IntPtr, size_t→UIntPtr, etc.
```

--------------------------------

### Win32MetadataScraper Architecture Overview

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-plan.md

This diagram illustrates the workflow of the Win32MetadataScraper tool, highlighting its single-pass AST discovery and generation process within isolated .NET processes for each partition.

```text
┌─────────────────────────────────────────────────────────────────┐
│  ScrapeHeaders.ProcessPartition (per partition, parallel)       │
│                                                                 │
│  1. Build RSP files + CommandLineBuilder args                   │
│  2. dotnet "Win32MetadataScraper.dll" <remapsFile> @rsp1 @rsp2  │
│     └─ Own process (complete isolation)                         │
│     └─ Parses TU via CXTranslationUnit.TryParse                │
│     └─ RemapDiscovery.WalkTranslationUnit(AST)                  │
│        ├─ Discovers tag→typedef pairs                           │
│        ├─ Discovers fn ptr prototype→alias pairs                │
│        └─ Resolves & filters using heuristics                   │
│     └─ Merges auto-remaps + fn ptr fixups + configured remaps   │
│     └─ Runs PInvokeGenerator.GenerateBindings(same TU)          │
│     └─ Writes .remaps sidecar file                              │
│  3. ScrapeHeaders reads .remaps → merges into discovered sets   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              WriteAutoRemapsRsp() in Execute()
              → scraper.autoRemaps.generated.rsp (tag remaps)
              → emitter.autoFnPtr.generated.rsp (reducePointerLevel)
              (consumed on subsequent builds via @(ScraperRsp) / @(EmitterRsp))
```

--------------------------------

### Run Full Build

Source: https://github.com/microsoft/win32metadata/blob/main/CONTRIBUTING.md

Execute a full build of the project using PowerShell 7. This process can take a significant amount of time and is used to generate comprehensive winmd diffs for validation.

```powershell
.\DoAll.ps1 -Clean
```

--------------------------------

### Enum Declaration with Doxygen-style Comments

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/enum-remapping-proposal.md

This example shows using Doxygen-style comments with custom tags (`@w32m:enum`) to denote enum definitions. This method was rejected due to comments being invisible to the AST and the fragility of text-based parsing.

```c
/// @w32m:enum THREAD_CREATION_FLAGS flags
#define THREAD_CREATE_RUN_IMMEDIATELY  0
/// @w32m:enum_end
```

--------------------------------

### Integration with Build Pipeline

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Illustrates the position of the patch application step within the overall build process, occurring before ClangSharp scraping.

```text
DoAll.ps1
  1. Ingest SDK headers (from NuGet or local)
  2. ★ Apply-MetadataPatches.ps1          ← NEW STEP
  3. RecompileIdlFilesForScraping.ps1
  4. BuildMetadataBin.ps1 (scrape + emit)
  5. Tests, packaging, etc.
```

--------------------------------

### Example Remap Entries

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-plan.md

These entries in `scraper.settings.rsp` instruct ClangSharp to rename C/C++ tag names to their corresponding typedef names in the generated C# output. This is crucial for using public typedef names instead of internal ones.

```text
--remap
_BLUETOOTH_ADDRESS=BLUETOOTH_ADDRESS
tagDEC=DECIMAL
_RTL_BARRIER=SYNCHRONIZATION_BARRIER
__MIDL___MIDL_itf_foo_0001=RealTypeName
```

--------------------------------

### Patch Application Tool Workflow

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Outlines the process for applying metadata patches, including reading the manifest, locating declarations, checking for existing annotations, and updating patch status.

```text
┌─ Read patches.json for previous SDK version
│
├─ For each patch:
│   ├─ Find target declaration in new SDK header
│   ├─ Is annotation already present? ──→ Mark as "adopted by SDK"
│   ├─ Has declaration moved/renamed?  ──→ Mark as "needs review"
│   └─ Declaration still exists, no annotation ──→ Re-apply patch
│
└─ Generate migration report:
    - N patches still needed
    - M patches adopted by SDK (can be removed)
    - K patches need manual review (target moved/removed)
```

--------------------------------

### Run Incremental Build

Source: https://github.com/microsoft/win32metadata/blob/main/CONTRIBUTING.md

Performs an incremental build, excluding NuGet packages and samples for faster build times. This is useful for local development when only specific components need to be rebuilt.

```powershell
.\DoAll.ps1 -ExcludePackages -ExcludeSamples
```

--------------------------------

### C++ Main File for Annotation Testing

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

This C++ code includes the test header and defines necessary macros for ClangSharp to process annotations. The `_WIN32METADATA_` macro is essential for enabling metadata processing.

```cpp
#define _WIN32METADATA_ 1
#include <sal.h>
#include "test_annotations.h"
```

--------------------------------

### Show Namespace Cycles Output

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-plan.md

Displays the output from the showNamespaceCycles tool, highlighting cyclical dependencies between namespaces. This is useful for identifying and resolving circular references in the metadata.

```text
Windows.Win32.System.Power
  Cyclical dependent namespaces: Windows.Win32.System.SystemServices
Windows.Win32.System.SystemServices
  Cyclical dependent namespaces: Windows.Win32.System.Threading
Windows.Win32.System.Threading
  Cyclical dependent namespaces: Windows.Win32.System.Power
```

--------------------------------

### Azure Pipelines CI/CD: Main Pipeline

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Configuration for the main CI/CD pipeline, detailing jobs for scraping headers across different architectures, building the .winmd, testing, signing, and packaging.

```yaml
Main pipeline (`azure-pipelines.yml`): Triggers on `main` branch pushes/PRs (excludes `apidocs/` and `docs/`).

| Job | Description | Dependencies | 
|-----|-------------|--------------|
| `scrape_x64` | Scrape headers for x64 arch | — |
| `scrape_x86` | Scrape headers for x86 arch (+ constants) | — |
| `scrape_arm64` | Scrape headers for arm64 arch | — |
| `build_winmd` | Merge arches → build winmd → test → sign → package | All 3 scrape jobs |

The scrape jobs run **in parallel** on `windows-2022` VMs, then `build_winmd` downloads all three artifacts and produces the cross-architecture .winmd.

**Code signing**: ESRP Authenticode signing for `Windows.Win32.winmd`, SDK DLLs, and NuGet packages (only on non-PR builds with `SignFiles=true`).
```

--------------------------------

### Restore Legacy Delegate Fixups

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-plan.md

These entries were restored to `functionPointerFixups.json` as a temporary measure to maintain branch correctness while shrinking the manual file. They address legacy cases not fully solvable by structural splits.

```json
"PTHREAD_START_ROUTINE -> LPTHREAD_START_ROUTINE" (alreadyPointer: true)
```

```json
"INTERNET_STATUS_CALLBACK -> LPINTERNET_STATUS_CALLBACK" (alreadyPointer: true)
```

```json
"INSTALLUI_HANDLER_RECORD -> PINSTALLUI_HANDLER_RECORD"
```

```json
"PBMCALLBACKFN -> LPBMCALLBACKFN"
```

```json
"ACMDRIVERPROC -> LPACMDRIVERPROC"
```

```json
"PTOP_LEVEL_EXCEPTION_FILTER -> LPTOP_LEVEL_EXCEPTION_FILTER"
```

```json
"LPFNADDPROPSHEETPAGE -> LPFNSVADDPROPSHEETPAGE"
```

```json
"PFIBER_START_ROUTINE -> LPFIBER_START_ROUTINE"
```

--------------------------------

### Azure Pipelines CI/CD: API Docs Pipeline

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/research/win32metadata-detailed-research.md

Separate pipeline triggered by changes in the `apidocs/` directory to build and package API documentation.

```yaml
API docs pipeline (`azure-pipelines-apidocs.yml`): Separate pipeline triggered only by changes in `apidocs/`. Builds and packages `Microsoft.Windows.SDK.Win32Docs`.
```

--------------------------------

### Configure Function Pointer Remapping with functionPointerFixups.json

Source: https://github.com/microsoft/win32metadata/blob/main/docs/generationOptions.md

Use this JSON structure to define how function pointers should be remapped. Specify the prototype name and its corresponding pointer type. 'alreadyPointer' indicates if the original type is already a pointer.

```json
{
    "name": "PTHREAD_START_ROUTINE",
    "pointerType": "LPTHREAD_START_ROUTINE",
    "alreadyPointer": true
  }
```

```json
{
    "name": "QUERYHANDLER",
    "pointerType": "PQUERYHANDLER"
  }
```

--------------------------------

### Cabinet File Compression and Decompression Functions

Source: https://github.com/microsoft/win32metadata/blob/main/tests/MetadataUtils.Tests/assets/Cabinet.txt

This section lists the functions available for managing cabinet files, including compression, decompression, and extraction operations. Each function is mapped to the DLL that implements it.

```APIDOC
## Cabinet File API

### Description
Provides functions for creating, compressing, decompressing, and extracting cabinet files.

### Functions

- **CloseCompressor** (Cabinet.dll)
- **CloseDecompressor** (Cabinet.dll)
- **Compress** (Cabinet.dll)
- **CreateCompressor** (Cabinet.dll)
- **CreateDecompressor** (Cabinet.dll)
- **Decompress** (Cabinet.dll)
- **DeleteExtractedFiles** (Cabinet.dll)
- **DllGetVersion** (Cabinet.dll)
- **Extract** (Cabinet.dll)
- **FCIAddFile** (Cabinet.dll)
- **FCICreate** (Cabinet.dll)
- **FCIDestroy** (Cabinet.dll)
- **FCIFlushCabinet** (Cabinet.dll)
- **FCIFlushFolder** (Cabinet.dll)
- **FDICopy** (Cabinet.dll)
- **FDICreate** (Cabinet.dll)
- **FDIDestroy** (Cabinet.dll)
- **FDIIsCabinet** (Cabinet.dll)
- **FDITruncateCabinet** (Cabinet.dll)
- **GetDllVersion** (Cabinet.dll)
- **QueryCompressorInformation** (Cabinet.dll)
- **QueryDecompressorInformation** (Cabinet.dll)
- **ResetCompressor** (Cabinet.dll)
- **ResetDecompressor** (Cabinet.dll)
- **SetCompressorInformation** (Cabinet.dll)
- **SetDecompressorInformation** (Cabinet.dll)

### Notes
All listed functions are implemented in `Cabinet.dll`.
```

--------------------------------

### Combined Function and Parameter Annotations

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

Illustrates the application of multiple annotations on a single function, including those for parameters.

```APIDOC
## Combined Function and Parameter Annotations

### Description
Shows how various annotations, including those for function behavior (`_Sets_last_error_`, `_Min_os_version_`, `_Must_close_with_`) and parameter types (`_Enum_type_`, `_Not_null_terminated_w32m_`, `_Com_out_ptr_w32m_`), are represented in the generated code.

### Method
N/A (Documentation of annotation usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```c
_Sets_last_error_
_Min_os_version_(10.0.22000)
_Must_close_with_(TestClose_Combined)
HANDLE TestCombined(
    _Enum_type_(CREATE_FLAGS) DWORD dwFlags,
    _Not_null_terminated_w32m_ LPCSTR lpData,
    DWORD cbData,
    _Com_out_ptr_w32m_ void** ppResult);
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
```csharp
[NativeAnnotation("w32m:setlasterror")]
[NativeAnnotation("w32m:minversion=10.0.22000")]
[NativeAnnotation("w32m:raiifree=TestClose_Combined")]
public static extern void* TestCombined(
    [NativeAnnotation("w32m:enumtype=CREATE_FLAGS")] ...,
    [NativeAnnotation("w32m:notnullterm")] ...,
    ...,
    [NativeAnnotation("w32m:comoutptr")] ...);
```
```

--------------------------------

### MSBuild Target Frameworks Configuration

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/refactoring-plan.md

Configure multi-target .NET frameworks in an MSBuild project file. This allows the project to be compatible with both older (.netstandard2.0) and newer (.net8.0) .NET runtimes.

```xml
<TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
```

--------------------------------

### Combined Function and Parameter Annotations in v18

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/annotation-validation-results.md

Illustrates the translation of combined function-level annotations (`_Sets_last_error_`, `_Min_os_version_`, `_Must_close_with_`) and parameter annotations (`_Enum_type_`, `_Not_null_terminated_w32m_`, `_Com_out_ptr_w32m_`) into `[NativeAnnotation]` attributes.

```c
_Sets_last_error_
_Min_os_version_(10.0.22000)
_Must_close_with_(TestClose_Combined)
HANDLE TestCombined(
    _Enum_type_(CREATE_FLAGS) DWORD dwFlags,
    _Not_null_terminated_w32m_ LPCSTR lpData,
    DWORD cbData,
    _Com_out_ptr_w32m_ void** ppResult);

```

```csharp
[NativeAnnotation("w32m:setlasterror")]                  // ✅ function
[NativeAnnotation("w32m:minversion=10.0.22000")]         // ✅ function
[NativeAnnotation("w32m:raiifree=TestClose_Combined")]   // ✅ function
public static extern void* TestCombined(
    [NativeAnnotation("w32m:enumtype=CREATE_FLAGS")] ..., // ✅ param
    [NativeAnnotation("w32m:notnullterm")] ...,           // ✅ param
    ...,
    [NativeAnnotation("w32m:comoutptr")] ...);            // ✅ param

```

--------------------------------

### C# RemapDiscovery Based on AST

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/auto-type-remappings-second-opinion.md

This C# code indicates that the remapping discovery process is based on structural Abstract Syntax Tree (AST) relationships rather than raw text scanning.

```csharp
sources\Win32MetadataScraper\RemapDiscovery.cs
```

--------------------------------

### SDK Header to Generated C# Transformation

Source: https://github.com/microsoft/win32metadata/blob/main/docs/copilot/plans/shift-left-metadata-plan.md

Illustrates the flow of annotations from SDK headers through ClangSharp parsing to generated C# code, highlighting the conversion of `_Sets_last_error_` to `[DllImport("kernel32.dll", SetLastError = true)]`.

```text
┌──────────────────────────────────────────────────────────────────┐
│  SDK Header (with annotations)                                   │
│                                                                  │
│  _Sets_last_error_
│  BOOL WINAPI CreateFileA(
│      _In_ LPCSTR lpFileName, ...);
│
│  With -D_WIN32METADATA_=1, expands to:
│  __attribute__((annotate("w32m:setlasterror")))
│  BOOL WINAPI CreateFileA(
│      __attribute__((annotate("Name=SAL_pre;..." ))) ...);
└────────────────────┬─────────────────────────────────────────────┘
                     │ ClangSharp parses with Clang
                     ▼
┌──────────────────────────────────────────────────────────────────┐
│  Generated C# (ClangSharp output)
│
│  [CppAttributeList("w32m:setlasterror")]
│  [DllImport("kernel32.dll", SetLastError = true)]
│  public static extern BOOL CreateFileA(
│      [In, MarshalAs(...)] string lpFileName, ...);
└────────────────────┬─────────────────────────────────────────────┘
                     │ MetadataSyntaxTreeCleaner processes
                     ▼
┌──────────────────────────────────────────────────────────────────┐
│  Cleaned C# (ready for winmd emission)
│
│  [SetLastError]                  ← converted from w32m:
│  [DllImport("kernel32.dll")]
│  public static extern BOOL CreateFileA(...);
└────────────────────┬─────────────────────────────────────────────┘
                     │ ClangSharpSourceWinmdGenerator writes
                     ▼
┌──────────────────────────────────────────────────────────────────┐
│  Windows.Win32.winmd
│  Method: CreateFileA  [SetLastError, DllImport("kernel32.dll")]
└──────────────────────────────────────────────────────────────────┘
```