使用 VS CODE 建立你的第一个 ASP.NET Core API 项目

在这一篇文章里, 我将介绍如何使用 VS Code 建立一个完整的ASP.NET Core 项目！在这里不得不再次说一下使用 VS CODE 做开发实在是太舒服了！OK，废话少说，让我们开始吧！

1. 创建项目

1) 首先建立一个名为 Demo 的文件夹，接著在 VS Code 里打开(我通常是直接将目录拖进 VS Code) 里面建立一个名为 MyDemo.API 的文件夹。你可以在 VS Code 里打开 MyDemo.API，或是直接将它拖曳到 VS CODE 里。

2) 点击左侧栏的 vscode solution 按钮，打开解决方案面板，接著点击 Create New Solution 创建新的解决方案，名字就叫做 MyDemo.API。

3) 在解决方案文件上按右键，选择 add new project，选择 asp.net core api，选择 c#，然后输入项目名称，这里我们用 MyDemo.API，之后会让你输入项目资料夹名称，只要和项目名称一样即可。完成后就会建立一个完整的 ASP.NET Core 项目了。

2. 启动项目

1) 建立完后，可点击左侧的调试按钮，然后打开调试面板，里面会有提示让你建立相关调试档案的按钮。

2) 可以尝试直接调试启动项目，并测试 API 的效果。这时可能会遇到 CORS 跨站错误的问题（这里可以解释一下相关的 CORS 知识）。解决办法是在 program.cs 档案里添加以下程式码即可。

//allow cross-origin access for the api
builder.Services.AddCors(o => o.AddPolicy("AllowCrosite", policy =>
{
    policy.AllowAnyHeader()
        .AllowAnyMethod()
        .SetIsOriginAllowed(origin => true) // allow any origin
        .AllowCredentials();
}));

3. 建立数据库

1. 好的，现在你已经建立了基本的 API 网站，接下来要实现数据的读取。在这里我们先讲一下整个 API 项目的架构。因为这个范例是要做得比较清晰简单，所以项目层次结构不会太复杂。我们只需要再建立一个 CORE 和 UTILITY 的项目就好了。其中 CORE 项目放置底层资料 MODEL 和相关操作逻辑，而 UTILITY 项目则是一些通用的功能元件。这个结构简单明了，也适合一般的中小型项目所需。

2. OK，接下来我们要建立另外两个项目。由于这两个项目只是类库形式的，所以在使用 vscode solution 建立时，选择 Class Library 就可以了。同时一般为了保持整体项目风格和格式，命名上也统一将每个项目前都加上 MyDemo，因此两个项目名分别是 MyDemo.Core、MyDemo.Utility。

3.1 什么是ORM

我们将会使用 Entity Framework 做为资料操作的 ORM 框架（介绍一下 ORM）

这里简单地说一下关于 EF 建立资料操作的方式吧，主要方式有两种，一种是 DB First，另一种是 Code First。DB First 就是比较传统的方式，即先要设计好整体数据库结构，然后直接在数据库里建立好各个资料表，再透过 EF 映射过来，在项目中自动建立每个表对应的实体类别；这种方式一般是要先写好相关建立表的 SQL 语句以作备用，好处是对于一些比较复杂的结构也可以直接用 SQL 完成，由于所有 SQL 一开始已设计好，所以整体上会感觉比较清晰，但缺点就是如果要同时支援不同类型的数据库就很不方便，要写各种不同类型的 SQL 语句，还有如果要迁移到新的数据库也是一件比较麻烦的事情。

另一种方式就是 Code First。顾名思义就是先写程式码，然后再生成资料表。这种方式好处是你只需要专心设计好每个实体类别的程式码，并不需要写任何的 SQL 语句，因此可以非常方便地支援多种不同类型的数据库，框架会自动为你生成不同数据库所需的 SQL，而更让人惊喜的是，你甚至连数据库档案也不需要建立，只需设定好相应的数据库伺服器连线就好，框架会自动建立整个数据库和相关表，这样就对迁移数据库的操作非常有帮助了，你只要一套完整的程式码，放到哪里运行都没问题！

所以, 为了方便迁移资料，也不想写这么多 SQL 语句，因此本项目也会使用 Code First 的形式进行。

然后设置好项目之前的引用。这里新建立的 CORE 和 Utility 项目均是为 API 服务的，所以要在 API 项目里添加这2个的引用。

3.2 使用 EF

在 MyDemo.Core 项目里，建立 Data 目录，这将存放所有资料表有关的实体类别和相关的 Code First 代码。

要使用 EF，需要先安装以下 package，我们可以透过 NuGet Gallery 直接安装，但要注意的是，需要将 package 同时安装到 MyDemo.Core 和 MyDemo.API 2个项目中。

