Azure 应用服务中的 API 应用、ASP.NET 和 Swagger 入门
学习内容:
- 如何通过 Visual Studio 2015 中的内置工具在 Azure 应用服务中创建和部署 API 应用。
- 如何使用 Swashbuckle NuGet 包动态生成 Swagger API 元数据,以便自动进行 API 发现。
- 如何使用 Swagger API 元数据自动生成 API 应用的客户端代码。
Note
若要将 Visual Studio 连接到 Azure 中国区,可按使用 Visual Studio 2015 连接中国区 Azure中的说明操作。
如果使用的是 Visual Studio 2015 Update 2 或更高版本,可以按照以下图片中的说明,选中“启用隔离的 Azure Active Directory 配置”选项。
如果使用的是 Visual Studio 2017,可按 使用 Visual Studio 2017 连接中国区 Azure中的说明操作。
示例应用程序概述
本教程使用简单的待办事项列表示例应用程序。该应用程序包含单页应用程序 (SPA) 前端、ASP.NET Web API 中间层和 ASP.NET Web API 数据层。
下面是 AngularJS 前端的屏幕截图。
Visual Studio 解决方案包含三个项目:
ToDoListAngular - 前端:用于调用中间层的 AngularJS SPA。
ToDoListAPI - 中间层:调用数据层,对待办事项执行 CRUD 操作的 ASP.NET Web API 项目。
ToDoListDataAPI - 数据层:对待办事项执行 CRUD 操作的 ASP.NET Web API 项目。
三层体系结构是可以使用 API 应用实现的多种体系结构之一,此处仅用它来进行演示。每一层中的代码尽可能以最简单的方式来演示 API 应用功能;例如,数据层使用服务器内存而不是数据库作为持久性机制。
完成本教程后,将创建两个在云中应用服务 API 应用中启动并运行的 Web API 项目。
本系列教程的下一篇文章会将 SPA 前端部署到云中。
先决条件
ASP.NET Web API - 本教程中的说明假设读者基本了解如何在 Visual Studio 中使用 ASP.NET Web API 2。
Azure 帐户 - 可以打开 Azure 帐户。
Visual Studio 2015 和用于 .NET 的 Azure SDK - SDK 会自动安装 Visual Studio 2015(如果尚未安装)。
在 Visual Studio 中,单击“帮助”->“关于 Microsoft Visual Studio”,确保安装了“Azure App Service Tools v2.9.1”或更高版本。
Note
根据计算机上已有 SDK 依赖项数量的不同,安装 SDK 可能耗时较长,从几分钟到半小时或更长时间不等。
下载示例应用程序
下载 Azure-Samples/app-service-api-dotnet-to-do-list 存储库。
可以单击“下载 ZIP”按钮,或克隆本地计算机上的存储库。
在 Visual Studio 2015 或 2013 中打开 ToDoList 解决方案。
- 需要信任每个解决方案。
生成解决方案 (CTRL + SHIFT + B) 以还原 NuGet 包。
如果要在部署应用程序之前先查看应用程序的运行情况,可以在本地运行此应用程序。确保 ToDoListDataAPI 是启动项目,然后运行解决方案。应该会在浏览器中看到 HTTP 403 错误。
使用 Swagger API 元数据和 UI
Azure 应用服务内置 Swagger 2.0 API 元数据支持。每个 API 应用可以指定以 Swagger JSON 格式返回 API 元数据的 URL 终结点。从该终结点返回的元数据可用于生成客户端代码。
ASP.NET Web API 项目可以使用 Swashbuckle NuGet 包动态生成 Swagger 元数据。Swashbuckle NuGet 包已安装在所下载的 ToDoListDataAPI 和 ToDoListAPI 项目中。
在教程的此部分中查看生成的 Swagger 2.0 元数据,然后尝试使用基于 Swagger 元数据的测试 UI。
将 ToDoListDataAPI 项目(而不是 ToDoListAPI 项目)设置为启动项目。
按 F5 或单击“调试”>“开始调试”,以调试模式运行项目。
浏览器将打开并显示“HTTP 403 错误”页。
在浏览器的地址栏中,于 URL 行尾处添加
swagger/docs/v1
,然后按回车键。(URL 为http://localhost:45914/swagger/docs/v1
。)这是 Swashbuckle 用于返回 API 的 Swagger 2.0 JSON 元数据的默认 URL。
如果使用的是 Internet Explorer,浏览器将提示下载 v1.json 文件。
如果使用的是 Chrome、Firefox 或 Edge,浏览器将在浏览器窗口中显示 JSON。不同的浏览器有不同的 JSON 处理方式,因此浏览器窗口看起来可能与示例不完全相同。
以下示例显示了 API 的 Swagger 元数据的第一个部分(包含 Get 方法的定义)。在以下步骤中使用的 Swagger UI 由此元数据驱动,本教程稍后的部分将使用它来自动生成客户端代码。
复制{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "ToDoListDataAPI"
},
"host": "localhost:45914",
"schemes": [ "http" ],
"paths": {
"/api/ToDoList": {
"get": {
"tags": [ "ToDoList" ],
"operationId": "ToDoList_GetByOwner",
"consumes": [ ],
"produces": [ "application/json", "text/json", "application/xml", "text/xml" ],
"parameters": [
{
"name": "owner",
"in": "query",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": { "$ref": "#/definitions/ToDoItem" }
}
}
},
"deprecated": false
},
关闭浏览器并停止 Visual Studio 调试。
在“解决方案资源管理器”的 ToDoListDataAPI 项目中打开 App_Start\SwaggerConfig.cs 文件,然后向下滚动到第 174 行并将以下代码取消注释。
复制/*
})
.EnableSwaggerUi(c =>
{
*/
SwaggerConfig.cs 文件是在项目中安装 Swashbuckle 包时创建的。该文件提供配置 Swashbuckle 的多种方式。
已取消注释的代码将启用要在以下步骤中使用的 Swagger UI。作为一种安全措施,使用 API 应用项目模板创建 Web API 项目时,默认会注释此代码。
再次运行该项目。
在浏览器的地址栏中,于 URL 行尾处添加
swagger
,然后按回车键。(URL 为http://localhost:45914/swagger
。)当 Swagger UI 页出现时,请单击“ToDoList”查看可用方法。
单击列表中的第一个“Get”按钮。
在“参数”部分中,输入星号作为
owner
参数的值,然后单击“试用”。在后续教程中添加身份验证时,中间层将为数据层提供实际的用户 ID。现在,当应用程序在未启用身份验证的情况下运行时,所有任务都以星号作为其所有者 ID。
Swagger UI 调用 ToDoList Get 方法并显示响应代码和 JSON 结果。
单击“Post”,然后单击“模型架构”下面的框。
单击模型架构会预先填充输入框,可以在该框中指定 Post 方法的参数值。(如果这不适用于 Internet Explorer,请使用不同的浏览器或在下一步骤中手动输入参数值。)
按以下示例中所示,在
todo
参数输入框中更改 JSON,或者使用自己的描述文本替代:复制{
"ID": 2,
"Description": "buy the dog a toy",
"Owner": "*"
}
单击“试用”。
ToDoList API 返回表示成功的 HTTP 204 响应码。
单击第一个“Get”按钮,然后在页面的该部分中单击“试用”按钮。
Get 方法响应现在包含新的待办事项。
可选:还可以尝试使用 Put、Delete 和 Get by ID方法。
关闭浏览器并停止 Visual Studio 调试。
Swashbuckle 可用于任何 ASP.NET Web API 项目。如果要将 Swagger 元数据生成添加到现有项目,只需安装 Swashbuckle 包。
Note
Swagger 元数据包含每个 API 操作的唯一 ID。默认情况下,Swashbuckle 可能为 Web API 控制器方法生成重复的 Swagger 操作 ID。如果控制器有重载的 HTTP 方法(例如 Get()
和 Get(id)
),就会发生这种情况。有关如何处理重载的信息,请参阅自定义 Swashbuckle 生成的 API 定义。如果在 Visual Studio 中使用 Azure API 应用模板创建 Web API 项目,SwaggerConfig.cs 文件中会自动添加用于生成唯一操作 ID 的代码。
在 Azure 中创建 API 应用并向其部署代码
本部分使用已集成到 Visual Studio 的“发布 Web”向导中的 Azure 工具,在 Azure 中创建新的 API 应用。然后,将 ToDoListDataAPI 项目部署到新的 API 应用,并通过运行 Swagger UI 来调用 API。
在“解决方案资源管理器”中,右键单击 ToDoListDataAPI 项目,然后单击“发布”。
在“发布 Web”向导的“配置文件”步骤中,单击“Azure 应用服务”。
如果尚未登录,请登录到 Azure 帐户;如果凭据已过期,请刷新凭据。
在“应用服务”对话框中,选择要使用的 Azure 订阅,然后单击“添加”。
此时将显示“创建应用服务”对话框的“托管”选项卡。
由于部署的是已安装 Swashbuckle 的 Web API 项目,因此 Visual Studio 假设要创建 API 应用。“API 应用名称”标题指出了这一点,另外,从“更改类型”下拉列表已设置为“API 应用”也能看出这一点。
输入在 chinacloudsites.cn 域中唯一的 API 应用名称。可以接受 Visual Studio 建议的默认名称。
如果输入的名称已被使用,右侧会出现红色感叹号。
API 应用的 URL 为
{API app name}.chinacloudsites.cn
。在“资源组”下拉列表中单击“新建”,然后输入“ToDoListGroup”或其他喜好的名称。
资源组是 Azure 资源的集合,例如 API 应用、数据库、VM 等等。在本教程中,最好创建新的资源组,因为这样可以通过一个步骤轻松删除针对本教程创建的所有 Azure 资源。
使用此框可以选择现有资源组,或通过键入与订阅中任何现有资源组不同的名称,来创建新资源组。
单击“应用服务计划”下拉列表旁边的“新建”按钮。
屏幕截图显示了“API 应用名称”、“订阅”和“资源组”的示例值 -- 用户的值会有所不同。
以下步骤为新资源组创建应用服务计划。应用服务计划指定 API 应用运行所在的计算资源。例如,如果你选择免费层,则 API 应用程序将在共享 VM 上运行;如果你选择某些付费层,则它在专用 VM 上运行。有关应用服务计划的信息,请参阅应用服务计划概述。
在“配置应用服务计划”对话框中,输入“ToDoListPlan”或其他喜好的名称。
在“位置”下拉列表中,选择最靠近的位置。
此设置指定你的应用将在哪个 Azure 数据中心运行。选择最靠近的位置,尽量减少延迟。
在“大小”下拉列表中,单击“免费”。
对于本教程,免费定价层即可提供足够的性能。
在“配置应用服务计划”对话框中,单击“确定”。
在“创建应用服务”对话框中,单击“创建”。
Visual Studio 将创建 API 应用,以及包含 API 应用全部所需设置的发布配置文件。然后,将打开“发布 Web”向导来部署项目。
打开的“发布 Web”向导最初显示“连接”选项卡(如下所示)。
在“连接”选项卡上,“服务器”和“站点名称”设置指向 API 应用。“用户名”和“密码”是 Azure 创建的部署凭据。部署后,Visual Studio 将在浏览器中打开目标 URL(这是目标 URL 的唯一用途)。
单击“下一步”。
下一个选项卡是“设置”选项卡(如下所示)。可以在此处更改生成配置选项卡,部署用于远程调试的调试生成。该选项卡还提供了多个“文件发布选项”:
- 删除目标处的其他文件
- 在发布期间预编译
- 从 App_Data 文件夹中排除文件
在本教程中,不需要使用这些选项。有关这些选项的作用的说明,请参阅 How to: Deploy a Web Project Using One-Click Publish in Visual Studio(如何:在 Visual Studio 中使用一键式发布来部署 Web 项目)。
单击“下一步”。
接下来是“预览”选项卡(如下所示),用于查看哪些文件即将从项目复制到 API 应用。如果要将项目部署到前面已部署到的 API 应用,则只会复制已更改的文件。如果想要查看要复制的项列表,请单击“开始预览”按钮。
单击“发布”。
Visual Studio 随即将 ToDoListDataAPI 项目部署到新的 API 应用。“输出”窗口将记录成功的部署,在打开了 API 应用 URL 的浏览器窗口中会出现“已成功创建”页。
在浏览器的地址栏中,将“swagger”添加到 URL,然后按 Enter。(URL 为
http://{apiappname}.chinacloudsites.cn/swagger
。)浏览器将显示前面出现的相同 Swagger UI,但该 UI 现在在云中运行。尝试使用 Get 方法,会发现已返回到默认的 2 个待办事项。前面所做的更改已保存在本地计算机的内存中。
打开 Azure 门户。
Azure 门户是用于管理 Azure 资源(例如 API 应用)的 Web 界面。
单击“更多服务”>“应用程序服务”。
在“应用程序服务”边栏选项卡中,找到并单击新的 API 应用。(在 Azure 门户中,右侧打开的窗口称为边栏选项卡。)
将打开两个边栏选项卡。其中一个边栏选项卡包含 API 应用的概述,另一个包含可以查看和更改的一长串设置。
在“设置”边栏选项卡中,找到“API”部分并单击“API 定义”。
使用“API 定义”边栏选项卡可以指定以 JSON 格式返回 Swagger 2.0 元数据的 URL。当 Visual Studio 创建 API 应用时,会将 API 定义 URL 设置为前面所示的 Swashbuckle 生成的元数据默认值,即 API 应用的基 URL 加上
/swagger/docs/v1
。选择要为其生成客户端代码的 API 应用时,Visual Studio 将从此 URL 检索元数据。
Azure 应用服务中的 API 应用、ASP.NET 和 Swagger 入门的更多相关文章
- 怎样在 Azure 应用服务中生成和部署 Java API 应用
先决条件 Java 开发人员工具包 8(或更高版本) 已在开发计算机上安装 Maven 已在开发计算机上安装 Git Azure 订阅付费版或试用版 HTTP 测试应用程序,如 Postman 使用 ...
- 在 Azure WebApps 中运行64位 Asp.net Core 应用
作为微软下一代的开源的跨平台的开发框架, Asp.net core 正在吸引越来越多的开发者基于其构建现代 web 应用. 目前, Azure App Service 也实现了对 asp.net co ...
- 【Azure 应用服务】App Service/Azure Function的出站连接过多而引起了SNAT端口耗尽,导致一些新的请求出现超时错误(Timeout)
问题描述 当需要在应用中有大量的出站连接时候,就会涉及到SNAT(源地址网络转换)耗尽的问题.而通过Azure App Service/Function的默认监控指标图表中,却没有可以直接查看到SNA ...
- 【Azure 应用服务】App Service服务无法启动,打开Kudu站点,App Service Editor 页面均抛出:The service is unavailable
问题描述 App Service 服务URL无法访问,进入门户中的Advanced Tools(Kudu).App Service Editor (Preview)等页面无法打开, 打开就出现 The ...
- 【Azure 应用服务】App Service For Linux 部署PHP Laravel 项目,如何修改首页路径为 wwwroot\public\index.php
问题描述 参考官方文档部署 PHP Laravel 项目到App Service for Linux环境中,但是访问应用时候遇见了500 Server Error 错误. 从部署的日志中,可以明确看出 ...
- 【Azure 应用服务】App Service For Linux 部署Java Spring Boot应用后,查看日志文件时的疑惑
编写Java Spring Boot应用,通过配置logging.path路径把日志输出在指定的文件夹中. 第一步:通过VS Code创建一个空的Spring Boot项目 第二步:在applicat ...
- 【Azure 应用服务】一个 App Service 同时部署运行两个及多个 Java 应用程序(Jar包)
问题描述 如何在一个AppService下同时部署运行多个Java 应用程序呢? 问题解答 因为App Service的默认根目录为 wwwroot.如果需要运行多个Java 应用程序,需要在 www ...
- 不用虚机不用Docker使用Azure应用服务部署ASP.NET Core程序
一般我们写好了应用程序想要部署发布它,要么发布到物理机,要么发布到虚拟机,要么发布到容器来运行它.现在有了Azure应用服务,我们可以完全不用管这些东西,只管写好自己的代码,然后使用VisualStu ...
- 【Azure 应用服务】App Service .NET Core项目在Program.cs中自定义添加的logger.LogInformation,部署到App Service上后日志不显示Log Stream中的问题
问题描述 在.Net Core 5.0 项目中,添加 Microsoft.Extensions.Logging.AzureAppServices 和 Microsoft.Extensions.Logg ...
随机推荐
- python中的循环和编码,运算符, 格式化输出
1.while循环 现在让我们来看看python中的while循环 格式为 while 条件 循环体 (break) (continue) 中断循环的关键字有break和continue, brea ...
- java学习笔记—web计算器(36)
MVC模式 模式主要的任务是帮助开发者解决一类问题. MVC模式主要是用于规划你的网站的开发的一个基本的结构. Servlet记住充当的是控制器层.cn.itcast.controller Java类 ...
- 【ocp-12c】最新Oracle OCP-071考试题库(37题)
19.choose the best answer View the Exhibit and examine the structure of the PROMOTIONS table. Evalua ...
- grunt 常用插件
grunt-contrib-uglify:代码压缩 grunt-contrib-jshint:检查js拼写错误 csslint:检查css语法错误
- Nodejs Express模块server.address().address为::
来自 http://blog.csdn.net/medivhq/article/details/74171939 我按照菜鸟教程上的写法为:(http://www.runoob.com/nodejs/ ...
- 基于注解的Spring容器源码分析
从spring3.0版本引入注解容器类之后,Spring注解的使用就变得异常的广泛起来,到如今流行的SpringBoot中,几乎是全部使用了注解.Spring的常用注解有很多,有@Bean,@Comp ...
- Java性能优化技巧及实战
关于Java代码的性能优化,是每个javaer都渴望掌握的本领,进而晋升为大牛的必经之路,但是对java的调优需要了解整个java的运行机制及底层调用细节,需要多看多读多写多试,并非一朝一夕之功.本文 ...
- 安卓手机移动端Web开发调试之Chrome远程调试(Remote Debugging)
一.让安卓打debug模式的apk包 二.将电脑中的chrome升级到最新版本,在chrome浏览器地址栏中输入chrome://inspect/#devices: 在智能手机还未普及时,移动设备的调 ...
- C#二进制位算 权限
关于权限管理,之前所做的都是一个权限对应一条数据,比方A页面有增删改查四个权限,那么用户在权限管理表中相对应AA页面有四条记录.后来改用二进制运算,发现省事很多. 首先说下位运算 熟悉一下操作符,懒得 ...
- c# timer使用
C#里现在有3个Timer类: System.Windows.Forms.Timer System.Threading.Timer System.Timers.Timer 这三个Timer我想大家对S ...