Jacobi.Azure.ApiManagement.Policy 2.1.0

Azure APIM Policy CSharp

This library allows you to generate Azure API Management Policy XML files based on C# class implementations.

Usage

You implement a class for each Policy Xml file you whish to generate. The method and parameter names are kept the same as the Azure API Management Policy documentation to make it very easy to know what stuff does. See also the list of implemented policies below.

public sealed class MyPolicy : Jacobi.Azure.ApiManagement.Policy.PolicyDocument
{
    protected override void Inbound(IInbound inbound)
    {
      inbound
        .CheckHeader(...)
        .IpFilter(...)
        // other policies
        ;

        base.Inbound(inbound); // generates the <Base/> implicitly.
    }

    protected override void Backend(IBackend backend)
    {
        // add your policies here
        base.Backend(backend);
    }

    protected override void Outbound(IOutbound outbound)
    {
        // add your policies here
        base.Outbound(outbound);
    }

    protected override void OnError(IOnError onError)
    {
        // add your policies here
        base.OnError(onError);
    }
}

Simularly for a policy fragment:

public sealed class MyFragment : Jacobi.Azure.ApiManagement.Policy.PolicyFragment
{
    protected override void Fragment(IPolicyFragment fragment)
    {
      fragment
        .CheckHeader(...)
        .IpFilter(...)
        // other policies
        ;
      
      // no need to call the base
    }
}


When the project is built (successfully) a Policy XML file will be generated for each class - with the same file name (.xml) as the class.

Note that the resulting dotnet assembly is not used in anyway.

## Policy Expressions

Any values that can be an expression (either code or a literal value) is represented by the `PolicyExpression` class.

There are two implementation of this class:

- `PolicyExpression<T>` that is used in the interface method declarations to indicate whet data type is ultimately expected for the value. Although at this point, the return-type of any code is not verified, some validation takes place - it servers more as documentation.
- `PolicyExpression` is the type you typically use when constructing expressions.

An example of specifying a code expression using the `PolicyExpression.FromCode` would be:

```csharp
public sealed class MyPolicy : Jacobi.Azure.ApiManagement.Policy.PolicyDocument
{
    protected override void Inbound(IInbound inbound)
    {
      inbound
        .Choose(choose =>
            choose.When(PolicyExpression.FromCode("""Context.Variables.GetValueOrDefault<bool>("myvar", true)"""),
                actions => actions.SetBody(LiquidTemplate.From(""" body """))))
        base.Inbound(inbound);
    }
}

Note the use of the LiquidTemplate struct. Support for Liquid-templates is very rudementary and serves basically as a way to distinguish between PolicyExpression and LiquidTemplate strings.

Policies Implemented

• authentication-basic
• authentication-certificate
• authentication-managed-identity
• azure-openai-emit-token-metric
• azure-openai-semantic-cache-lookup
• azure-openai-semantic-cache-store
• azure-openai-token-limit
• cache-lookup
• cache-lookup-value
• cache-store
• cache-store-value
• cache-remove-value
• check-header
• choose
• cors
• cosmosdb-data-source
• cross-domain
• emit-metric
• find-and-replace
• forward-request
• get-authorization-context
• http-data-source
• include-fragment
• invoke-dapr-binding
• ip-filter
• jsonp
• json-to-xml
• limit-concurrency
• llm-content-safety
• llm-emit-token-metric
• llm-semantic-cache-lookup
• llm-semantic-cache-store
• llm-token-limit
• log-to-eventhub
• mock-response
• proxy
• publish-event
• publish-to-dapr
• quota
• quota-by-key
• rate-limit
• rate-limit-by-key
• redirect-content-urls
• retry
• return-response
• rewrite-uri
• send-one-way-request
• send-service-bus-message
• send-request
• set-backend-service
• set-backend-service-dapr
• set-body
• set-header
• set-method
• set-query-parameter
• set-status
• set-variable
• sql-data-source
• trace
• validate-azure-ad-token
• validate-client-certificate
• validate-content
• validate-graphql-request
• validate-headers
• validate-jwt
• validate-odata-request
• validate-parameters
• validate-status-code
• wait
• xml-to-json
• xsl-transform

Policy XML Files Output Folder

By default the generated policy XML files are written to the PolicyXml folder in the project root folder. However this can be easily changed by specifying an override in your .csproj file.

<PropertyGroup>
  <PolicyXmlOutputFolder>$(TargetPath)\MyCustomPolicyXmlFolder</PolicyXmlOutputFolder>
</PropertyGroup>

Replacement tokens (macros) can be used to build a folder path to where the policy xml files will be written. This example creates a new 'MyCustomPolicyXmlFolder' folder in the build-output folder next to the binaries.

TODO

For transparency:

• Variables: check exists (variable-references in policies are typically created on demand)
• Variables: Typed - to check the 'structure' of variables
• PolicyExpression: TypeHint to document expected (result) type of literal or code expression
• CodeExpression: {{named-value}} in code. Compiler will fail.
• CodeExpression Compiler: (string)Context.Variables["connectionId"] error CS0201: Only assignment, call, increment, decrement, await, and new object expressions can be used as a statement (suppressed for now)
• Int32: validate non-negative or use uint.
• Fragment scope: unclear what policies can (not) go in fragments
• XslTransform: represent the xslt as something else than a plain string?
• Keep track of the number of policy uses per document (for instance: cors can only be used once).