01.04 Backend Web API Service / REST API 后端Web API服务/ REST API

Backend Web API Service / REST API 后端Web API服务/ REST API

Overview 概述

The Template Kit creates a back-end Web API Service (Web API) with integrated authorization and CRUD operations powered by Microsoft EF Core and DevExpress XPO ORM library. You can use OAuth2, JWT, or custom strategies for authentication. The built-in Security System also filters out secure server data based on permissions granted to users.
模板套件创建了一个后端Web API服务（Web API），集成了授权和CRUD操作，由Microsoft EF Core和DevExpress XPO ORM库提供支持。您可以使用OAuth2、JWT或自定义策略进行身份验证。内置的安全系统还可以根据用户的权限过滤出安全的服务器数据。

The Web API creates URLs (endpoints) that allow you to perform CRUD operations from your non-XAF UI applications (for instance, .NET MAUI, JavaScript, or Blazor clients). It uses ASP.NET Core OData to support paging, filters, and other OData options. This service can be hosted as part of a Blazor Server project or as a standalone ASP.NET Core project.
Web API创建url（端点），允许您从非xaf UI应用程序（例如，）执行CRUD操作。NET MAUI、JavaScript或Blazor客户端)。它使用ASP。. NET Core OData来支持分页、过滤器和其他OData选项。该服务可以作为Blazor Server项目的一部分托管，也可以作为独立的ASP托管。. NET Core项目。

The Web API utilizes Swagger (OpenAPI) to display and test endpoints. You can also test endpoints or consume the Web API with other platforms (for example, Postman, .NET, or JavaScript).
Web API利用Swagger （OpenAPI）来显示和测试端点。您还可以测试端点或使用其他平台的Web API(例如，Postman、. NET或JavaScript)。

The basic functions of our Web API Service (including the Template Kit) are available for free as part of our .NET App Security & Web API Service free offer. To register your free copy today, please visit our .NET App Security & Web API – Free Offer from DevExpress page.
我们的Web API服务的基本功能（包括模板套件）是免费提供的。NET应用安全和Web API服务免费提供。今天注册您的免费副本，请访问我们的. NET应用安全和Web API -免费提供从DevExpress页面。

Additional services/benefits of our Web API Service ship as part of the DevExpress Universal Subscription and include:
我们的Web API服务的附加服务/好处作为DevExpress通用订阅的一部分发布，包括：

• Technical support and full source code. 技术支持和完整的源代码。
• XAF’s administrative UI to manage users and roles at runtime using
  WinForms and ASP.NET Core Blazor apps: Getting Started Tutorial |
  Demos. XAF的管理UI在运行时使用WinForms和ASP管理用户和角色。. NET Core
  Blazor应用程序：入门教程|演示。
• Localization functions (endpoints to obtain localized captions for
  classes, members, and custom UI elements).
  本地化函数（获取类、成员和自定义UI元素的本地化标题的端点）。

Advanced/enterprise functions such as audit trail, endpoints to
download reports, file attachments, check validation, etc.
高级/企业功能，如审计跟踪、下载报告的端点、文件附件、检查验证等。

See Also

• Frequently Asked Questions 常见问题
• Overview and Tutorial Videos 概述和教程视频
• Survey - Your Feedback Matters 调查——你的反馈很重要

How to Use 如何使用

You can add the Web API to an existing Blazor Server project or create a new project with this service:
您可以将Web API添加到现有的Blazor Server项目或使用此服务创建新项目：

• Create a Standalone Web API Application 创建一个独立的Web API应用程序
• Integrate the Web API into an Existing XAF Blazor Application 将Web
  API集成到现有的XAF Blazor应用程序中

After you add the Web API to your project, you can use it as described in the following topics:
将Web API添加到项目后，您可以按照以下主题使用它：

• Add and Protect CRUD Web API Endpoints 添加和保护CRUD Web API端点
• Make HTTP Requests to the Web API from .NET Applications 向Web
  API发出HTTP请求
• Execute Custom Operations on Endpoint Requests 对端点请求执行自定义操作
• Create Custom Endpoints 创建自定义端点
• Access Object Space, Security System, and Caption Helper in Custom
  Endpoint Methods 在自定义端点方法中访问对象空间、安全系统和标题帮助器

Additionally, review our GitHub examples:
此外，回顾一下我们的GitHub示例：

• JavaScript with DevExtreme + ASP.NET Core Web API/OData App
  JavaScript与DevExtreme + ASP. NET Core Web API/OData应用
• JavaScript with Svelte + ASP.NET Core Web API/OData App
  JavaScript与Svelte + ASP. NET Core Web API/OData应用
• Blazor WebAssembly App Blazor WebAssembly应用
• .NET MAUI (iOS/Android) App .NET MAUI （iOS/Android）应用程序
• WinForms Application (with OData) WinForms应用程序（带OData）

Authentication Options 身份验证选项

The Web API supports all standard ASP.NET Core authentication techniques that you can specify in the MySolution.WebApi\Startup.cs (MySolution.Blazor.Server.Startup.cs) file. See the following topic for details: Authentication in Web API Projects.
Web API支持所有标准的ASP。您可以在MySolution.WebApi\Startup.cs （MySolution.Blazor.Server.Startup.cs）文件中指定。NET核心认证技术。有关详细信息，请参阅以下主题：Web API项目中的身份验证。

Performance Considerations 性能考虑

You can disable logging to improve the Web API performance. To do this, set the LogLevel.DevExpress.ExpressApp option to None.
您可以禁用日志记录以提高Web API性能。为此，将LogLevel.DevExpress.ExpressApp选项设置为None。

File:MySolution.Blazor.Server\appsettings.json
(MySolution.Blazor.Server\appsettings.Development.json for debugging)

JSON // ... "LogLevel":{"Default":"Information", "Microsoft":"Warning", "Microsoft.Hosting.Lifetime":"Information", "DevExpress.ExpressApp":"None"} // ... 

Use logging options other than None (for example, DevExpress.ExpressApp = Debug) only for debugging purposes because logging reduces performance. See the following topic for more information: Log Files.
使用除None以外的日志记录选项（例如DevExpress）。ExpressApp = Debug)仅用于调试目的，因为日志记录会降低性能。有关更多信息，请参见以下主题：日志文件。

Limitations 限制

• The capability to use custom fields in an XPO data model is not
  supported. The underlying ASP.NET Core Web API / OData v4
  infrastructure accesses type information directly through reflection
  in the form of System.Type objects, which do not contain information
  about custom fields. 不支持在XPO数据模型中使用自定义字段的功能。底层ASP. NET Core Web API / OData v4基础结构以System的形式通过反射直接访问类型信息。类型对象，它不包含有关自定义字段的信息。

FAQ 常见问题解答

Q: Is the .NET App Security & Web API free for commercial use?
问：. NET应用程序安全和Web API免费用于商业用途？

A: Absolutely. .NET App Security & Web API is available free-of-charge. To download your copy, visit: https://www.devexpress.com/security-api-free/.
答: 当然可以.NET应用安全和Web API是免费的。下载副本，请访问：https://www.devexpress.com/security-api-free/。

When you register for a free DevExpress product, you can use your registered product for as long as your needs dictate. Should an update be made available free-of-charge, you will be notified by email or on this website. Updates that are issued free-of-charge can also be used indefinitely. Please refer to the DevExpress End User License Agreement for detailed licensing information.
当您注册一个免费的DevExpress产品时，只要您需要，您就可以使用您注册的产品。如果免费提供更新，您将通过电子邮件或本网站收到通知。免费发布的更新也可以无限期使用。请参考DevExpress最终用户许可协议了解详细的许可信息。**

Q: Do I have to include XAF UI dependencies in my project?
问：我必须在我的项目中包括XAF UI依赖关系吗？

A: Our Web API Service relies on Visual Studio 2022 and a few non-visual cross-platform .NET packages (example). These include DevExpress.Data, DevExpress.Xpo, DevExpress.Document.Processor, and other core libraries. Though these packages have “XAF” or “ExpressApp” in their names, you do not need to pull XAF WinForms and ASP.NET Core Blazor dependencies in your projects.
答: 我们的Web API服务依赖于Visual Studio 2022和一些非可视化跨平台。. NET包（示例）。其中包括DevExpress。数据,DevExpress。Xpo DevExpress.Document。处理器和其他核心库。虽然这些包的名称中有“XAF”或“ExpressApp”，但您不需要拉XAF WinForms和ASP. NET Core Blazor依赖于你的项目。

In other words, if you do not require XAF, you are not forced to use it. Optionally, you can tell the Template Kit to create the Web API Service inside an XAF Blazor UI app. This could be helpful to those who wish to incorporate a web Admin Panel (watch the video) and an embedded API server within the same package (for easier hosting and maintenance). Again, this is entirely up to you. You can always use the Web API Service on a standalone basis.
换句话说，如果您不需要XAF，就不必强制使用它。可选地，你可以告诉模板套件在XAF Blazor UI应用程序中创建Web API服务。这可能有助于那些希望在同一包中合并Web管理面板（观看视频）和嵌入式API服务器的人（更容易托管和维护）。再说一次，这完全取决于你。你总是可以在独立的基础上使用Web API服务。

Q: Will I benefit from the Web API Service if I’m not developing XAF UI apps?
问：如果我不开发XAF UI应用程序，我会从Web API服务中受益吗？
A: Our Web API Service can be used outside of XAF-powered UI apps. Numerous developers have successfully used our Web API Service as a backend for their Angular, Vue, React, Blazor WebAssembly, Xamarin, and other .NET/JavaScript UI clients.
答: 我们的Web API服务可以在xaf驱动的UI应用程序之外使用。许多开发人员已经成功地使用我们的Web API服务作为他们的Angular、Vue、React、Blazor WebAssembly、Xamarin等的后端 .NET/JavaScript UI客户端。

