diff --git a/docs/en/Community-Articles/2022-05-16-Consuming-Rest-Api-By-Using-Static-Proxy/POST.md b/docs/en/Community-Articles/2022-05-16-Consuming-Rest-Api-By-Using-Static-Proxy/POST.md index d22c8bf362..e2ad154bdd 100644 --- a/docs/en/Community-Articles/2022-05-16-Consuming-Rest-Api-By-Using-Static-Proxy/POST.md +++ b/docs/en/Community-Articles/2022-05-16-Consuming-Rest-Api-By-Using-Static-Proxy/POST.md @@ -2,9 +2,9 @@ In this article, I will explain how to consume HTTP APIs from a .NET application using ABP's [dynamic](https://docs.abp.io/en/abp/latest/API/Dynamic-CSharp-API-Clients) and [static](https://docs.abp.io/en/abp/latest/API/Static-CSharp-API-Clients) client-side proxy systems. I will start by creating a new project and consume the HTTP APIs from a .NET console application using dynamic client proxies. Then I will switch to static client proxies. Finally, I will glance at the differences and similarities between static and dynamic generic proxies. -**Benefits (both valid for dynamic and static proxies):** +Here the main benefits of using the client-side proxy system (either dynamic or static): -* Maps C# method calls to remote server HTTP calls by considering the HTTP method, route, query string parameters, request payload and other details. +* Automatically maps C# method calls to remote server HTTP calls by considering the HTTP method, route, query string parameters, request payload and other details. * Authenticates the HTTP Client by adding an access token to the HTTP header. * Serializes to and deserialize from JSON. * Handles HTTP API versioning. @@ -18,7 +18,7 @@ Firstly create a new solution via [ABP CLI](https://docs.abp.io/en/abp/latest/CL abp new Acme.BookStore ``` -> See ABP's [Getting Started document](https://docs.abp.io/en/abp/latest/Getting-Started-Setup-Environment?UI=MVC&DB=EF&Tiered=No) to learn how to create and run your application, if you haven't before. +> See ABP's [Getting Started document](https://docs.abp.io/en/abp/latest/Getting-Started-Setup-Environment?UI=MVC&DB=EF&Tiered=No) to learn how to create and run your application, if you haven't done it before. ## Create the application service interface I will start by creating an application service and exposing it as an HTTP API to be consumed by remote clients. First, define an interface for the application service; Create an `IBookAppService` interface in the `Books` folder (namespace) of the `Acme.BookStore.Application.Contracts` project: @@ -122,12 +122,10 @@ We are basically injecting the `IBookAppService` interface to consume the remote You can run the application to see the output: ``` -Books: Anna Karenina, Crime and Punishment, Mother +Books: Hunger, Crime and Punishment, For Whom the Bell Tolls ``` ## Convert the application to use static client proxies -Before showing you how to use static client proxies instead of dynamic client proxies, I will mention the differences between both approaches. Their similarities, advantages and disadvantages to each other. - The [application startup template](https://docs.abp.io/en/abp/latest/Startup-Templates/Application) comes pre-configured for the **dynamic** client proxy generation, in the `HttpApi.Client` project. If you want to switch to the **static** client proxies, you should change `context.Services.AddHttpClientProxies` to `context.Services.AddStaticHttpClientProxies` in the module class of your `HttpApi.Client` project: ```csharp @@ -150,7 +148,7 @@ public class BookStoreHttpApiClientModule : AbpModule The `AddStaticHttpClientProxies` method gets an assembly, finds all service interfaces in the given assembly, and prepares for static client proxy generation. -Now you're ready to generate the client proxy code by running the following command in the root folder of your client project while your server-side project is running: +Now you're ready to generate the client proxy code by running the following command in the root folder of your client project **while your server-side project is running**: ````bash abp generate-proxy -t csharp -u http://localhost:44397/ @@ -165,12 +163,14 @@ You should see the generated files under the selected folder: Now you can run the console client application again. You should see the same output: ```` -Books: Anna Karenina, Crime and Punishment, Mother +Books: Hunger, Crime and Punishment, For Whom the Bell Tolls ```` ## Add authorization The ABP Framework provides an [authorization system](https://docs.abp.io/en/abp/latest/Authorization) based on [ASP.NET Core's authorization infrastructure](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction). We can define permissions and restrict access to some of our application's functionalities, so only the allowed users/clients can use these functionalities. Here, I will define a permission to be able to get the list of books. +### Defining a permission + Under `Acme.BookStore.Application.Contracts` open `BookStorePermissions` and paste the below code: ```csharp namespace Acme.BookStore.Permissions; @@ -201,6 +201,8 @@ public class BookStorePermissionDefinitionProvider : PermissionDefinitionProvide } } ``` +### Authorizing the application service + We can now add the `[Authorize(BookStorePermissions.Books.Default)]` attribute to the `BookAppService` class: ```csharp @@ -214,34 +216,26 @@ public class BookAppService : ApplicationService, IBookAppService If you run the server now, then run the console client application, you will see the following error on the console application: ``` -Unhandled exception. Volo.Abp.Http.Client.AbpRemoteCallException: Forbidden - at Volo.Abp.Http.Client.ClientProxying.ClientProxyBase`1.ThrowExceptionForResponseAsync(HttpResponseMessage response) - at Volo.Abp.Http.Client.ClientProxying.ClientProxyBase`1.RequestAsync(ClientProxyRequestContext requestContext) - at Volo.Abp.Http.Client.ClientProxying.ClientProxyBase`1.RequestAsync[T](ClientProxyRequestContext requestContext) - at Volo.Abp.Http.Client.ClientProxying.ClientProxyBase`1.RequestAsync[T](String methodName, ClientProxyRequestTypeValue arguments) - at Acme.BookStore.Books.ClientProxies.BookClientProxy.GetListAsync(PagedAndSortedResultRequestDto input) in YourPath\ABPConsumingRestApiByUsingStaticProxy\src\Acme.BookStore.HttpApi.Client\ClientProxies\BookClientProxy.Generated.cs:line 20 - at Acme.BookStore.HttpApi.Client.ConsoleTestApp.ClientDemoService.RunAsync() in YourPath\ABPConsumingRestApiByUsingStaticProxy\test\Acme.BookStore.HttpApi.Client.ConsoleTestApp\ClientDemoService.cs:line 21 - at Acme.BookStore.HttpApi.Client.ConsoleTestApp.ConsoleTestAppHostedService.StartAsync(CancellationToken cancellationToken) in YourPath\ABPConsumingRestApiByUsingStaticProxy\test\Acme.BookStore.HttpApi.Client.ConsoleTestApp\ConsoleTestAppHostedService.cs:line 30 - at Microsoft.Extensions.Hosting.Internal.Host.StartAsync(CancellationToken cancellationToken) - at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token) - at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token) - at Acme.BookStore.HttpApi.Client.ConsoleTestApp.Program.Main(String[] args) in YourPath\ABPConsumingRestApiByUsingStaticProxy\test\Acme.BookStore.HttpApi.Client.ConsoleTestApp\Program.cs:line 12 - at Acme.BookStore.HttpApi.Client.ConsoleTestApp.Program.
(String[] args) +Unhandled exception. Volo.Abp.Http.Client.AbpRemoteCallException: Forbidden at +Volo.Abp.Http.Client.ClientProxying.ClientProxyBase`1 +.ThrowExceptionForResponseAsync(HttpResponseMessage response)... ``` To fix the problem, we should grant permission to the admin user. We are granting permission to the admin user because the console application is configured to use the Resource Owner Password Grant Flow. That means the client application is consuming services on behalf of the admin user. You can see the configuration in the `appsettings.json` file of the console application. -**Giving permission** +### Granting the permission + Once you define the permissions, you can see them on the permission management modal. Go to the Administration -> Identity -> Roles page, select the Permissions action for the admin role to open the permission management modal: ![persmisson](./permission.png) Grant the permissions you want and save the modal. -**The differences between dynamic and static proxies:** +## Dynamic vs static proxies + Static generic proxies provide **better performance** because they don't need to run on runtime, but you should **re-generate** them once you change the API endpoint definition. Dynamic generic proxies don't need to be re-generated because they work on the runtime but they have a slight performance penalty. -### Further Reading +## Further Reading In this tutorial, I explained how you can create an example project and apply a static client proxy instead of a dynamic client proxy. I also summarized the differences between both approaches. If you want to get more information, you can read the following documents: * [Static C# API Client Proxies](https://docs.abp.io/en/abp/latest/API/Static-CSharp-API-Clients)