# Policy Codebase Reference

> Reference guide for the Azure API Management policy toolkit codebase structure. Use this skill when you need to find existing policies, infrastructure, or naming conventions. Use when this capability is needed.

- Skill: `tomevault-io/policy-codebase-reference` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/policy-codebase-reference`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/policy-codebase-reference/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/policy-codebase-reference

---


# Policy Toolkit Codebase Reference

This skill provides an inventory of the codebase structure, shared infrastructure, reference policy selection, and naming conventions for the Azure API Management policy toolkit.

## File Path Conventions

### Authoring & Compilation

| Artifact | Location | Example |
|---|---|---|
| Config record | `src/Authoring/Configs/{PolicyName}Config.cs` | `RateLimitConfig.cs` |
| Document attribute | `src/Authoring/Attributes/DocumentAttribute.cs` | — |
| Expression attribute | `src/Authoring/Attributes/ExpressionAttribute.cs` | — |
| Expression-allowed attribute | `src/Authoring/Attributes/ExpressionAllowedAttribute.cs` | — |
| Section interfaces | `src/Authoring/I{Section}Context.cs` | `IInboundContext.cs` |
| Compiler class | `src/Core/Compiling/Policy/{PolicyName}Compiler.cs` | `RateLimitCompiler.cs` |
| Compiler test class | `test/Test.Core/Compiling/{PolicyName}Tests.cs` | `RateLimitTests.cs` |
| Available policies doc | `docs/AvailablePolicies.md` | — |
| Compiler utilities | `src/Core/Compiling/CompilerUtils.cs` | — |
| Syntax extensions | `src/Core/Compiling/SyntaxExtensions.cs` | — |
| Diagnostics | `src/Core/Compiling/Diagnostics/CompilationErrors.cs` | — |
| IoC / auto-registration | `src/Core/IoC/CompilerModule.cs` | — |
| Test initialization | `test/Test.Core/CompilerTestInitialize.cs` | — |
| Assertion helpers | `test/Test.Core/Assertions/` | `CompilationResultAssertion.cs` |
| Generic compiler utilities | `src/Core/Compiling/Policy/GenericCompiler.cs` | — |
| Add-policy guide | `docs/AddPolicyGuide.md` | — |

### Gateway Emulator

| Artifact | Location | Example |
|---|---|---|
| Emulator handler class | `src/Testing/Emulator/Policies/{PolicyName}Handler.cs` | `SetHeaderHandler.cs` |
| Handler base classes | `src/Testing/Emulator/Policies/PolicyHandler.cs` | — |
| IPolicyHandler interface | `src/Testing/Emulator/IPolicyHandler.cs` | — |
| Section attribute | `src/Testing/Emulator/Policies/SectionAttribute.cs` | — |
| Argument extensions | `src/Testing/Emulator/Policies/ArgumentsExtensions.cs` | — |
| Policy exception | `src/Testing/Emulator/PolicyExeption.cs` | Note: filename has typo |
| SectionContextProxy | `src/Testing/Emulator/SectionContextProxy.cs` | — |
| GatewayContext | `src/Testing/GatewayContext.cs` | — |
| TestDocument | `src/Testing/TestDocument.cs` | — |
| Emulator test class | `test/Test.Testing/Emulator/Policies/{PolicyName}Tests.cs` | `SetHeaderTests.cs` |
| Emulator policy checklist | `docs/EmulatorPolicyChecklist.md` | — |

## Naming Conventions

### Authoring & Compilation

| Artifact | Convention | Example |
|---|---|---|
| Config record | `{PolicyName}Config` | `RateLimitConfig` |
| Sub-config record | `{DescriptiveName}` | `ApiRateLimit`, `AddressRange` |
| Compiler class | `{PolicyName}Compiler` | `RateLimitCompiler` |
| Compiler test class | `{PolicyName}Tests` | `RateLimitTests` |
| Context method | `{PolicyName}` | `RateLimit` |
| XML element name | kebab-case | `rate-limit` |
| Config namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Authoring` | — |
| Compiler namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy` | — |
| Compiler test namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling` | — |

### Gateway Emulator

| Artifact | Convention | Example |
|---|---|---|
| Handler class | `{PolicyName}Handler` | `SetHeaderHandler` |
| Emulator test class | `{PolicyName}Tests` | `SetHeaderTests` |
| PolicyName property | PascalCase method name from section interface | `SetHeader` |
| Handler namespace | `Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Policies` | — |
| Emulator test namespace | `Test.Emulator.Emulator.Policies` | — |

> **Note:** `JsonToXmlHandle.cs` is a naming inconsistency in the source (missing the `r` in `Handler`). Do not rename it.

## Copyright Header

Every new `.cs` file must start with:

```csharp
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
```

## Reference Policy Selection Guide

When implementing a new policy, choose the closest structural match as your reference:

| Policy Structure | Reference Config | Reference Compiler | Reference Tests |
|---|---|---|---|
| Simple attributes only | `RateLimitByKeyConfig` | `RateLimitByKeyCompiler` | `RateLimitByKeyTests` |
| Attributes + child elements | `RateLimitConfig` | `RateLimitCompiler` | `RateLimitTests` |
| Attributes + typed child arrays | `IpFilterConfig` | `IpFilterCompiler` | `IpFilterTests` |
| String-list child elements | `ValidateJwtConfig` | `ValidateJwtCompiler` | `ValidateJwtTests` |
| Complex nested configs | `CorsConfig` | `CorsCompiler` | `CorsTests` |
| Direct parameters (no config) | — | `SetMethodCompiler` | `SetMethodTests` |

## Shared Infrastructure Inventory

### Expression Support

- **`[Document]`** attribute (`src/Authoring/Attributes/DocumentAttribute.cs`) — Marks a class as a policy document. Optional `name` parameter; `Scope` and `Type` properties control document scope and type.
- **`[Expression]`** attribute (`src/Authoring/Attributes/ExpressionAttribute.cs`) — Marks a method as a policy expression helper. Captures source file path via `[CallerFilePath]`.
- **`[ExpressionAllowed]`** attribute (`src/Authoring/Attributes/ExpressionAllowedAttribute.cs`) — Marks properties or parameters that accept policy expressions.
- **`Expression<T>`** delegate (`src/Authoring/Expression.cs`) — `delegate T Expression<out T>(IExpressionContext context)`.
- **`IHaveExpressionContext`** interface (`src/Authoring/IHaveExpressionContext.cs`) — Base interface for all section contexts, providing `IExpressionContext ExpressionContext { get; }`.

### Compiler Infrastructure

- **`IMethodPolicyHandler`** interface (`src/Core/Compiling/IMethodPolicyHandler.cs`) — The primary compiler interface. Properties: `string MethodName { get; }`. Method: `void Handle(IDocumentCompilationContext context, InvocationExpressionSyntax node)`.
- **`IReturnValueMethodPolicyHandler`** interface (`src/Core/Compiling/IReturnValueMethodPolicyHandler.cs`) — For policies returning a value. Currently disabled (the `LocalDeclarationStatementCompiler` is commented out in `CompilerModule.cs`).
- **Auto-registration** (`src/Core/IoC/CompilerModule.cs`) — Uses reflection to find and register all public, non-abstract classes in the `Microsoft.Azure.ApiManagement.PolicyToolkit.Compiling.Policy` namespace that implement `IMethodPolicyHandler`. No manual DI wiring needed for standard compilers.
- **`CompilerUtils`** (`src/Core/Compiling/CompilerUtils.cs`) — Static utility class with methods for parameter extraction (`ProcessParameter`, `TryExtractingConfig`), expression processing, and syntax normalization. Also defines `InitializerValue` for property name → value mapping.
- **`SyntaxExtensions`** (`src/Core/Compiling/SyntaxExtensions.cs`) — Extension methods for Roslyn syntax trees: attribute detection (`ContainsAttributeOfType<T>`), document class discovery (`GetDocumentAttributedClasses`), and document metadata extraction.
- **`GenericCompiler.HandleList`** (`src/Core/Compiling/Policy/GenericCompiler.cs`) — Utility for compiling string arrays into repeated child XML elements.
- **`CompilationErrors`** (`src/Core/Compiling/Diagnostics/CompilationErrors.cs`) — Static class with `DiagnosticDescriptor` fields for all compilation error types.

### Compiler Test Infrastructure

- **`CompilerTestInitialize`** (`test/Test.Core/CompilerTestInitialize.cs`) — Assembly-level MSTest setup. Creates Roslyn compilation with references to `System`, `System.Xml.Linq`, and the Authoring assembly. Provides the `CompileDocument()` extension method.
- **`CompilationResultAssertion`** (`test/Test.Core/Assertions/CompilationResultAssertion.cs`) — FluentAssertions extension providing `BeSuccessful()` and `DocumentEquivalentTo(string expectedXml)`.
- **`Usings.cs`** (`test/Test.Core/Usings.cs`) — Global usings: `FluentAssertions`, `Microsoft.VisualStudio.TestTools.UnitTesting`, assertion helpers, test extensions.

### Emulator Infrastructure

