C# 新手必學：用 Visual Studio 2022 建立你的第一個 Hello API

在程式開發的世界裡，API (應用程式介面) 是現代應用程式不可或缺的元素。無論是網頁、手機應用程式，還是物聯網設備，都需要透過 API 進行資料交換。本文將帶你一步步使用 C# 與 Visual Studio 2022 建立一個簡單的 Hello API，即使你是初學者也能輕鬆上手！

為什麼選擇 C# 開發 API？

C# 是微軟開發的強大程式語言，具有以下優勢：

強大的 .NET 框架支援，提供豐富的內建函式庫
適合企業級應用開發，擁有完善的錯誤處理機制
Visual Studio 提供卓越的開發體驗和除錯工具
跨平台支援，透過 .NET Core 可在 Windows、Linux 和 macOS 上執行

🔧 環境準備與專案建立

在開始前，確保你已經安裝了 Visual Studio 2022。我們推薦使用 Community 版本，它對個人開發者和小團隊是免費的。

安裝必要的開發套件

在安裝 Visual Studio 2022 時，請確保勾選了「.NET 桌面開發」工作負載，這將包含我們需要的所有元件。

建立 Console 應用程式

接下來，我們將建立一個新的 Console 應用程式：

1. 開啟 Visual Studio 2022
2. 點選「建立新專案」
3. 在搜尋欄位輸入「Console」
4. 選擇「Console Application」(.NET Core)
5. 點選「下一步」
6. 專案名稱設定為「HelloAPI」
7. 選擇儲存位置後，點選「建立」

📝 提示

請確保選擇的是 .NET 6.0 (或更新版本) 的 Console 應用程式，這能提供更好的跨平台支援與效能。

💻 Hello API 程式碼實作

現在，讓我們替換 Program.cs 的內容，實作一個簡單的 HTTP 伺服器來提供 API 功能：

using System;
using System.Net;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
namespace HelloAPI
{
class Program
{
static async Task Main(string[] args)
{
// 建立 HTTP 監聽器
HttpListener listener = new HttpListener();
        // 設定前綴 (監聽哪些 URL)
        listener.Prefixes.Add("http://localhost:5050/");
        
        // 開始監聽
        listener.Start();
        Console.WriteLine("API 伺服器已啟動，正在監聽 http://localhost:5050/");
        Console.WriteLine("按 Ctrl+C 終止服務器...");

        try
        {
            while (true)
            {
                // 等待請求
                HttpListenerContext context = await listener.GetContextAsync();
                
                // 處理請求
                await ProcessRequestAsync(context);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"發生錯誤: {ex.Message}");
        }
        finally
        {
            // 停止監聽
            listener.Stop();
        }
    }

    static async Task ProcessRequestAsync(HttpListenerContext context)
    {
        HttpListenerRequest request = context.Request;
        HttpListenerResponse response = context.Response;

        // 設定回應格式
        response.ContentType = "application/json";
        
        // 建立回應內容
        var responseObject = new
        {
            Message = "Hello from C# API!",
            Timestamp = DateTime.Now,
            Path = request.Url?.PathAndQuery,
            Method = request.HttpMethod
        };

        // 序列化為 JSON
        string jsonResponse = JsonSerializer.Serialize(responseObject, new JsonSerializerOptions
        {
            WriteIndented = true
        });

        // 傳送回應
        byte[] buffer = Encoding.UTF8.GetBytes(jsonResponse);
        response.ContentLength64 = buffer.Length;
        await response.OutputStream.WriteAsync(buffer, 0, buffer.Length);
        
        // 關閉輸出流
        response.OutputStream.Close();
        
        Console.WriteLine($"{DateTime.Now} - 處理請求: {request.HttpMethod} {request.Url?.PathAndQuery}");
    }
}
}

🔍 程式碼解析

讓我們逐段解析上面的程式碼：

引用必要的命名空間

using System; 
using System.Net; 
using System.Text; 
using System.Text.Json; 
using System.Threading.Tasks;

這些命名空間提供了我們需要的類別：

• System.Net：包含 HttpListener 類別，用於建立 HTTP 伺服器
• System.Text：提供編碼功能，將字串轉換為位元組
• System.Text.Json：提供 JSON 序列化功能
• System.Threading.Tasks：提供非同步程式設計支援

