You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-12Lines changed: 3 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,10 @@
1
1
# Azure API Management policy toolkit
2
2
3
-
**Azure API management policy toolkit** is a set of libraries and tools for **Azure API Management** which target
4
-
**policy document**. The toolkit was design to help **create** and **test** policy documents with complex expressions.
3
+
**Azure API management policy toolkit** is a set of libraries and tools for authoring [**policy documents**](https://learn.microsoft.com/azure/api-management/api-management-howto-policies) for [**Azure API Management**](https://learn.microsoft.com/azure/api-management/). The toolkit was designed to help **create** and **test** policy documents with complex expressions.
5
4
6
-
Before the Policy toolkit, policy documents were written in Razor format.
7
-
The Razor format is hard to read and understand, especially when there are a lot of expressions.
8
-
The feedback loop on new documents or event the smallest changes was very long.
9
-
It required live Azure API Management instance,
10
-
a policy document deployment and manual testing through the API request.
5
+
Before the Policy toolkit, policy documents were written in Razor format, which is hard to read and understand, especially when there are multiple expressions. The feedback loop on new documents or even the smallest changes was very long, requiring a live Azure API Management instance, a policy document deployment, and manual testing through the API request.
11
6
12
-
The policy toolkit changes that. It allows you to write policy documents in C# language.
13
-
The C# language is more natural and shows a process nature of policy.
14
-
There is as well, no need to jump between C# and XML for expression creation.
15
-
Creating policy documents in C# brings another advantage.
16
-
Simple C# code can test the policy document in the unit test.
7
+
The policy toolkit changes that. It allows you to write policy documents in C# language, which is more natural and doesn't require you to jump between C# and XML for expression creation. Creating policy documents in C# also brings the advantage of using simple C# code for unit testing of policy documents.
Copy file name to clipboardExpand all lines: docs/AvaliablePolicies.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
The Project is in the development stage.
4
4
That means that not all policies are implemented yet.
5
-
In this document, you can find a list of implemented policies and their description.
5
+
In this document, you can find a list of implemented policies. For policy details, see the Azure API Management [policy reference](https://learn.microsoft.com/azure/api-management/api-management-policies).
6
6
7
7
#### :white_check_mark: Implemented policies
8
8
@@ -35,7 +35,7 @@ Policies not listed here are not implemented yet.
35
35
36
36
## InlinePolicy
37
37
38
-
Inline Policy is a workaround until all the policies are implemented.
38
+
InlinePolicy is a workaround until all the policies are implemented.
39
39
It allows you to include policy not implemented yet to the document.
Copy file name to clipboardExpand all lines: docs/IntegratePolicySolution.md
+20-21Lines changed: 20 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,21 @@
1
1
# Steps for deploying policies created by the policy toolkit
2
2
3
-
The Azure API Management policy toolkit targets the advance user who leverages a CI/CD pipeline to check and deploy
3
+
The Azure API Management policy toolkit targets the advanced user who leverages a CI/CD pipeline to check and deploy
4
4
changes made to Azure API Management instance.
5
-
The solution with policy documents can be easily integrated with any infrastructure as a code repository
5
+
The solution with policy documents can be easily integrated with any infrastructure as code repository
6
6
containing data about Azure API Management instance like ARM templates, Bicep, Terraform or APIOps.
7
7
8
8
In this tutorial, we will show you what steps need to be added to the CI/CD pipeline to integrate the policy documents
9
9
created by the policy toolkit. We will execute them locally to understand what is happening under the hood.
10
10
11
11
## Prerequisites
12
12
13
-
### Infrastructure as a code repository
13
+
### Infrastructure as code repository
14
14
15
15
We assume that you have a policy document solution created, and you use a hierarchical approach for the project
16
16
structure. You can read about the hierarchical structure in
17
17
the [Policy documents repository and solution structure](./SolutionStructureRecomendation.md).
18
-
The repository which we will be talking about is looking like the one in the following schema:
18
+
The repository which we will be talking about looks like the one in the following schema:
19
19
20
20
```
21
21
.
@@ -40,19 +40,18 @@ The repository which we will be talking about is looking like the one in the fol
40
40
### Azure API Management instance
41
41
42
42
We assume that you have an Azure API Management instance created and that you have access to it.
43
-
We assume that you have an API created in the Azure API Management instance.
44
-
The API is named `echo-api`. We assume that you can test the policy by invoking some operations on the API.
43
+
We assume that you have an API created in the Azure API Management instance named `echo-api`. We assume that you can test the policy by invoking some operations on the API.
45
44
46
45
### Azure CLI
47
46
48
-
In this tutorial, we will use a bicep file for the deployment description.
49
-
To be able to use the bicep file, an Azure CLI tool needs to be available in the environment.
47
+
In this tutorial, we will use a Bicep file for the deployment description.
48
+
To be able to use the Bicep file, an Azure CLI tool needs to be available in the environment.
50
49
You can download the Azure CLI from the [official site](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
51
50
52
51
## Building and testing
53
52
54
-
The policy documents solution is standard .NET project.
55
-
Because of that, building and testing, the solution is straightforward.
53
+
The policy document's solution is a standard .NET project.
54
+
Because of that, building and testing the solution is straightforward.
56
55
You need to execute standard .NET commands to build and test the solution in the root of the solution folder.
57
56
These steps are essential to know that the policy documents are correct and that they are not breaking the build.
58
57
@@ -74,7 +73,7 @@ these two commands should be split into separate steps, and if any of them fails
74
73
## Compiling the policy documents
75
74
76
75
After standard C# compilation and testing is done, the policy documents can be compiled by the policy toolkit compiler.
77
-
Because, the bicep file for deployment is in the `.\infrastructure\` folder, the compilation target folder should be
76
+
Because the Bicep file for deployment is in the `.\infrastructure\` folder, the compilation target folder should be
78
77
`.\infrastructure\` as well. This will allow easy referencing of the policy documents in the bicep file.
79
78
80
79
```shell
@@ -99,13 +98,13 @@ The command will produce the policy documents and the folder structure will look
99
98
└── ...
100
99
```
101
100
102
-
Your CI/CD pipeline should as well fail if the compilation of the policy documents fails.
101
+
Your CI/CD pipeline should also fail if the compilation of the policy documents fails.
103
102
104
103
## Deploying the policy documents
105
104
106
-
The bicep file for the deployment is in the `.\infrastructure\` folder.
107
-
The bicep file is referencing the service, the API and the policy document.
108
-
The bicep file should look like this:
105
+
The Bicep file for the deployment is in the `.\infrastructure\` folder.
106
+
The Bicep file is referencing the service, the API and the policy document.
| :exclamation: Azure API Management Policy toolkit is not yet published to nuget. For now, please follow the repository setup guide to obtain packages mentioned in the document. |
31
+
| :exclamation: Azure API Management Policy toolkit is not yet published to NuGet. For now, please follow the repository setup guide to obtain packages mentioned in the document. |
with [C# devkit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit),
35
+
tested [Visual Studio ](https://visualstudio.microsoft.com), [Raider](https://www.jetbrains.com/rider/), [Visual Studio Code](https://code.visualstudio.com/)
36
+
with [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit),
37
37
but any IDE with C# support should work.
38
38
39
39
## Writing a simple policy document
40
40
41
-
Azure API Management policy toolkit define new way of writing policy documents. One policy document is one C# class in
41
+
Azure API Management policy toolkit defines a new way of writing policy documents: One policy document is one C# class in
42
42
one `cs` file.
43
-
Let's create a new `ApiOperationPolicy.cs` file in the project which will be our policy document by executing following
43
+
Let's create a new `ApiOperationPolicy.cs` file in the project which will be our policy document by executing the following
44
44
command.
45
45
46
46
```shell
@@ -65,7 +65,7 @@ public class ApiOperationPolicy : IDocument
65
65
The `IDocument` type contains methods `Inbound`, `Outbound`, `Backend` and `OnError` which are used to define policy
66
66
sections.
67
67
68
-
Let's implement `Inbound` method. In the method lets add the policy to set header `X-Hello` to value `World`.
68
+
Let's implement `Inbound` method. In the method let's add the policy to set header `X-Hello` to value `World`.
69
69
70
70
```csharp
71
71
[Document]
@@ -99,7 +99,7 @@ Azure API Management supports policy documents in Razor format. The Azure API Ma
99
99
dotnet tool called a compiler which can generate
100
100
Razor policy documents from C# classes.
101
101
102
-
To use the compiler, we firstly need to add it to our solution folder. To do that execute the following commandin the
102
+
To use the compiler, we first need to add it to our solution folder. To do that execute the following command in the
103
103
solution folder.
104
104
105
105
```shell
@@ -118,7 +118,7 @@ The compiler is a dotnet tool named `policy-compiler`. The `--s` parameter is a
118
118
The `--o` parameter is an output folder for generated policy documents. The `--format` parameter is a flag which tells
119
119
the compiler to format the generated document.
120
120
121
-
The compiler will generate `ApiOperationPolicy.xml` file in the solution folder. Generated file should have the
121
+
The compiler will generate `ApiOperationPolicy.xml` file in the solution folder. The generated file should have the
122
122
following
123
123
content:
124
124
@@ -149,9 +149,9 @@ The Azure API Management policy toolkit allows you to naturally create expressio
149
149
policy document.
150
150
151
151
Let's assume that we want to add authorization header to the request.
152
-
If requests comes from Company IP addresses `10.0.0.0/24` it should use basic authorization with `username`
152
+
If a request comes from Company IP addresses `10.0.0.0/24` it should use basic authorization with `username`
153
153
and `password` from named values.
154
-
If request comes from other IP addresses it should use `Bearer` token received from https://graph.microsoft.com.
154
+
If a request comes from other IP addresses it should use `Bearer` token received from https://graph.microsoft.com.
155
155
For every request we want to add header with the user id.
156
156
157
157
```csharp
@@ -201,10 +201,10 @@ Let's unpack the code above it:
201
201
*`AuthenticationManagedIdentity` method is mapped to `authentication-managed-identity` policy.
202
202
*`SetHeader` method is mapped to `set-header` policy with override.
203
203
204
-
Expressions are a methods in the class. They may be static or instance methods, and they can be private or public.
204
+
Expressions are methods in the class. They may be static or instance methods, and they can be private or public.
205
205
They need to accept one parameter of type`IExpressionContext` with name `context`.
206
206
207
-
To use expression you just need to call that method in the place were you want to use it. Like in our example, we call
207
+
To use an expression you just need to call that method in the place were you want to use it. In our example, we call
208
208
`IsCompanyIP` method in the `if` statement, and we call `GetUserId` method in the `SetHeader` method in value parameter.
209
209
In other more complex policies, which accept a configuration object, you will invoke method in the field initialization
210
210
assignment like in example below.
@@ -248,7 +248,7 @@ Isn't it great, right? I hope it is. But we can now test the expressions in the
248
248
249
249
The Azure API Management policy toolkit provides a way to test expressions in policy documents. To do that we need to
250
250
create a test project from a solution folder. Then we will need to add a reference to the policy project and the testing
251
-
library. Lastly we need to create a test class and write a test for the expression. All of that you can do by executing
251
+
library. Last, we need to create a test class and write a testfor the expression. All of that you can do by executing
252
252
the following commands.
253
253
254
254
```shell
@@ -290,11 +290,10 @@ public class ApiOperationPolicyTest
290
290
291
291
Let's unpack the code above:
292
292
293
-
* Test class is a standard MSTest class with one test method. You can use your favorite testing framework in place of MS
294
-
test. Policy framework is not dependent on any testing framework.
293
+
* Test class is a standard MSTest class with one test method. You can use your favorite testing framework in place of MSTest. Policy framework is not dependent on any testing framework.
295
294
* `MockExpressionContext` is a class which is used to mock request context. It is available in
296
295
`Azure.ApiManagement.PolicyToolkit.Emulator.Expressions` namespace. It implements `IExpressionContext`
297
-
interface and expose a helper properties to set up request context.
296
+
interface and exposes helper properties to set up request context.
298
297
* `context.MockRequest.IpAddress = "10.0.0.12"` is setting a IpAddress for request.
299
298
300
299
To check that the expression works as expected, run the test by executing the following command.
0 commit comments