.NET 教學課程 - 您的第一個微服務
入門
目的
熟悉使用 .NET 建立微服務的建置組塊。
必要條件
無。
macOS 12.0 或更新版本。
完成時間
15 分鐘
情節
建立可傳回值清單的簡易服務,然後在 Docker 容器中執行該服務。
安裝 .NET SDK
若要開始組建 .NET 應用程式,請下載並安裝 .NET SDK。
下載 .NET 8 SDK x64 (Intel)
下載 .NET 8 SDK Arm64 (Apple Silicon)
如果您使用的 Mac 上有 Apple M1 或 M2 晶片,則必須安裝 Arm64 版本的 SDK。
檢查是否已正確安裝所有項目
安裝完成後,請開啟新命令提示字元,然後執行下列命令:
安裝完成後,請開啟 [新增] 終端,然後執行下列命令:
dotnet --version
如果安裝成功,您應該會看到輸出的版本 8.0.100 或更新版本:
8.0.100
如果一切順利,請選取下方的 [繼續] 按鈕以移至下一個步驟。
發生錯誤嗎?
如果您收到 ['dotnet' 無法辨識為內部或外部命令] 錯誤,請確定您已開啟新的命令提示字元。如果快速重新啟動您的機器無法解決問題,請使用 [我遇到問題] 按鈕以尋求解決問題的協助。
建立您的服務
在命令提示字元中,執行下列命令以建立您的應用程式:
在終端機中,執行下列命令以建立您的應用程式:
dotnet new webapi -o MyMicroservice --no-https
然後,瀏覽至上一個命令所建立的新目錄:
cd MyMicroservice
這些命令代表什麼?
dotnet
命令會建立類型 webapi
(即 REST API 端點) 的新應用程式。
-o
參數會建立名為MyMicroservice
的目錄,以儲存您的應用程式。--no-https
旗標會建立可在沒有 HTTPS 憑證的情況下執行的應用程式,讓部署保持簡單。
cd MyMicroservice
命令可讓您進入新建立的應用程式目錄。
產生的程式碼
在 MyMicroservice
目錄中建立了數個檔案,為您提供一個可供執行的簡單服務,包括下列檔案:
Program.cs
是進入點檔案,並包含應用程式啟動時載入的所有設定和組態,而且具有簡單 API 的程式碼,可傳回未來五天的天氣預測。它也會啟動應用程式。MyMycroservice.http
會用於測試 ASP.NET Core 專案。MyMicroservice.csproj
定義應用程式的目標 .NET 版本、專案參考的程式庫等等。Properties
目錄內的launchSettings.json
檔案會定義本機開發環境的不同設定檔設定。專案建立時會自動指派介於 5000 至 5300 之間的連接埠編號,並儲存在此檔案。
下列程式碼顯示 Program.cs
檔案的內容:
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();
app.Run();
record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
選取下方的 [繼續] 按鈕以移至下一個步驟。
發生錯誤嗎?
如果您收到類似 無法建立範本「ASP.NET Core Web API」。無法建立範本。詳細資料: 拒絕存取路徑 'C:\Windows\System32\MyMicroservice',請將您目前的目錄變更為您有權限建立新資料夾的目錄,然後嘗試重新執行命令。
若 Windows 在您嘗試建立專案時找不到 SDK,且您確定已安裝 SDK,您的電腦可能會發生 PATH 環境變數的問題。如需如何診斷及修正此問題的說明,請參閱這篇 Stack Overflow 文章。
如果您無法解決目前發生的問題,請選取下方的 [我遇到問題] 按鈕,以取得解決問題的協助。
執行您的服務
在命令提示字元中執行下列命令:
在終端中,執行下列命令:
dotnet run
您應該會看到類似下列的輸出:
Building...
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5020
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: C:\Users\Ana\MyMicroservice
等待應用程式在 http://localhost:<port number> 上顯示正在聆聽,然後開啟瀏覽器並瀏覽至 http://localhost:<port number>/WeatherForecast。
在此範例中,它顯示正在連接埠 5020 上收聽,因此下列影像顯示了 URL localhost:5020/weatherforecast
。
恭喜,您已有簡單的服務正在執行!
在命令提示字元上按 CTRL+C 以結束在本機執行服務的 dotnet run
命令。
在您的終端上按 CTRL+C,即可結束在本機執行服務的 dotnet run
命令。
發生錯誤嗎?
如果您收到類似 [No webpage was found for the web address: http://localhost:5020] 的訊息,請確認您檢視的是應用程式的天氣預報頁面。URL 應為 http://localhost:5020/weatherforecast,而非只是 http://localhost:5020。
安裝 Docker
Docker 是一個平台,可讓您將應用程式及其設定與相依性結合到單一、可獨立部署且稱為容器的單元。
如果您已安裝 Docker,請確定其版本為 23.0.0 或更新版本。
下載並安裝
系統會要求您先註冊 Docker 存放區,然後才能下載安裝程式。
根據預設,Docker 會在 Windows 上使用 Linux 容器。在安裝程式中收到提示時,將此設定保持原樣。
安裝 Docker 之後,系統可能會要求您登出以完成安裝。
檢查 Docker 是否已就緒可供使用
安裝完成後,請開啟新命令提示字元,然後執行下列命令:
安裝完成後,請開啟 [新增] 終端,然後執行下列命令:
docker --version
若命令執行時有顯示某些版本資訊,則已成功安裝 Docker。
新增 Docker 中繼資料
若要使用 Docker 映像執行,您需要 Dockerfile
,這是文字檔,其中包含如何將您的應用程式建置為 Docker 映像的指示。Docker 映像包含以 Docker 容器形式執行應用程式所需的一切。
返回應用程式目錄
因為您在上一步中開啟了新的命令提示字元,所以需要返回您建立服務的目錄。
因為您在上一步中開啟了新的終端,所以需要回到您在其中建立服務的目錄。
cd MyMicroservice
新增 DockerFile
使用此命令建立名為 Dockerfile
的檔案:
touch Dockerfile
fsutil file createnew Dockerfile 0
然後,您可以在喜愛的文字編輯器中開啟它。
然後,您可以在喜愛的文字編輯器中手動開啟它,或使用此命令:
open Dockerfile
start Dockerfile
在文字編輯器中將 Dockerfile
的內容取代為下列內容:
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY MyMicroservice.csproj .
RUN dotnet restore
COPY . .
RUN dotnet publish -c release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyMicroservice.dll"]
注意: 請確定將檔案命名為 Dockerfile
,而不是 Dockerfile.txt
或其他名稱。
選用: 新增 dockerignore 檔案
Dockerignore 檔案會減少用來做為 ' docker build ' 部分的檔案集。較少的檔案會讓組建更快。
使用此命令建立名為 .dockerignore
的檔案 (如果您熟悉,則這類似於 .gitignore
檔案):
touch .dockerignore
fsutil file createnew .dockerignore 0
然後,您可以在喜愛的文字編輯器中開啟它。
然後,您可以在喜愛的文字編輯器中手動開啟它,或使用此命令:
open .dockerignore
start .dockerignore
在文字編輯器中將 .dockerignore
的內容取代為下列內容:
Dockerfile
[b|B]in
[O|o]bj
建立 Docker 映像
執行下列命令:
docker build -t mymicroservice .
docker build
命令使用 Dockerfile
來組建 Docker 映像。
-t mymicroservice
參數會告訴它將影像標記 (或命名) 為mymicroservice
。- 最後一個參數會告知要使用哪個目錄來尋找
Dockerfile
(.
指定目前的目錄)。 - 此命令會下載並建置所有相依性,以建立 Docker 映像,因此可能需要一些時間。
您可以執行下列命令,查看電腦上所有可用映像的清單,包括您剛建立的映像。
docker images
執行 Docker 映像
您可以使用下列命令在容器中執行您的應用程式:
docker run -it --rm -p 3000:8080 --name mymicroservicecontainer mymicroservice
您可以瀏覽至下列 URL 以存取在容器中執行的應用程式: http://localhost:3000/weatherforecast
您可以選擇使用下列命令,檢視在不同命令提示字元中執行的容器:
您可以選擇使用下列命令,檢視在不同終端機視窗中執行的容器:
docker ps
在命令提示字元上按 [CTRL+C] 來結束在容器中執行服務的 docker run
命令。
在終端機上按 CTRL+C 來結束在容器中執行服務的 docker run
命令。
恭喜! 您已成功建立可用 Docker 容器進行部署和調整的小型獨立服務。
這些是微服務的基礎組建區塊。
發生錯誤嗎?
如果您收到類似 [ERROR: error during connect: this error may indicate that the docker daemon is not running] 的訊息,,表示您需要啟動 Docker 應用程式。請執行 docker run hello-world
,以確認 Docker 用戶端正在執行。這樣做應該會提取並執行映像。如需更多協助,請參閱 Docker 文件,以取得如何診斷及修正此問題的指示。
後續步驟
恭喜! 您已建立簡易的服務,接著可在 Docker 容器中執行它。
現在,您可以透過我們的下一個教學課程,了解如何將您的微服務部署到雲端。
您可能也會想了解...