設定 HTTP 監聽器

// 建立 HTTP 監聽器
HttpListener listener = new HttpListener();
// 設定前綴 (監聽哪些 URL)
listener.Prefixes.Add("http://localhost:5050/");
// 開始監聽
listener.Start();

這段程式碼創建了一個 HTTP 監聽器，並設定它監聽 localhost 的 5050 埠。你可以根據需要更改埠號或監聽的 IP 地址。

主迴圈：等待並處理請求

while (true)
{
// 等待請求
HttpListenerContext context = await listener.GetContextAsync();
// 處理請求
await ProcessRequestAsync(context);
}

這個無限迴圈會持續等待新的 HTTP 請求。每當收到請求時，程式會建立一個新的 HttpListenerContext 物件，然後將其傳遞給 ProcessRequestAsync 方法處理。

處理請求與回應

static async Task ProcessRequestAsync(HttpListenerContext context)
{
HttpListenerRequest request = context.Request;
HttpListenerResponse response = context.Response;
// 設定回應格式
response.ContentType = "application/json";

// 建立回應內容
var responseObject = new
{
    Message = "Hello from C# API!",
    Timestamp = DateTime.Now,
    Path = request.Url?.PathAndQuery,
    Method = request.HttpMethod
};

// 序列化為 JSON
string jsonResponse = JsonSerializer.Serialize(responseObject, new JsonSerializerOptions
{
    WriteIndented = true
});

// 傳送回應
byte[] buffer = Encoding.UTF8.GetBytes(jsonResponse);
response.ContentLength64 = buffer.Length;
await response.OutputStream.WriteAsync(buffer, 0, buffer.Length);

// 關閉輸出流
response.OutputStream.Close();
}

這個方法處理收到的 HTTP 請求，並產生一個 JSON 格式的回應。它獲取請求的詳細資訊、建立一個包含訊息、時間戳和請求資訊的物件，然後將其序列化為 JSON 並傳送回客戶端。

💡 重點說明

• 我們使用了匿名類型來建立 JSON 回應物件
• WriteIndented = true 選項使輸出的 JSON 格式化為易讀的格式
• 回應流程：序列化物件 → 轉換為位元組 → 寫入輸出流
• 別忘了關閉輸出流，這是釋放資源的好習慣

📝 擴充功能：處理 POST 請求

一個真正的 API 通常需要處理不同類型的 HTTP 請求。讓我們擴充程式碼以處理 POST 請求：

static async Task ProcessRequestAsync(HttpListenerContext context)
{
HttpListenerRequest request = context.Request;
HttpListenerResponse response = context.Response;
// 設定回應格式
response.ContentType = "application/json";

// 根據不同的請求方法進行處理
object responseObject;

switch (request.HttpMethod)
{
    case "GET":
        responseObject = new
        {
            Message = "Hello from C# API!",
            Timestamp = DateTime.Now,
            Path = request.Url?.PathAndQuery,
            Method = request.HttpMethod
        };
        break;
        
    case "POST":
        string requestBody;
        using (var reader = new StreamReader(request.InputStream, request.ContentEncoding))
        {
            requestBody = await reader.ReadToEndAsync();
        }

        responseObject = new
        {
            Message = "已接收 POST 請求",
            ReceivedData = requestBody,
            Timestamp = DateTime.Now
        };
        break;
        
    default:
        response.StatusCode = 405; // Method Not Allowed
        responseObject = new
        {
            Error = "不支援的 HTTP 方法",
            Method = request.HttpMethod
        };
        break;
}

// 序列化為 JSON
string jsonResponse = JsonSerializer.Serialize(responseObject, new JsonSerializerOptions
{
    WriteIndented = true
});

// 傳送回應
byte[] buffer = Encoding.UTF8.GetBytes(jsonResponse);
response.ContentLength64 = buffer.Length;
await response.OutputStream.WriteAsync(buffer, 0, buffer.Length);

// 關閉輸出流
response.OutputStream.Close();

Console.WriteLine($"{DateTime.Now} - 處理請求: {request.HttpMethod} {request.Url?.PathAndQuery}");
}

