API Management policy expressions

This article discusses policy expressions syntax is C# 7. Each expression has access to the implicitly provided context variable and an allowed subset of .NET Framework types.

For more information:

  • See how to supply context information to your backend service. Use the Set query string parameter and Set HTTP header policies to supply this information.
  • See how to use the Validate JWT policy to pre-authorize access to operations based on token claims.
  • See how to use an API Inspector trace to see how policies are evaluated and the results of those evaluations.
  • See how to use expressions with the Get from cache and Store to cache policies to configure API Management response caching. Set a duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive.
  • See how to perform content filtering. Remove data elements from the response received from the backend using the Control flow and Set body policies.
  • To download the policy statements, see the api-management-samples/policies GitHub repo.

Syntax

Single statement expressions are enclosed in @(expression), where expression is a well-formed C# expression statement.

Multi-statement expressions are enclosed in @{expression}. All code paths within multi-statement expressions must end with a return statement.

Examples

@(true)

@((1+1).ToString())

@("Hi There".Length)

@(Regex.Match(context.Response.Headers.GetValueOrDefault("Cache-Control",""), @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value)

@(context.Variables.ContainsKey("maxAge") ? int.Parse((string)context.Variables["maxAge"]) : 3600)

@{
  string value;
  if (context.Request.Headers.TryGetValue("Authorization", out value))
  {
    return Encoding.UTF8.GetString(Convert.FromBase64String(value));
  }
  else
  {
    return null;
  }
}

Usage

Expressions can be used as attribute values or text values in any API Management policies (unless the policy reference specifies otherwise).

Important

When you use policy expressions, there is only limited verification of the policy expressions when the policy is defined. Expressions are executed by the gateway at run-time, any exceptions generated by policy expressions result in a runtime error.

.NET Framework types allowed in policy expressions

The following table lists the .NET Framework types and their members that are allowed in policy expressions.

CLR type Supported members
Newtonsoft.Json.Linq.Extensions All
Newtonsoft.Json.Linq.JArray All
Newtonsoft.Json.Linq.JConstructor All
Newtonsoft.Json.Linq.JContainer All
Newtonsoft.Json.Linq.JObject All
Newtonsoft.Json.Linq.JProperty All
Newtonsoft.Json.Linq.JRaw All
Newtonsoft.Json.Linq.JToken All
Newtonsoft.Json.Linq.JTokenType All
Newtonsoft.Json.Linq.JValue All
System.Collections.Generic.IReadOnlyCollection<T> All
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue> All
System.Collections.Generic.ISet<TKey, TValue> All
System.Collections.Generic.KeyValuePair<TKey, TValue> Key, Value
System.Collections.Generic.List<TKey, TValue> All
System.Collections.Generic.Queue<TKey, TValue> All
System.Collections.Generic.Stack<TKey, TValue> All
System.Convert All
System.DateTime All
System.DateTimeKind Utc
System.DateTimeOffset All
System.Decimal All
System.Double All
System.Guid All
System.IEnumerable<T> All
System.IEnumerator<T> All
System.Int16 All
System.Int32 All
System.Int64 All
System.Linq.Enumerable<T> All
System.Math All
System.MidpointRounding All
System.Net.WebUtility All
System.Nullable<T> All
System.Random All
System.SByte All
System.Security.Cryptography. HMACSHA384 All
System.Security.Cryptography. HMACSHA512 All
System.Security.Cryptography.HashAlgorithm All
System.Security.Cryptography.HMAC All
System.Security.Cryptography.HMACMD5 All
System.Security.Cryptography.HMACSHA1 All
System.Security.Cryptography.HMACSHA256 All
System.Security.Cryptography.KeyedHashAlgorithm All
System.Security.Cryptography.MD5 All
System.Security.Cryptography.RNGCryptoServiceProvider All
System.Security.Cryptography.SHA1 All
System.Security.Cryptography.SHA1Managed All
System.Security.Cryptography.SHA256 All
System.Security.Cryptography.SHA256Managed All
System.Security.Cryptography.SHA384 All
System.Security.Cryptography.SHA384Managed All
System.Security.Cryptography.SHA512 All
System.Security.Cryptography.SHA512Managed All
System.Single All
System.String All
System.StringSplitOptions All
System.Text.Encoding All
System.Text.RegularExpressions.Capture Index, Length, Value
System.Text.RegularExpressions.CaptureCollection Count, Item
System.Text.RegularExpressions.Group Captures, Success
System.Text.RegularExpressions.GroupCollection Count, Item
System.Text.RegularExpressions.Match Empty, Groups, Result
System.Text.RegularExpressions.Regex (Constructor),IsMatch, Match, Matches, Replace
System.Text.RegularExpressions.RegexOptions Compiled, IgnoreCase, IgnorePatternWhitespace, Multiline, None, RightToLeft, Singleline
System.TimeSpan All
System.Tuple All
System.UInt16 All
System.UInt32 All
System.UInt64 All
System.Uri All
System.Xml.Linq.Extensions All
System.Xml.Linq.XAttribute All
System.Xml.Linq.XCData All
System.Xml.Linq.XComment All
System.Xml.Linq.XContainer All
System.Xml.Linq.XDeclaration All
System.Xml.Linq.XDocument All
System.Xml.Linq.XDocumentType All
System.Xml.Linq.XElement All
System.Xml.Linq.XName All
System.Xml.Linq.XNamespace All
System.Xml.Linq.XNode All
System.Xml.Linq.XNodeDocumentOrderComparer All
System.Xml.Linq.XNodeEqualityComparer All
System.Xml.Linq.XObject All
System.Xml.Linq.XProcessingInstruction All
System.Xml.Linq.XText All
System.Xml.XmlNodeType All

Context variable

A variable named context is implicitly available in every policy expression. Its members provide information pertinent to the \request. All of the context members are read-only.

Context Variable Allowed methods, properties, and parameter values
context Api: IApi

Deployment

Elapsed: TimeSpan - time interval between the value of Timestamp and current time

LastError

Operation

Product

Request

RequestId: Guid - unique request identifier

Response

Subscription

Timestamp: DateTime - point in time when request was received

Tracing: bool - indicates if tracing is on or off

User

Variables: IReadOnlyDictionary<string, object>

void Trace(message: string)
context.Api Id: string

IsCurrentRevision: bool

Name: string

Path: string

Revision: string

ServiceUrl: IUrl

Version: string
context.Deployment Region: string

ServiceName: string

Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.LastError Source: string

Reason: string

Message: string

Scope: string

Section: string

Path: string

PolicyId: string

For more information about context.LastError, see Error handling.
context.Operation Id: string

Method: string

Name: string

UrlTemplate: string
context.Product Apis: IEnumerable<IApi>

ApprovalRequired: bool

Groups: IEnumerable<IGroup>

Id: string

Name: string

State: enum ProductState {NotPublished, Published}

SubscriptionLimit: int?

SubscriptionRequired: bool
context.Request Body: IMessageBody

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary<string, string[]>

IpAddress: string

MatchedParameters: IReadOnlyDictionary<string, string>

Method: string

OriginalUrl:IUrl

Url: IUrl
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Returns comma-separated request header values or defaultValue if the header is not found.
context.Response Body: IMessageBody

Headers: IReadOnlyDictionary<string, string[]>

StatusCode: int

StatusReason: string
string context.Response.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Returns comma-separated response header values or defaultValue if the header is not found.
context.Subscription CreatedTime: DateTime

EndDate: DateTime?

Id: string

Key: string

Name: string

PrimaryKey: string

SecondaryKey: string

StartDate: DateTime?
context.User Email: string

FirstName: string

Groups: IEnumerable<IGroup>

Id: string

Identities: IEnumerable<IUserIdentity>

LastName: string

Note: string

RegistrationDate: DateTime
IApi Id: string

Name: string

Path: string

Protocols: IEnumerable<string>

ServiceUrl: IUrl

SubscriptionKeyParameterNames: ISubscriptionKeyParameterNames
IGroup Id: string

Name: string
IMessageBody As<T>(preserveContent: bool = false): Where T: string, JObject, JToken, JArray, XNode, XElement, XDocument

The context.Request.Body.As<T> and context.Response.Body.As<T> methods are used to read a request and response message bodies in a specified type T. By default the method uses the original message body stream and renders it unavailable after it returns. To avoid that by having the method operate on a copy of the body stream, set the preserveContent parameter to true. Go here to see an example.
IUrl Host: string

Path: string

Port: int

Query: IReadOnlyDictionary<string, string[]>

QueryString: string

Scheme: string
IUserIdentity Id: string

Provider: string
ISubscriptionKeyParameterNames Header: string

Query: string
string IUrl.Query.GetValueOrDefault(queryParameterName: string, defaultValue: string) queryParameterName: string

defaultValue: string

Returns comma-separated query parameter values or defaultValue if the parameter is not found.
T context.Variables.GetValueOrDefault<T>(variableName: string, defaultValue: T) variableName: string

defaultValue: T

Returns variable value cast to type T or defaultValue if the variable is not found.

This method throws an exception if the specified type does not match the actual type of the returned variable.
BasicAuthCredentials AsBasic(input: this string) input: string

If the input parameter contains a valid HTTP Basic Authentication authorization request header value, the method returns an object of type BasicAuthCredentials; otherwise the method returns null.
bool TryParseBasic(input: this string, result: out BasicAuthCredentials) input: string

result: out BasicAuthCredentials

If the input parameter contains a valid HTTP Basic Authentication authorization value in the request header the method returns true and the result parameter contains a value of type BasicAuthCredentials; otherwise the method returns false.
BasicAuthCredentials Password: string

UserId: string
Jwt AsJwt(input: this string) input: string

If the input parameter contains a valid JWT token value, the method returns an object of type Jwt; otherwise the method returns null.
bool TryParseJwt(input: this string, result: out Jwt) input: string

result: out Jwt

If the input parameter contains a valid JWT token value, the method returns true and the result parameter contains a value of type Jwt; otherwise the method returns false.
Jwt Algorithm: string

Audience: IEnumerable<string>

Claims: IReadOnlyDictionary<string, string[]>

ExpirationTime: DateTime?

Id: string

Issuer: string

NotBefore: DateTime?

Subject: string

Type: string
string Jwt.Claims.GetValueOrDefault(claimName: string, defaultValue: string) claimName: string

defaultValue: string

Returns comma-separated claim values or defaultValue if the header is not found.
byte[] Encrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - plaintext to be encrypted

alg - name of a symmetric encryption algorithm

key - encryption key

iv - initialization vector

Returns encrypted plaintext.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - plaintext to be encrypted

alg - encryption algorithm

Returns encrypted plaintext.
byte[] Encrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - plaintext to be encrypted

alg - encryption algorithm

key - encryption key

iv - initialization vector

Returns encrypted plaintext.
byte[] Decrypt(input: this byte[], alg: string, key:byte[], iv:byte[]) input - cypher text to be decrypted

alg - name of a symmetric encryption algorithm

key - encryption key

iv - initialization vector

Returns plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm) input - cypher text to be decrypted

alg - encryption algorithm

Returns plaintext.
byte[] Decrypt(input: this byte[], alg: System.Security.Cryptography.SymmetricAlgorithm, key:byte[], iv:byte[]) input - input - cypher text to be decrypted

alg - encryption algorithm

key - encryption key

iv - initialization vector

Returns plaintext.

Next steps

For more information working with policies, see: