📘 前言

在區塊鏈應用開發中，.NET 開發者可以透過 Nethereum 這個強大的函式庫，輕鬆地與 Ethereum 相容的區塊鏈互動。本文將以 Polygon Amoy 測試網為例，實作查詢帳戶餘額、檢查交易狀態、寫入及讀取智能合約資料的完整流程。

🧰 環境準備

套件安裝

在你的 .NET 專案中執行下列指令以安裝必要套件：

Install-Package Nethereum.Web3
Install-Package Nethereum.Accounts
Install-Package Nethereum.Contracts

開發環境準備

✅ .NET 7 或以上
✅ 測試鏈 RPC 連線：
本文使用 Polygon Amoy 測試網
RPC URL：https://rpc-amoy.polygon.technology
✅ 測試智能合約地址：
用於寫入資料的合約部署在 Amoy 測試網
合約位址：0x2ef7F7790BB7B85D2FebF425A05c759c9961488b
✅ 一組擁有測試幣的帳戶私鑰（⚠️ 請勿使用主網私鑰）
✅ 推薦錢包工具：
小狐狸錢包（MetaMask）官方網站
建議使用 MetaMask 錢包建立測試帳戶並申請 Amoy 測試幣

💡 測試幣取得方式與常見問題

🔄 如何取得 Amoy 測試幣（MATIC）

Polygon 官方提供 Faucet 可用來領取 Amoy 測試幣：

👉 Amoy Faucet 官方入口

步驟如下：

將你的測試帳戶地址貼上到網站中
選擇 Amoy 測試網
點擊申請，等待鏈上確認（有時需等待幾分鐘）

🌟 重要密技：進階申請測試幣（POL）表單

如果你需要較大量的 Amoy 測試代幣，可以填寫官方提供的 Google 表單申請：

👉 申請 Amoy 測試代幣表單

⚠️ 請注意：

每個專案每 90 天最多只能申請 500 顆 POL 測試代幣。
無需審核的上限為 500 顆，超過將不會被受理。
建議填寫項目簡潔、用途明確，能提升通過機會。

⚠️ 開發初期常見困擾：測試幣太少

由於 Amoy Faucet 每次發放金額有限，且全球開發者共用資源，可能會遇到以下情況：

Faucet 回應過慢或顯示錯誤
MATIC 數量不足以覆蓋交易 gas
部署或多次互動失敗

🔧 建議：

可嘗試不同時間重試 Faucet
控制交易 Gas 設定避免浪費
可聯絡社群或開發者社群管道交換額外測試幣

🦊 如何在小狐狸錢包新增 Polygon Amoy 測試網

步驟一：安裝與登入小狐狸錢包

請先在瀏覽器中安裝 MetaMask（小狐狸錢包）擴充套件，並完成登入或建立帳戶流程。

步驟二：從瀏覽器加入 Amoy 測試網

前往 Amoy 測試鏈瀏覽器頁面，拉到最下方，點擊 「Add Polygon Amoy Network」 按鈕。

步驟三：確認測試網已加入

完成授權後，打開 MetaMask，在左上角的網路選單中，即可看到 Polygon Amoy Testnet 已成功加入。

💰 查詢帳戶餘額

我們可以使用 Nethereum 提供的 Web3 物件，來查詢指定地址在 Polygon Amoy 測試網上的 POL（MATIC）餘額。

var web3 = new Web3("https://rpc-amoy.polygon.technology");
string address = "0x0dB390F2A618F9311dec1ec347787A8faecfdaFb";
var balance = await web3.Eth.GetBalance.SendRequestAsync(address);
var etherAmount = Web3.Convert.FromWei(balance.Value);
Console.WriteLine($"帳戶 POL 餘額為: {etherAmount}");

每一段說明：

建立 Web3 物件並指定 Amoy 測試鏈 RPC
設定目標地址
向鏈上查詢該地址餘額
將 Wei 轉換為較易讀的 MATIC 單位

🔍 檢查交易狀態

以下方法可透過交易哈希查詢交易是否上鏈，並顯示其詳細資訊：

