2.5.1 使用Visual Studio 2017

启动Visual Studio 2017项目后，选择“文件”→ “新建”→“项目”，在弹出“新建项目”对话框中选择左侧的“Visual C#”节点选项，并在其下继续选择“.NET Core”节点，在右侧选择“ASP.NET Core Web应用程序”选项，为新项目输入一个名称HelloAPI，如图2-14所示。

单击“确定”按钮后会弹出图2-15所示的对话框。

Visual Studio默认提供了若干个ASP.NET Core项目模板，选择不同的模板会创建用于不同目的的应用程序或类库。这里我们选择“API”模板，使用该模板可以创建基于RESTful HTTP服务的Web API应用程序，然后单击“确定”按钮。

在图2-15所示的对话框中还提供了两个选项，即“启用Docker支持”和“为HTTPS配置”。

“启用Docker支持”选项将会在所创建项目中添加Docker容器所需要的文件，这对于将应用程序部署到Docker容器中很便利；

“为HTTPS配置”选项将使应用程序默认支持HTTPS，这个选项自ASP.NET Core 2.1后默认勾选。

除了这两个选项外，在窗口的右侧还可以为项目提供身份验证的功能，它的默认值为“不进行身份验证”。

图2-16展示了创建项目成功后的项目结构图。

在项目中，包含了如下若干个文件。

launchSettings.json：应用程序运行配置文件，包含了程序运行的相关配置，如URL和端口信息等。

wwwroot：文件夹，用于存储静态文件，如图片、CSS和JavaScript等文件。

依赖项：当前应用程序所依赖的NuGet包和SDK，其中Microsoft.ASP.NETCore.App含了ASP.NET Core应用程序要引用的API，而Microsoft.NETCore.App含了.NET Core中的所有API。

Controllers：文件夹，用于存储所有的Controller类文件，这些文件通常以Controller.cs结尾。

appsettings.json：配置文件，用于存储在应用程序运行时要用到的一些配置项。

Program.cs：程序入口类，ASP.NET Core应用程序从这个类中的Main函数运行，这与控制台程序完全一样。

Startup.cs：应用程序启动时的配置类，用于配置ASP.NET Core应用程序中的服务、中间件、MVC和异常处理等。

打开Controller文件夹下的ValuesController，其内容如下所示。

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // GET api/values
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1", "value2" };
    }
    // GET api/values/5
    [HttpGet("{id}")]
    public ActionResult<string> Get(int id)
    {
        return "value";
    }
    // POST api/values
    [HttpPost]
    public void Post([FromBody] string value)
    {
    }
    // PUT api/values/5
    [HttpPut("{id}")]
    public void Put(int id, [FromBody] string value)
    {
    }
    // DELETE api/values/5
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
    }
}

在这个Controller中包含了多个方法，它们均以Http开头的特性所标识，用于指明该方法是一个Action，以及它可以接受的HTTP请求方法。关于Controller与Action以及ASP.NET Core中的MVC模式，我们将在第3章中详细说明。将其中的Get(int id)方法改成如下代码。

[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
    return $"请求时id的值为{id}";
}

此时，程序可以直接运行。单击工具栏中的启动按钮，如图2-17所示，当前应用程序将会以IIS Express为其宿主运行。

展开启动按钮旁边的下拉菜单，如图2-18所示。

可以看到，在运行选项中，除了默认的IIS Express外，还有HelloAPI，也即应用程序自身的名字，这两个运行选项称为配置文件（Profile）。不同的配件文件会使Visual Studio在启动应用程序时采用不同的配置。在这两个配置文件中，选择IIS Express会使用IIS Express运行应用程序，它和直接以IIS作为应用程序的宿主很相似；而后者，以应用程序名称命名的配置文件，则会使用dotnet run来运行程序。

打开项目中Properties文件夹下的launchSetting.json文件，上述两个配置文件的信息都在这个JSON文件中，其内容如下所示。

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:60359",
      "sslPort": 44323
    }
  },
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "api/values",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "HelloAPI": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "api/values",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      },
      "applicationUrl": "https://localhost:5001;http://localhost:5000"
    }    
  }
}

它包含两个主要的节点iisSettings和profiles，前者主要用于配置IIS中的认证信息以及IIS Express运行时使用的URL和端口信息；后者则包含了所有的运行配置文件，即IIS Express和HelloAPI，在每个节点下，包括了若干配置项，如命令名称（commandName）、运行时是否启动浏览器（launchBrowser）、运行后在浏览器中要打开的URL（launchUrl）和环境变量（environmentVariables）等。

所有这些配置项，也可以在项目属性中的“调试”选项卡中配置，如图2-19所示。

无论使用哪个配置文件，当首次启用应用程序时，都会弹出类似图2-20的提示。

图2-20 信任IIS Express证书的警告

这是因为应用程序启用了HTTPS，此时就需要SSL证书。在开发时，通常使用自签名证书，在上述对话框中选择“是”，会信任IIS Express SSL证书并在当前计算机中安装证书。关于HTTPS与SSL证书，将在第8章中详细介绍。

默认情况下，当程序运行后，会以当前操作系统中默认的浏览器打开https://localhost:<端口>/api/values，如图2-21所示，在页面上显示了由服务器返回的字符串数组。

在地址栏中输入https://localhost:44323/api/values/7地址，按回车键后得到图2-22所示的结果。

除了使用浏览器查看结果外，更为常见的方式是使用Postman等软件来请求API，这是因为，浏览器只支持发起GET请求，而Postman以及同类软件则可以方便地使用所有常见的HTTP方法，如GET、POST、PUT、DELETE和PATCH等。

Postman是一款功能强大的HTTP调试工具，在开发和调试Web API应用时非常有用，它提供针对不同平台的版本以及针对不同浏览器的插件，可以到Postman官网中下载并安装。图2-23显示了在Postman中以GET方法请求api/values时的结果。