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

Gateway Emulator

Naming Conventions

Authoring & Compilation

Gateway Emulator

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:

// 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:

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:

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:

Common Pitfalls

Build and Test Commands

# 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 — distributed by TomeVault.