What is the difference between 'xml' and 'rawxml' formats when defining APIM policies in ARM/Bicep Templates

Question

When defining an Azure API Management policy in a Bicep or ARM template, the format of the policy value may be set to rawxml (and rawxml-link) or xml (and xml-link). I know what the link formats are, however there is an unclear difference between rawxml and xml.

I have looked through the MS Docs on this (ApiManagement Policy Template Definition) but have not found any indicator as to the differences or purposes of either format. Googling around has not produced a straight answer anyway, at least to my google skills.

What is the difference between rawxml and xml?

Blamable

Answer 1

Policy in xml format must be a valid XML, i.e. all characters that are not valid in XML must be properly escaped. For example, that is how simple expression must look

<set-variable name="var" value="@(&quot;user id:&quot; + context.User?.Id)"/>

Policy in rawxml format utilizes razor syntax and it is what you see in Azure Portal when you edit policy code. In this format you don't need to escape XML invalid characters in expressions, like so:

<set-variable name="var" value="@("user id:" + context.User?.Id)"/>

Otherwise there is no difference, you can choose whatever format fits your needs best.

Collbaith

Is this documented somewhere? There are various magic strings like this in ARM/bicep that have limited documentation. – Fortunna

Only very briefly: learn.microsoft.com/en-us/rest/api/apimanagement/current-ga/… – Collbaith

Thanks, would be good if they also put this on the bicep doc! – Fortunna

You made my day! This was the last issue we were having. The error so other people can easily find this solution: Name cannot begin with the '\"' character, hexadecimal value 0x22. Line 16, position 37." – Calvert

TIL I learned that adding APIM policies to arm templates does not have to be a nightmare. @VitaliyKurokhtin you have changed my life lol. For years (literally) I've been struggling to properly escape apim policies thinking to myself "there has to be a better way, this is ridiculous". How I missed the docs on rawxml, beats me, but now I know! – Cislunar

Answer 2

This official reference shows the differences:

• rawxml: The contents are inline and Content type is a non XML encoded policy document.

• rawxml-link: The policy document is not XML encoded and is hosted on a HTTP endpoint accessible from the API Management service.

• xml: The contents are inline and Content type is an XML document.

• xml-link: The policy XML document is hosted on a HTTP endpoint accessible from the API Management service.

Rennold