public async Task CheckTransactionStatus()
{
	var web3 = new Web3("https://rpc-amoy.polygon.technology");
	string txHash = "0x54fb98b395c4ca03c977900802aac010dc1729775b9256f7a5f0828594f7d713";
	var receipt = await web3.Eth.Transactions.GetTransactionReceipt.SendRequestAsync(txHash);

	if (receipt == null)
	{
		Console.WriteLine("🚧 交易尚未上鏈或找不到！");
		return;
	}

	Console.WriteLine($"✅ 交易已上鏈！區塊編號：{receipt.BlockNumber.Value}");
	Console.WriteLine($"📦 狀態：{(receipt.Status.Value == 1 ? "成功 ✅" : "失敗 ❌")}");
	Console.WriteLine($"⛽ Gas Used：{receipt.GasUsed.Value}");
	Console.WriteLine($"📍 合約地址（若有部署）：{receipt.ContractAddress}");
	Console.WriteLine($"🧾 Logs 數量：{receipt.Logs.Count}");
}

📷 圖片說明建議位置：

🔍 顯示如何在區塊鏈瀏覽器查詢交易哈希（例如 polygonscan）
📦 顯示交易回執成功的區塊畫面
⛽ 顯示 Gas Used 的資訊欄位

每一段功能說明：

透過 txHash 指定欲查詢的交易
使用 GetTransactionReceipt 發送查詢
若查無結果，顯示「尚未上鏈」提示
若查詢成功，依序顯示：
- 區塊編號
- 狀態（成功/失敗）
- 實際消耗 Gas 數量
- 是否部署出合約位址
- 是否產生事件 Logs 數據

💻 從瀏覽器測試合約函式（PolygonScan）

如果你想快速驗證合約功能或模擬呼叫行為，可以透過區塊鏈瀏覽器（如 Amoy Polygonscan）進行操作：

前往合約頁面（例如你的合約地址：https://amoy.polygonscan.com/address/0x2ef7F7790BB7B85D2FebF425A05c759c9961488b）
點選「Contract」頁籤，切換到「Write Contract」或「Read Contract」
若為寫入操作（需交易），需先透過小狐狸錢包登入帳號，並授權該操作
輸入參數並提交交易，即可與合約互動

1️⃣ 點選「Contract」頁籤
切換至「Contract」區段，才能看到合約公開的程式碼與互動功能。
2️⃣ 點選「Write Contract」分頁
若你想執行需要交易的合約函式（例如寫入資料），請切換至此分頁。這裡列出所有可以呼叫的 write functions。
3️⃣ 連接你的錢包（Connect to Web3）
點擊「Connect to Web3」後，系統會提示你連接小狐狸錢包。成功連接後才能執行交易，否則按鈕無效。

✍️ 寫入資料至智能合約

先建立 FunctionMessage 類別以對應合約函式：

[Function("insertData", "uint256")]
public class InsertDataFunction : FunctionMessage
{
    [Parameter("uint256", "requestId", 1)]
    public BigInteger RequestId { get; set; }

    [Parameter("string", "data", 2)]
    public string Data { get; set; }
}

然後透過 GetContractTransactionHandler 寫入資料：

var account = new Account(privateKey);
var web3 = new Web3(account, "https://rpc-amoy.polygon.technology");
var insertFunction = new InsertDataFunction()
{
    RequestId = 426,
    Data = "今晚打老虎"
};

var handler = web3.Eth.GetContractTransactionHandler<InsertDataFunction>();
var txReceipt = await handler.SendRequestAndWaitForReceiptAsync(contractAddress, insertFunction);

Console.WriteLine($"交易成功，Hash：{txReceipt.TransactionHash}");

📖 從智能合約讀取資料

定義查詢用函式：

[Function("showData", "string")]
public class ShowDataFunction : FunctionMessage
{
    [Parameter("uint256", "requestId", 1)]
    public BigInteger RequestId { get; set; }
}

執行查詢：

var showDataFunction = new ShowDataFunction
{
    RequestId = new BigInteger(2)
};

var handler = web3.Eth.GetContractQueryHandler<ShowDataFunction>();
var result = await handler.QueryAsync<string>(contractAddress, showDataFunction);

Console.WriteLine($"📦 showData({requestId}) 回傳值：{result}");

✅ 總結

使用 Nethereum 可以輕鬆整合以太坊相容鏈功能至 .NET 專案
本文涵蓋：帳戶查詢、交易查詢、資料寫入與讀取合約
可進一步延伸實作：事件監聽、多簽帳戶支援、Gas 控制策略等

🔗 延伸閱讀：

Csharp Nethereum.Web3 區塊鏈

打造你的第一個以太坊應用：Nethereum.Web3 基礎操作教學