接下来就要添加数据库的连线字串到 MyDemo.API\appsettings.json 档案里。 然后就到了最关键的部分了，就是为你的实体类别项目添加 Code First 的支持。

首先让我们建立一个使用者表的实体类别。在 Data 目录下建立一个 Entity 的目录，然后在此目录下建立一个 User.cs 的实体类别。

3.3 关于表的设计

在此先说明一下关于表的设计思路。假设现在我们要建立一个最简单的使用者，里面要包括的属性有

使用者ID
名称
密码
邮件

在基本资讯上这几个是够用的了，但对于一个项目来说，操作一张表除了让使用者看到的资讯之外，还需要有一些状态资讯要处理的，如对记录的停用操作，可能管理员因某些原因暂时停用了，还有想知道当时何时建立这条记录，何时曾经更新过，再对资料安全性较高的系统，还会做一个软删除的操作，即并不是真正删除了当前记录，只是用一个标记表示状态是已被删除了。这样做的原因是防止使用者直接删除非常重要的资料。

因此，在设计表时，应该再包括以下几个固定的属性：

是否启用的状态
是否删除了
建立时间
修改时间

由于这几个是公共栏位，即每张表都应该要有的，所以我们可以建立一个公共的实体基类来放，名字可叫做 BaseEntity，也可以将 ID 也放入其中，由于这个基类的任务只是被别人继承也不需要实现的，所以可以使用抽象类，然后再将 User 继承自 BaseEntity，这样就不需要每次都写这些公共栏位了。

在建立完实体类别的属性后，还需要为其设置好在数据库里的表名，因为有时类名并不一定就和表名一样的，要设置表名，可以使用 [Table("name")] 的属性，只需将其添加到类上即可。同时为了更好的效能，最好再为表添加索引，我们可直接使用唯一的ID 属性来做索引，也是在类上添加 [Index(nameof(Id))] 即可。

最后，我们还需要为此实体类别设置好一些栏位在数据库里的情况，如 ID 是必须要输入的，建立时间自动按当前资料的储存时间，还有一些栏位的长度大小等。这些设置都可以透过 IEntityTypeConfiguration 这个介面实现。

3.4 创建 DbContext

当完成了实体类别后，就要建立一个 DbContext，即数据库上下文的类别来处理资料，我们在此将其命名为 ApplicationDbContext，这个类别是要继承自 DbContext 的.

在 ApplicationDbContext 里要重写 OnModelCreating 方法，目的就是为了将刚才在实体类别里写的 IEntityTypeConfiguration 生效。最后就是将 User 的实体类别与具体的资料表联系起来，即添加一个 DbSet 的物件，以后就可以透过这个物件直接操作数据库里的表了。

最后还要在 API 项目的 program.cs 档案里添加使用数据库的服务。要注意的是，所添加的服务程式码必须要放到建立 builder app 之前喔！

// Add ApplicationDbContext and SQL Server support
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"))
);

var app = builder.Build();

3.5 创建数据库代码

现在可以开始写指令生成相关的 EF 迁移代码了。不过在执行相关指令之前，需要在 VS CODE 里打开终端机，然后进入到解决方案的根目录下，因为之后的相关 EF 指令，都需要在这里执行的，当然你也可以在其他目录执行，但就要修改指令里项目的路径。

执行以下指令以生成相关的数据库程式码迁移的档案。

dotnet ef migrations add InitialMigrations --project .\MyDemo.Core\MyDemo.Core.csproj --startup-project .\MyDemo.API\MyDemo.API.csproj 

然后再执行指令将程式码更新到数据库。

dotnet ef database update --project .\MyDemo.Core\MyDemo.Core.csproj --startup-project .\MyDemo.API\MyDemo.API.csproj 

执行完后，就可以打开数据库要看一下看是否有新添加的表。

4. 总结

现在我们来总结一下之前所说到的内容，我们知道了如何搭建 VS CODE 的开发环境，如何创建一个项目，而且也已成功创建了一个 API 项目，同时也创建了一个使用者表的数据库，接下来就要为这个表创建 CRUD（这是个程式设计中的资料操作术语，代表的是增删改查等操作，全称即是：Create, Read, Update, Delete），但在讲这些操作方法之前，我们需要了解一下设计模式，一个好的设计模式，可以将程式码规范，提高效率，所以在下一篇文章里，我会为大家讲解 Repository 这一模式和使用。

相关文章：

如何配置开发 ASP.NET Core 项目的 VS Code 环境 VSCode 常用快捷键，扩展推荐和 Flutter 开发的配置