- **`IPolicyHandler`** interface (`src/Testing/Emulator/IPolicyHandler.cs`) — The handler interface. Properties: `string PolicyName { get; }`. Method: `object? Handle(GatewayContext context, object?[]? args)`.
- **`PolicyHandler<T>`** base classes (`src/Testing/Emulator/Policies/PolicyHandler.cs`) — Three generic variants: single config, optional config, and two-parameter. All include `CallbackSetup` for test mocking.
- **`SectionContextProxy<T>`** (`src/Testing/Emulator/SectionContextProxy.cs`) — Uses `System.Reflection.DispatchProxy` to dynamically route method calls to handlers. Discovers handlers via reflection on namespace + `[Section]` attribute.
- **`[Section]`** attribute (`src/Testing/Emulator/Policies/SectionAttribute.cs`) — Constructor takes `string scope` (use `nameof(IInboundContext)`, etc.). Multiple attributes can be stacked.
- **`ArgumentsExtensions`** (`src/Testing/Emulator/Policies/ArgumentsExtensions.cs`) — Static utility for safe argument extraction from `object?[]?`: `ExtractArgument<T>()` (required single arg), `ExtractOptionalArgument<T>()` (nullable), and `ExtractArguments<T1, T2>()` (two-param handlers).
- **`PolicyException`** (`src/Testing/Emulator/PolicyExeption.cs`) — Exception thrown when a handler fails. Carries `Policy`, `Section`, and `PolicyArgs` context. Note: filename has a typo (`Exeption`) — do not rename.
- **`GatewayContext`** (`src/Testing/GatewayContext.cs`) — Central mock object with section proxies, mock stores (CertificateStore, CacheStore, ResponseExampleStore, LoggerStore), and expression context.
- **`TestDocument`** (`src/Testing/TestDocument.cs`) — Orchestrates test execution across policy sections. Wraps `IDocument` and calls section methods through proxies.
- **`FinishSectionProcessingException`** — Thrown by handlers (e.g., MockResponse, ReturnResponse) to terminate section processing early.

### Emulator Test Infrastructure

- **`.AsTestDocument()`** extension — Creates `TestDocument` from `IDocument` for fluent test setup.
- **`SetupInbound()`/`SetupOutbound()`/etc.** — Returns `MockPoliciesProvider<TSection>` for mock configuration.
- **`Usings.cs`** (`test/Test.Testing/Usings.cs`) — Global usings for `FluentAssertions` and MSTest.

## Section Interfaces

Policies can be available in one or more pipeline sections:

| Section | Interface File | XML Section |
|---|---|---|
| Inbound | `src/Authoring/IInboundContext.cs` | `<inbound>` |
| Outbound | `src/Authoring/IOutboundContext.cs` | `<outbound>` |
| Backend | `src/Authoring/IBackendContext.cs` | `<backend>` |
| On-Error | `src/Authoring/IOnErrorContext.cs` | `<on-error>` |
| Fragment | `src/Authoring/IFragmentContext.cs` | N/A (reusable fragment) |

Note: `IFragmentContext` duplicates method signatures from other interfaces (see `//TODO` at top of file). Copy signatures verbatim when adding policies there.

## Emulator Reference Handler Selection Guide

When implementing a new emulator handler, choose the closest structural match:

| Policy Structure | Reference Handler | Reference Test |
|---|---|---|
| Single config, simple state change | `SetStatusHandler` | `SetStatusTests` |
| Two parameters (name + values) | `SetHeaderHandler` | `SetHeaderTests` |
| Config with callback hooks only (no-op) | `RateLimitHandler` | `RateLimitTests` |
| Optional config | `MockResponseHandler` | `MockResponseTests` |
| Validation + short-circuit | `CheckHeaderHandler` | `CheckHeaderTests` |
| Authentication + token | `AuthenticationManagedIdentityHandler` | `AuthenticationManagedIdentityHandlerTests` |
| Cache interaction | `CacheLookupValueHandler` | `CacheLookupValueTests` |
| Logging/store interaction | `LogToEventHubHandler` | `LogToEventHubTests` |
| No-config (no-arg method) | `BaseHandler` | `BaseTests` |
| Custom flow control / wrapper | `ReturnResponseHandler` | — |
| AzureOpenAi variant (inherits Llm) | `AzureOpenAiEmitTokenMetricHandler` | — |

## Common Pitfalls

| Pitfall | Rule |
|---------|------|
| Modifying `.csproj` files | Do **not** change `Compiling.csproj` or `Testing.csproj` unless explicitly required. Reformatting, reordering, or encoding changes (BOM, line endings) cause noisy diffs and will be rejected in review. |
| Missing `IFragmentContext` entry | Every method added to a section interface (`IInboundContext`, `IOutboundContext`, etc.) must also be added to `IFragmentContext.cs`. See the authoring skill for details. |
| Missing expression tests | Every property marked `[ExpressionAllowed]` in a config must have a corresponding expression test `[DataRow]`. See the testing skill section 3 for the pattern. |

## Build and Test Commands

```bash
# Build the entire solution
dotnet build

# Run all compiler tests
dotnet test --project test/Test.Core

# Run all emulator tests
dotnet test --project test/Test.Testing

# Run tests for a specific policy
dotnet test --filter "FullyQualifiedName~{PolicyName}Tests"
```

---
> Source: [Azure/azure-api-management-policy-toolkit](https://github.com/Azure/azure-api-management-policy-toolkit) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->