学习009-08 Create Custom Endpoints（创建自定义端点）

Create Custom Endpoints（创建自定义端点）

Follow the steps below to implement custom endpoints for the Web API Service:
按照以下步骤为Web API服务实现自定义端点：

1.Right-click the Web API Service project in the Visual Studio Solution Explorer and select Add -> New Item in the context menu. Choose the API Controller – Empty template in the invoked window.
右键单击Visual Studio解决方案资源管理器中的Web API服务项目，然后在上下文菜单中选择Add->New Item。在调用的窗口中选择API控制器-清空模板。

2.Add custom endpoint methods to the new Controller (Get, Post, Put, and Delete methods in the code sample below).
将自定义端点方法添加到新控制器（下面代码示例中的Get、Post、put和Delete方法）。

3.If you wish to use Web API authentication, decorate the new Controller with the AuthorizeAttribute. See the following topic for more information on how to configure authentication: Authenticate and Authorize Web API Endpoints.
如果您希望使用Web API身份验证，请使用AuthorizeAtual装饰新控制器。有关如何配置身份验证的更多信息，请参阅以下主题：身份验证和授权Web API端点。

The Controller’s code:
控制器的代码：

C#

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;


namespace MainDemo.Blazor.Server.Controllers;
[Route("api/[controller]")]
[ApiController]
[Authorize]
public class CustomEndpointController : ControllerBase {
   
    [HttpGet]
    public IEnumerable<string> Get() {
   
        return new string[] {
    "value1", "value2" };
    }


    [HttpGet("{id}")]
    public string Get(int id) {
   
        return "value";
    }


    [HttpPost]
    public void Post([FromBody] string value) {
   
    }


    [HttpPut("{id}")]
    public void Put(int id, [FromBody] string value) {
   
    }


    [HttpDelete("{id}")]
    public void Delete(int id) {
   
    }
}

The result in the Swagger UI:
Swagger UI中的结果：

Authorize Endpoint Requests（授权端点请求）

Decorate a controller or its actions with the AuthorizeAttribute to restrict access. Only authenticated users will have access permissions. AuthorizeAttribute is mandatory if a controller action accesses services that use the Security System (for example IObjectSpaceFactory or ISecurityProvider). In such instances, we recommend that you decorate the entire controller with the AuthorizeAttribute to avoid faulty behavior:
使用AuthorizeAtcade装饰控制器或其操作以限制访问。只有经过身份验证的用户才具有访问权限。如果控制器操作访问使用安全系统的服务（例如IObjectSpaceFactory或ISecurityProvider），则AuthorizeAtcade是强制性的。在这种情况下，我们建议您使用AuthorizeAtcade装饰整个控制器以避免错误行为：

C#

using DevExpress.ExpressApp.Core;
using DevExpress.ExpressApp.Security;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace MainDemo.Blazor.Server.Controllers;
[ApiController]
[Route("api/[controller]")]
[Authorize]
public class CustomEndPointController : ControllerBase {
   
    private readonly ISecurityProvider _securityProvider;
    private readonly IObjectSpaceFactory _securedObjectSpaceFactory;
    public CustomEndPointController(ISecurityProvider securityProvider, IObjectSpaceFactory securedObjectSpaceFactory) {
   
        _securityProvider = securityProvider;
        _securedObjectSpaceFactory = securedObjectSpaceFactory;
    }
    // ...
}

Note
If an endpoint does not access any secured services, you can skip the AuthorizeAttribute and make the endpoint available to unauthenticated users. Refer to the Non-Secured Endpoint Examples section for examples on how to implement endpoints that can work without authentication.
如果终结点不访问任何受保护的服务，您可以跳过AuthorizeAtual，并使该终结点可供未经身份验证的用户使用。有关如何实现无需身份验证即可工作的终结点的示例，请参阅非安全终结点示例部分。

Be sure to apply the AuthorizeAttribute in the following cases:
请务必在以下情况下应用 AuthorizeAttribute：

• You run a standalone Web API Service and access a secured service in a controller action. When the code accesses the service, XAF Security System attempts to authenticate the user even if the AuthorizeAttribute is not used. This operation will fail with an exception if the request does not contain an authentication header.

• 您运行独立的Web API服务并在控制器操作中访问受保护的服务。当代码访问该服务时，XAF安全系统会尝试对用户进行身份验证，即使未使用AuthorizeAtcade。如果请求不包含身份验证标头，此操作将失败并出现异常。

• JWT-based authentication is not the default authentication method in your application. For example, this is the case if you use Web API Service as a part of an XAF Blazor application, where the default authentication method is cookie-based. When a controller action without the AuthorizeAttribute accesses a secured service, the ASP.NET Core authentication system attempts to authenticate a user with the default method (a cookie). In this case, the XAF Security System throws an exception even if an authentication header is specified, because the ASP.NET Core authentication system failed to authenticate the user based on a cookie. However, if you specify the AuthorizeAttribute, the ASP.NET Core authorization system tries all available authentication methods, so it handles JWT authentication correctly.

• 基于JWT的身份验证不是您的应用程序中的默认身份验证方法。例如，如果您使用Web API服务作为XAF Blazor应用程序的一部分，则会出现这种情况，其中默认身份验证方法是基于cookie的。当没有AuthorizeAtcade的控制器操作访问安全服务时，ASP.NETCore身份验证系统会尝试使用默认方法（cookie）对用户进行身份验证。在这种情况下，即使指定了身份验证标头，XAF安全系统也会抛出异常，因为ASP.NETCore身份验证系统未能根据cookie对用户进行身份验证。但是，如果您指定AuthorizeAtcade，ASP.NETCore授权系统会尝试所有可用的身份验证方法，因此它会正确处理JWT身份验证。

See the Secured Endpoint Examples section for examples of custom endpoints that require the AuthorizeAttribute.
请参阅安全端点示例部分，了解需要Authorize属性的自定义端点示例。

Access an Object Space（访问对象空间）

Use one of the following techniques to access an Object Space from a custom endpoint controller:
使用以下技术之一从自定义端点控制器访问对象空间：

Use IDataService (Recommended)（使用IDataService（推荐））

Inject the IDataService and call its GetObjectSpace method to obtain a secured Object Space instance for the specified type:
注入IDataService并调用其GetObjectSpace方法以获取指定类型的安全对象空间实例：

C#

using DevExpress.ExpressApp.WebApi.Services;
using MainDemo.Module.BusinessObjects;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace MainDemo.Blazor.Server.Controllers;
[ApiController]
[Route(