For more information in this regard, check out our DevExtreme example on GitHub. This example uses our client-side dxDataGrid with DevExpress.Data.ODataStore (just like many other CRUD apps powered by DevExtreme). We’ve also published a video series where we built a .NET MAUI mobile app that consumes our Web API Service (see also .NET MAUI example sources).
有关这方面的更多信息，请查看GitHub上的DevExtreme示例。这个例子使用我们的客户端dxDataGrid和DevExpress.Data.ODataStore（就像许多其他由DevExtreme驱动的CRUD应用程序一样）。我们还发布了一个系列视频.NET MAUI移动应用程序，它使用我们的Web API服务(参见.NET MAUI示例源)。

Q: Do I have to learn a lot of XAF terminology to consume the Web API?
问：我必须学习很多XAF术语才能使用Web API吗？

A: As far as clients or consumers are concerned, our Web API Service is a standard ASP.NET Core OData 8.0 service – use the standard OData v4 query options to consume our API. You can also use Swagger UI, Postman, developer tools within your favorite web browser, or standard .NET/JavaScript API.
答: 就客户或消费者而言，我们的Web API服务是一个标准的ASP.NET Core OData 8.0服务——使用标准的OData v4查询选项来使用我们的API。您还可以在您最喜欢的web浏览器或标准中使用Swagger UI， Postman，开发人员工具.NET/JavaScript API。

We have published dozens of .NET code examples with the standard HttpClient: Make HTTP Requests to the Web API from .NET Applications. You can find other examples in public community resources for your favorite client UI technology.
我们已经发表了几十篇. NET代码示例与标准HttpClient：使HTTP请求的Web API从。网络应用程序。您可以在公共社区资源中找到您喜欢的客户机UI技术的其他示例。

Q: Will it take hours to get started?
问：要几个小时才能开始吗？

A: We ship a 1-Click solution to build CRUD REST API for popular usage scenarios – from zero to a running Swagger UI.
答: 我们发布了一个一键式解决方案，为流行的使用场景构建CRUD REST API——从零到运行的Swagger UI。

Simply run the Universal Component Installer from the Download Manager and enter the credentials for your DevExpress account (free or paid/Universal). Then, use the free Template Kit in Visual Studio 2022+ to create Web API Service. The Template Kit adds all required dependencies, Entity Framework DbContext, default access control rights, connection string, etc. For more information, refer to the following help topic: Create a Standalone Web API Application.
只需从下载管理器中运行通用组件安装程序，并输入您的DevExpress帐户（免费或付费/通用）的凭据。然后，使用Visual Studio 2022+中的免费模板工具包创建Web API服务。模板套件添加了所有必需的依赖，实体框架DbContext，默认访问控制权限，连接字符串等。有关更多信息，请参阅以下帮助主题：创建独立Web API应用程序。

Q: Can I customize the API (add custom endpoints, remove data from response, and so on)?
问：我可以自定义API（添加自定义端点，从响应中删除数据，等等）吗？

A: You can do everything that you can do with ASP.NET Core OData. Microsoft published lots of information in this regard here: Create web APIs with ASP.NET Core.
答: 你可以用ASP. NET Core OData做任何你能做的事情。微软在这方面发布了很多信息：用ASP创建ASP.NET Core。

To save time for our Web API Service users, we documented highly popular OData customizations on our website:
为了节省我们的Web API服务用户的时间，我们在我们的网站上记录了非常流行的OData定制：

• Create Custom Endpoints | Expose or Hide Business Object Properties
  创建自定义端点|公开或隐藏业务对象属性
• Change an EDM Model Structure using ODataModelBuilder | Customize
  OData Options 使用ODataModelBuilder更改EDM模型结构|自定义OData选项
• Authenticate Users & Authorize CRUD Operations in .NET MAUI Apps with
  Web API Service & EF Core (videos on YouTube) 中的认证用户和授权CRUD操作.NET
  MAUI应用程序与Web API服务和EF Core（视频在YouTube上）
• Add Custom Web API Endpoints To Check Permissions & Query Media Data
  in .NET MAUI Apps with EF Core (videos on YouTube) 添加自定义Web
  API端点来检查权限和查询媒体数据.NET MAUI应用程序与EF Core（视频在YouTube上）
• Preview Reports as PDF in .NET MAUI Apps using Backend Web API
  Service Endpoints with EF Core (videos on YouTube) 以PDF格式预览报告。使用带有EF
  Core的后端Web API服务端点的.NET MAUI应用程序（YouTube视频）

You can customize your own EF Core or XPO data model and fine-tune things at the XAF layer (security permissions, CRUD behavior, and so on).
您可以自定义自己的EF Core或XPO数据模型，并在XAF层微调（安全权限、CRUD行为等）。