API Management policy expressions

  • Article

APPLIES TO: All API Management tiers

This article discusses policy expressions syntax in C# 7. Each expression has access to:

  • The implicitly provided context variable.
  • An allowed subset of .NET Framework types.

Syntax

  • Single statement expressions:
    • Enclosed in @(expression), where expression is a well-formed C# expression statement.
  • Multi-statement expressions:
    • 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))
  {
      if(value != null && value.Length > 0)
      {
          return Encoding.UTF8.GetString(Convert.FromBase64String(value[0]));
      }
  }
  return null;

}

Usage

Unless the policy reference specifies otherwise, expressions can be used as attribute values or text values in any API Management policy.

Important

When the policy is defined, policy expressions only have limited verification. 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 members allowed in policy expressions.

Type Supported members
Newtonsoft.Json.Formatting All
Newtonsoft.Json.JsonConvert SerializeObject, DeserializeObject
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.Array All
System.BitConverter All
System.Boolean All
System.Byte All
System.Char All
System.Collections.Generic.Dictionary<TKey, TValue> All
System.Collections.Generic.HashSet<T> All
System.Collections.Generic.ICollection<T> All
System.Collections.Generic.IDictionary<TKey, TValue> All
System.Collections.Generic.IEnumerable<T> All
System.Collections.Generic.IEnumerator<T> All
System.Collections.Generic.IList<T> All
System.Collections.Generic.IReadOnlyCollection<T> All
System.Collections.Generic.IReadOnlyDictionary<TKey, TValue> All
System.Collections.Generic.ISet<T> All
System.Collections.Generic.KeyValuePair<TKey, TValue> All
System.Collections.Generic.List<T> All
System.Collections.Generic.Queue<T> All
System.Collections.Generic.Stack<T> All
System.Convert All
System.DateTime (Constructor), Add, AddDays, AddHours, AddMilliseconds, AddMinutes, AddMonths, AddSeconds, AddTicks, AddYears, Date, Day, DayOfWeek, DayOfYear, DaysInMonth, Hour, IsDaylightSavingTime, IsLeapYear, MaxValue, Millisecond, Minute, MinValue, Month, Now, Parse, Second, Subtract, Ticks, TimeOfDay, Today, ToString, UtcNow, Year
System.DateTimeKind Utc
System.DateTimeOffset All
System.Decimal All
System.Double All
System.Enum Parse, TryParse, ToString
System.Exception All
System.Guid All
System.Int16 All
System.Int32 All
System.Int64 All
System.IO.StringReader All
System.IO.StringWriter All
System.Linq.Enumerable All
System.Math All
System.MidpointRounding All
System.Net.IPAddress AddressFamily, Equals, GetAddressBytes, IsLoopback, Parse, TryParse, ToString
System.Net.WebUtility All
System.Nullable All
System.Random All
System.SByte All
System.Security.Cryptography.AsymmetricAlgorithm All
System.Security.Cryptography.CipherMode All
System.Security.Cryptography.HashAlgorithm All
System.Security.Cryptography.HashAlgorithmName All
System.Security.Cryptography.HMAC All
System.Security.Cryptography.HMACMD5 All
System.Security.Cryptography.HMACSHA1 All
System.Security.Cryptography.HMACSHA256 All
System.Security.Cryptography.HMACSHA384 All
System.Security.Cryptography.HMACSHA512 All
System.Security.Cryptography.KeyedHashAlgorithm All
System.Security.Cryptography.MD5 All
System.Security.Cryptography.Oid All
System.Security.Cryptography.PaddingMode All
System.Security.Cryptography.RNGCryptoServiceProvider All
System.Security.Cryptography.RSA All
System.Security.Cryptography.RSAEncryptionPadding All
System.Security.Cryptography.RSASignaturePadding 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.Security.Cryptography.SymmetricAlgorithm All
System.Security.Cryptography.X509Certificates.PublicKey All
System.Security.Cryptography.X509Certificates.RSACertificateExtensions All
System.Security.Cryptography.X509Certificates.X500DistinguishedName Name
System.Security.Cryptography.X509Certificates.X509Certificate All
System.Security.Cryptography.X509Certificates.X509Certificate2 All
System.Security.Cryptography.X509Certificates.X509ContentType All
System.Security.Cryptography.X509Certificates.X509NameType All
System.Single All
System.String All
System.StringComparer All
System.StringComparison 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, Unescape, Split
System.Text.RegularExpressions.RegexOptions All
System.Text.StringBuilder All
System.TimeSpan All
System.TimeZone All
System.TimeZoneInfo.AdjustmentRule All
System.TimeZoneInfo.TransitionTime All
System.TimeZoneInfo All
System.Tuple All
System.UInt16 All
System.UInt32 All
System.UInt64 All
System.Uri All
System.UriPartial 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, except Load
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

The context variable is implicitly available in every policy expression. Its members:

  • Provide information relevant to the API request and response, and related properties.
  • Are all 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

GraphQL

LastError

Operation

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 Gateway

GatewayId: string (returns 'managed' for managed gateways)

Region: string

ServiceId: string

ServiceName: string

Certificates: IReadOnlyDictionary<string, X509Certificate2>
context.Deployment.Gateway Id: string (returns 'managed' for managed gateways)

InstanceId: string (returns 'managed' for managed gateways)

IsManaged: bool
context.GraphQL GraphQLArguments: IGraphQLDataObject

Parent: IGraphQLDataObject

Examples
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 ApprovalRequired: bool

Groups: IEnumerable<IGroup>

Id: string

Name: string

State: enum ProductState {NotPublished, Published}

SubscriptionsLimit: int?

SubscriptionRequired: bool
context.Request Body: IMessageBody or null if request doesn't have a body.

Certificate: System.Security.Cryptography.X509Certificates.X509Certificate2

Headers: IReadOnlyDictionary<string, string[]>

IpAddress: string

MatchedParameters: IReadOnlyDictionary<string, string>

Method: string

OriginalUrl: IUrl

Url: IUrl

PrivateEndpointConnection: IPrivateEndpointConnection or null if request doesn't come from a private endpoint connection.
string context.Request.Headers.GetValueOrDefault(headerName: string, defaultValue: string) headerName: string

defaultValue: string

Returns comma-separated request header values or defaultValue if the header isn't 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 isn't found.
context.Subscription CreatedDate: 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
IGraphQLDataObject TBD
IGroup Id: string

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

- The context.Request.Body.As<T> and context.Response.Body.As<T> methods read a request or response message body in specified type T.

- Or -

AsFormUrlEncodedContent(bool preserveContent = false)

- The context.Request.Body.AsFormUrlEncodedContent() and context.Response.Body.AsFormUrlEncodedContent() methods read URL-encoded form data in a request or response message body and return an IDictionary<string, IList<string> object. The decoded object supports IDictionary operations and the following expressions: ToQueryString(), JsonConvert.SerializeObject(), ToFormUrlEncodedContent().

By default, the As<T> and AsFormUrlEncodedContent() methods:
  • Use the original message body stream.
  • Render it unavailable after it returns.

To avoid that and have the method operate on a copy of the body stream, set the preserveContent parameter to true, as shown in examples for the set-body policy.
IPrivateEndpointConnection Name: string

GroupId: string

MemberName: string

For more information, see the REST API.
IUrl Host: string

Path: string

Port: int

Query: IReadOnlyDictionary<string, string[]>

QueryString: string

Scheme: 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 isn't found.
IUserIdentity Id: string

Provider: string
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 isn't found.

This method throws an exception if the specified type doesn't 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

Audiences: IEnumerable<string>

Claims: IReadOnlyDictionary<string, string[]>

ExpirationTime: DateTime?

Id: string

Issuer: string

IssuedAt: DateTime?

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 isn't 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 - cypher text to be decrypted

alg - encryption algorithm

key - encryption key

iv - initialization vector

Returns plaintext.
bool VerifyNoRevocation(input: this System.Security.Cryptography.X509Certificates.X509Certificate2) Performs an X.509 chain validation without checking certificate revocation status.

input - certificate object

Returns true if the validation succeeds; false if the validation fails.

Related content

For more information working with policies, see:

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 detect 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.