API Management policy expressions

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 Workspace: IWorkspace
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 Workspace: IWorkspace
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
IWorkspace	Id: string Name: 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:

• Policies in API Management
• Tutorial: Transform and protect APIs
• Policy reference for a full list of policy statements and their settings
• Policy snippets repo
• Author policies using Microsoft Copilot for Azure

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.