---
slideOptions:
showNotes: false
---

# .Net Core Web API 基本教學

---

## 基本簡介

----

### 什麼是 .Net Core

* 微軟開發的第一個<span style="color:red">跨平台</span>的應用程式開發框架
* 為 <span style="color:red">.NET 5 +</span> 之前版本的名稱

* .NET Core 1.0、1.1、2.0、2.1、2.2、3.0、3.1
* .NET 5、6

Note:

* 為甚麼使用 3.1

* .NET 6 為較新版本，資源可能相對較少
* .NET 5 並不是長期支援版本，到今年 5 月

* 直接跳 .NET 5 避免跟 .NET Framework 4.X 搞混

----

### .Net Core 與 .NET Framework

* <span style="color:red">.Net Core</span> 是 .NET Framework 的<span style="color:red">新一代版本</span>

* .NET Framework 最新版本到 <span style="color:red">4.8</span>

* 運行環境

* .NET Core 能在 <span style="color:red">Windows</span>、<span style="color:red">MacOS</span>、<span style="color:red">Linux</span> 上運行
* .NET Framework 只能在 <span style="color:red">Windows</span> 上運行

* .NET Core 會包含 .NET Framework 的類別庫

---

## 安裝 SDK 與 Runtime

Note:

* 下載位置 : [Download .NET](https://dotnet.microsoft.com/en-us/download/dotnet)

----

### SDK ( 用於<span style="color:red">開發建置</span> )


Note:

* 本身包含 Runtime

----

### Runtime ( 用於<span style="color:red">執行</span> )


Note:

* IIS 上執行須安裝 Hosting Bundle，包含 IIS runtime support

---

## 建立新專案

----

### Visual Studio 2022


----


----

### Visual Studio Code

dotnet new webapi -o NETCoreWebAPITest

Note:

* 在要放專案的目錄下執行此命令，例如 : source\repos\
* 或是建立專案名稱資料夾執行 `dotnet new webapi`

---

## 專案內容

----

### 檔案架構


* 相依性 : <span style="color:red">組件參考</span>、<span style="color:red">NuGet</span>
* Controller : 控制器，用於<span style="color:red">處理 Web API 要求</span>
* Program.cs : 程式的<span style="color:red">進入點</span>
* Startup.cs : 負責<span style="color:red">基礎設定檔</span>的執行

Note:

* 相依性

* 相依性的組件參考設定會記錄在 .csproj 中

* Controller

* Controllers 主要處理路由、回應格式、寫 LOG
* 另外註冊 Service 注入 Controller 來處理邏輯

* WeatherForecast.cs 可以放在 Models 資料夾裡

----

### 程式架構

#### Program.cs


* 呼叫 <span style="color:red">CreateHostBuilder</span> 建立 Web 的預設組態環境並載入 Startup

Note:

* 參考 : [ASP.NET Core 中的 .NET 泛型主機](https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/host/generic-host?view=aspnetcore-3.1)
* 以前用 IWebHostBuilder，現在建議都用 IHostedBuilder 了

----

#### Startup.cs : ConfigureServices


* 由 Runtime 呼叫，<span style="color:red">負責向容器註冊 Service</span>
* 一旦註冊了，所有類別都<span style="color:red">能向容器獲取此實例</span>
* 註冊時<span style="color:red">可以決定該實例的生命週期</span>，分為三種

* AddTransient
* AddScoped
* AddSingleton

Note:

* 參考 : [ASP.NET Core 中的應用程式啟動](https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/startup?view=aspnetcore-3.1)、[.NET Core 中的相依性插入](https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-3.1)
* AddTransient : 週期為每次請求到請求結束，每次請求都是一個新的實例
* AddScoped : 週期為客戶端的連結到結束
* AddSingleton : 週期為應用程序的開始到結束，每個請求都使用相同實例

----

#### Startup.cs : Configure


* 由 Runtime 呼叫，<span style="color:red">負責指定應用程式如何響應請求</span>
* 可在此插入<span style="color:red">中介軟體</span>

Note:

* 參考 : [ASP.NET Core 中介軟體](https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/middleware/?view=aspnetcore-3.1)
* UseDeveloperExceptionPage : 回報應用程式執行階段錯誤
* UseHttpsRedirection : 會將 HTTP 要求重新導向到 HTTPS
* UseRouting : 路由要求
* UseAuthorization : 授權使用者存取安全資源
* UseEndpoints : 將呼叫端點引導至要求方法

----

### Controller 如何使用 Service

----

#### 加入 Service

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddSingleton<TestService>();
    ...
}

* Startup.cs : ConfigureServices

----

#### 使用 Service

public class WeatherForecastController : ControllerBase
{
    ...
    private TestService _service;

    public WeatherForecastController(TestService service)
    {
        _service = service;
    }
    ...
}

* Controller

----

### 路由

* 透過路由才能讓應用程式知道此次請求須<span style="color:red">交由哪個方法處理</span>
* 為了<span style="color:red">讓使用者明瞭 API 是做甚麼的</span>，路由的設計也很重要

Note:

