APIM-Unified-AI-Gateway-Sample: Instructions file for GitHub Copilot

APIM Policy XML Guidelines

This guide provides instructions for working with Azure API Management (APIM) policy XML files.

Suggested Policy File Structure

A suggested folder structure for APIM policy files:

Infra/
└── Resources/
    ├── Policies/
    │   ├── APIPolicies/        # API policies
    │   │   └── *.xml
    │   └── ProductPolicies/    # Product-level policies
    │       └── *.xml
    └── Fragments/              # Injected policy fragments
        └── *.xml

XML Content Rules

CRITICAL: Do NOT escape XML content

When making changes to policy .xml files:

• ❌ DON'T: Add escape characters to XML content in existing or new files
• ❌ DON'T: Escape special characters like <, >, &, ", '
• ❌ DON'T: Use HTML entities (e.g., <, >, &)
• ✅ DO: Preserve the XML structure exactly as-is without escaping
• ✅ DO: Keep XML formatting clean and readable
• ✅ DO: Maintain consistent indentation

C# Expressions in Policies

APIM policies and fragments use C# expressions within @() or @{} syntax. When writing C# expressions:

• Use C# 7 syntax only - Do not use C# 8+ features
• Keep expressions concise and readable
• Do not escape characters within C# expressions
• Test expressions are syntactically valid C# 7

For valid policy expression syntax and examples, refer to: API Management policy expressions

Variable Best Practices

Use safe variable access

Use GetValueOrDefault with meaningful defaults:

<set-variable name="user" value="@(context.Variables.GetValueOrDefault<string>("user-id", "anonymous"))" />

Check variable existence

For required variables, fail fast:

<choose>
    <when condition="@(!context.Variables.ContainsKey("required-var"))">
        <return-response>
            <set-status code="500" reason="Internal Server Error" />
        </return-response>
    </when>
</choose>