這個更新版本的處理方法可以區分 GET 和 POST 請求，並根據請求類型提供不同的回應。對於 POST 請求，它會讀取請求的內容並將其包含在回應中。

🧪 測試你的 API

編譯並執行你的專案後，你可以使用以下方法測試你的 API：

使用瀏覽器測試 GET 請求

在瀏覽器中輸入 http://localhost:5050/ 來測試 GET 請求。你應該會看到一個 JSON 回應，類似於：

{ 
"Message": "Hello from C# API!", 
"Timestamp": "2025-05-15T12:30:45.123456+08:00", 
"Path": "/", "Method": "GET" 
}

使用 Postman 測試 POST 請求

Postman 是一個功能強大的 API 測試工具，可以幫助你測試不同類型的 HTTP 請求：

1. 下載並安裝 Postman
2. 建立一個新的 POST 請求
3. 輸入 URL: http://localhost:5050/
4. 切換到「Body」標籤，選擇「raw」和「JSON」格式
5. 輸入測試資料：{ "name": "Test User", "message": "Hello API!" }
6. 點擊「Send」按鈕並觀察回應

💡 進階提示與最佳實踐

想要更進一步改善你的 API？這裡有一些建議：

安全性建議

啟用 HTTPS：在生產環境中，請務必使用 HTTPS 來保護資料傳輸。
實作身份驗證：考慮添加 JWT 或 API 金鑰等身份驗證機制。
輸入驗證：永遠驗證並消毒所有用戶輸入，防止注入攻擊。
錯誤處理：不要在生產環境中向客戶端洩露詳細的錯誤資訊。

效能優化

非同步處理：使用 Task.Run 來處理請求，避免阻塞主線程。
連接池：對於資料庫連接，使用連接池以提高效能。
快取機制：實作快取來減少重複計算和資料庫查詢。
壓縮回應：考慮使用 GZip 壓縮來減少網路傳輸量。

⚠️ 注意事項

此示例專案適合學習和本地開發，不建議直接在生產環境中使用。對於生產環境，請考慮使用 ASP.NET Core Web API 框架，它提供了更完整的功能、更好的安全性和可擴展性。

❓ 常見問題與解答

Q: 我需要管理員權限才能執行這個程式嗎？

A: 在 Windows 上，若要監聽低於 1024 的埠號（如 80 或 443），需要管理員權限。使用 8080 或其他高埠號則通常不需要特別權限。

Q: 如何處理不同的 URL 路徑？

A: 你可以使用 request.Url.AbsolutePath 來檢查請求的路徑，然後根據不同的路徑提供不同的回應：

switch (request.Url.AbsolutePath) {     case "/hello":         responseObject = new {Message = "Hello, World!"};         break;     case "/time":         responseObject = new {CurrentTime = DateTime.Now};         break;     default:         responseObject = new {Message = "Welcome to the API"};         break; }

Q: 如何在 API 中使用資料庫？

A: 你可以使用 ADO.NET 或 Entity Framework Core 來連接資料庫。這裡是一個使用 Entity Framework Core 的簡單例子：

// 首先通過 NuGet 添加 EF Core 依賴
// 例如: Microsoft.EntityFrameworkCore.SqlServer
// 然後定義你的 DbContext
public class ApiDbContext : DbContext
{
public DbSet<User> Users { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseSqlServer("你的連接字串");
}
}
// 使用範例
using (var db = new ApiDbContext())
{
var users = db.Users.ToList();
responseObject = new
{
    UserCount = users.Count,
    Users = users
};
}

總結

恭喜！你現在已經了解如何使用原生 C# 和 Visual Studio 2022 建立一個簡單的 Hello API。這只是 API 開發的起點，還有許多進階功能可以探索，如身份驗證、資料庫整合、跨域資源共享 (CORS) 等。

對於更複雜的專案，強烈建議考慮使用 ASP.NET Core Web API 框架，它提供了更豐富的功能和更好的開發體驗。然而，了解底層的 HttpListener 如何工作，對於深入理解 Web API 的原理非常有幫助。

希望這篇教學對你有所幫助！如果有任何問題或建議，歡迎在評論區留言分享。