* 參考 : [ASP.NET Core 中的路由](https://docs.microsoft.com/zh-tw/aspnet/core/fundamentals/routing?view=aspnetcore-3.1)

----

#### 在 Controller <span style="color:red">類別</span>套用屬性

[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    ...
}

* 常用屬性 : <span style="color:red">controller</span>、<span style="color:red">action</span>

* 使用純文字或是和屬性<span style="color:red">混合使用</span>，例如 :

    [Route("api/[controller]/[action]")]

----

#### 在 Action <span style="color:red">方法</span>套用屬性

[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
    ...
}

* 決定 HTTP 協議中<span style="color:red">傳送請求的方式</span>

* HttpGet、HttpPost、HttpDelete、HttpPut

* 接著加上路由，例如 :

    [HttpGet("product/{id:int}")]

* 不使用路由傳遞 : GET .../product?id=1

---

## 套件分享

----

### Swagger

* 透過產生器就可<span style="color:red">自動生成 API 文件</span>供對接者查看
* 也能透過文件進行<span style="color:red">線上測試</span>

Install-Package Swashbuckle.AspNetCore -Version 6.2.3

Note:

* 參考 : [Swashbuckle 與 ASP.NET Core 使用者入門](https://docs.microsoft.com/zh-tw/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio)

----

#### Startup.cs : ConfigureServices


* Swagger 產生器，<span style="color:red">可產生一到多份檔案</span>
* 產生 <span style="color:red">XML 檔</span>

----

#### <span style="color:red">註解</span>可以在文件上更<span style="color:red">詳細描述 API</span>



Note:

* 可以設定回傳格式、描述回應類型、要求範例...

----

#### Startup.cs : Configure


* <span style="color:red">UseSwagger 產生 JSON 檔</span>，位置 : /swagger/v1/swagger.json
* <span style="color:red">UseSwaggerUI 產生網頁</span>，位置 : /swagger/index.html

----

### NLog

* 依日期時間<span style="color:red">記錄 Log</span>
* 方便<span style="color:red">日後維護</span>或<span style="color:red">查看歷史呼叫紀錄</span>

Install-Package NLog -Version 4.7.15
Install-Package NLog.Web.AspNetCore -Version 4.14.0

Note:

* 參考 : [Getting started with ASP.NET Core 3](https://github.com/NLog/NLog/wiki/Getting-started-with-ASP.NET-Core-3)

----

#### 建立 nlog.config


* 包含<span style="color:red">加入 .net core 擴展</span>、<span style="color:red">設定目標</span>、<span style="color:red">設定規則</span>

Note:

* 參考 : [Configuration file](https://github.com/NLog/NLog/wiki/Configuration-file)

----

#### nlog.config 啟用複製


Note:

* 在發佈時，才會將設定好的 nlog.config 帶過去

----

#### program.cs


----

#### appsettings.json


* 這邊的 Default <span style="color:red">會覆蓋 nlog.config 的 minievel</span>

Note:

* 若這邊設定的層級較高，nlog.config 那邊的層級設為較低也不會記錄該層級

----

#### 如何使用

private readonly ILogger<WeatherForecastController> _logger;

public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
    _logger = logger;
    _logger.LogDebug("NLog injected into WeatherForecastController");
}

* LogCritical、LogError、LogWarning、LogInformation、LogDebug、LogTrace

Note:

* Critical : 致命
* Error : 錯誤
* Warning : 警告
* Information : 資訊
* Debug : 偵錯
* Trace : 追蹤

----

### 統一回復錯誤格式

* 避免使用者看到錯誤細節，方便其處理錯誤

----

#### Startup.cs : Configure

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Unite/Error");
    }
}

----

#### ErrorController


---

## 建置與執行

----

### Visual Studio Code

建置

dotnet build

建置與執行

dotnet run

建置與執行並監看檔案

dotnet watch run

Note:

* 預設網址為 : https://localhost:5001、http://localhost:5000/
* 可在 `Properties` > `launchSettings.json` 更改

---

## 佈署

----

### 資料夾

* 只需將<span style="color:red">發佈出來的資料夾內容</span>放入<span style="color:red">站點的實體路徑</span>即可

----

#### Visual Studio


----


----


Note:

* 新增 : 新增設定檔
* 更多動作 : 重新命名、編輯、刪除

----

#### Visual Studio Code

dotnet publish --configuration Release 

* 路徑 : .\bin\Release\netcoreapp3.1\publish

----

### 網頁伺服器 ( IIS )


* 透過 Web Platform Installer 安裝 Web Deploy

Note:

* 參考 : [設定 Web Deploy 發行的網頁伺服器 (Web Deploy 處理常式) - 建立和設定 IIS 網站](https://docs.microsoft.com/zh-tw/aspnet/web-forms/overview/deployment/configuring-server-environments-for-web-deployment/configuring-a-web-server-for-web-deploy-publishing-web-deploy-handler#create-and-configure-an-iis-website)
* 下載位置 : [Web Platform Installer](https://www.microsoft.com/web/downloads/platform.aspx)
* 沒有看到佈署按鈕 :

* 需安裝 `Web Deploy 3.6`、`Web Deploy 3.6 without bundled SQL support`、`Web Deploy 3.6 for Hosting Servers`
* `開啟或關閉 Windows 功能` 需開啟 `IIS 管理服務`
* 確認 `Web Deployment Agent Service`、`Web Management Service` 兩個服務有開啟
* `控制台/程式集/程式和功能` 中的 `Microsoft Web Deploy 3.6` 變更查看功能是否都有開啟

----


Note:

* 可選擇其他身分或在 IIS 上建立使用者來避免發佈人員直接擁有管理者權限
* `指定發行伺服器連線的 URL` 須記下來

----

#### Visual Studio 2022


----


----


Note:

* `目的地 URL` 為 IIS 上設定的 `指定發行伺服器連線的 URL`

---

## Q&A

----

###### tags: `筆記` `簡報` `.Net Core` `WebAPI` `IIS`