在 Python 中協調 .NET Aspire 應用程式

發行項
12/19/2024

在本文中，您將瞭解如何在 Python 應用程式主機上使用 .NET Aspire 應用程式。本文中的範例應用程式示範如何啟動 Python 應用程式。 Python 的 .NET Aspire 延伸模組需要使用虛擬環境。

先決條件

若要使用 .NET.NET Aspire，您需要在本機安裝下列專案：

.NET 8.0 或 .NET 9.0
符合 OCI 規範的容器運行時間，例如：
- Docker 桌面或 Podman。如需詳細資訊，請參閱容器運行時間。
整合式開發人員環境（IDE）或程式碼編輯器，例如：
- Visual Studio 2022 17.9 版或更高版本（選用）
- Visual Studio Code （選擇性）
  - C# Dev Kit：擴充功能（選擇性）
- JetBrains Rider 搭配 .NET.NET Aspire 外掛程式（選用）

如需詳細資訊，請參閱 .NET.NET Aspire 設定和工具和 .NET.NET Aspire SDK。

此外，您必須在計算機上安裝 Python。本文中的範例應用程式是使用 Python 3.12.4 版和 pip 24.1.2 版所建置。若要確認您的 Python 和 pip 版本，請執行下列命令：

python --version

pip --version

若要下載（包括），請參閱下載頁面。

使用範本建立 .NET.NET Aspire 專案

若要開始在 Python 中啟動 .NET Aspire 專案，請先使用入門範本來建立 .NET Aspire 應用程式主機：

dotnet new aspire -o PythonSample

在相同的終端機會話中，將目錄變更為新建立的專案：

cd PythonSample

建立範本之後，請使用下列命令啟動應用程式主機，以確保應用程式主機和 .NET.NET Aspire 儀錶板成功啟動：

dotnet run --project PythonSample.AppHost/PythonSample.AppHost.csproj

應用程式主機啟動時，應該可以按下主台輸出中的儀錶板連結。此時，儀錶板不會顯示任何資源。在終端機中按 Ctrl + C，以停止應用程式主機。

準備 Python 應用程式

在您創建 .NET Aspire 解決方案的先前終端機會話中，請建立一個新目錄以包含 Python 原始程式碼。

mkdir hello-python

將目錄變更為新建立的 hello-python 目錄：

cd hello-python

初始化 Python 虛擬環境

若要使用 Python 應用程式，它們必須位於虛擬環境中。若要建立虛擬環境，請執行下列命令：

python -m venv .venv

如需虛擬環境的詳細資訊，請參閱 Python：使用 pip 和 venv在虛擬環境中安裝套件。

若要啟用虛擬環境，啟用套件的安裝和使用方式，請執行下列命令：

Unix/macOS
Windows

source .venv/bin/activate

.venv\Scripts\Activate.ps1

執行下列命令，確保在虛擬環境中，pip 已是 up-to-date：

python -m pip install --upgrade pip

安裝 Python 套件

在 python 目錄中建立 requirements.txt 檔案並新增下列這一行，以安裝 Flask 套件：

Flask==3.0.3

然後，執行下列命令來安裝 Flask 套件：

python -m pip install -r requirements.txt

安裝 Flask 之後，請在 python 目錄中建立名為 main.py 的新檔案，並新增下列程式代碼：

import os
import flask

app = flask.Flask(__name__)

@app.route('/', methods=['GET'])
def hello_world():
    return 'Hello, World!'

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8111))
    app.run(host='0.0.0.0', port=port)

上述程式代碼會建立簡單的 Flask 應用程式，以接聽埠 8111，並在存取根端點時傳回訊息 "Hello, World!"。

更新應用程式主機專案

執行下列命令以安裝 Python 裝載套件：

dotnet add ../PythonSample.AppHost/PythonSample.AppHost.csproj package Aspire.Hosting.Python --version 9.0.0

安裝套件之後，專案 XML 應該會有類似下列的新套件參考：

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>5fd92a87-fff8-4a09-9f6e-2c0d656e25ba</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
    <PackageReference Include="Aspire.Hosting.Python" Version="9.0.0" />
  </ItemGroup>

</Project>

藉由呼叫 API 並指定專案名稱、專案路徑和進入點檔案，更新應用程式主機 Python 檔案以包含 AddPythonApp 專案：

using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREHOSTINGPYTHON001
var pythonapp = builder.AddPythonApp("hello-python", "../hello-python", "main.py")
       .WithHttpEndpoint(env: "PORT")
       .WithExternalHttpEndpoints()
       .WithOtlpExporter();
#pragma warning restore ASPIREHOSTINGPYTHON001

if (builder.ExecutionContext.IsRunMode && builder.Environment.IsDevelopment())
{
    pythonapp.WithEnvironment("DEBUG", "True");
}

builder.Build().Run();

重要

AddPythonApp API 是實驗性的，未來版本可能會變更。如需詳細資訊，請參閱 ASPIREHOSTINGPYTHON001。

執行應用程式

既然您已新增 Python 裝載套件、更新應用程式主機 Program.cs 檔案，並建立 Python 專案，您可以執行應用程式主機：

dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj

按兩下主控台輸出中的連結，以啟動儀錶板。儀錶板應該將 Python 項目顯示為一項資源。

選取 [端點] 連結，以在新瀏覽器索引標籤中開啟 hello-python 端點。瀏覽器應該會顯示訊息「Hello， World！“：

在終端機中按 Ctrl + C，以停止應用程式主機。

新增遙測支援。

為了增加一些可觀察性，請加入遙測來協助監視依賴的 Python 應用程式。在 Python 專案中，將下列 OpenTelemetry 套件新增為 requirements.txt 檔案中的相依性：

Flask==3.0.3
opentelemetry-distro
opentelemetry-exporter-otlp-proto-grpc
opentelemetry-instrumentation-flask
gunicorn

上述需求更新會新增 OpenTelemetry 套件和 OTLP 匯出工具。接下來，執行下列命令，將 Python 應用程式需求重新安裝至虛擬環境：

python -m pip install -r requirements.txt

上述命令會在虛擬環境中安裝 OpenTelemetry 套件和 OTLP 匯出工具。將現有的 Python 程式代碼取代為下列程式代碼，以更新 OpenTelemetry 應用程式以包含程式代碼：

import os
import logging
import flask
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.instrumentation.flask import FlaskInstrumentor

app = flask.Flask(__name__)

trace.set_tracer_provider(TracerProvider())
otlpExporter = OTLPSpanExporter()
processor = BatchSpanProcessor(otlpExporter)
trace.get_tracer_provider().add_span_processor(processor)

FlaskInstrumentor().instrument_app(app)

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.route('/', methods=['GET'])
def hello_world():
    logger.info("request received!")
    return 'Hello, World!'

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8111))
    debug = bool(os.environ.get('DEBUG', False))
    host = os.environ.get('HOST', '127.0.0.1')
    app.run(port=port, debug=debug, host=host)

更新應用程式主機專案的 launchSettings。json 檔案，以包含 ASPIRE_ALLOW_UNSECURED_TRANSPORT 環境變數：

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:17171;http://localhost:15209",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21171",
        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22122"
      }
    },
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:15209",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19171",
        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20208",
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    }
  }
}

ASPIRE_ALLOW_UNSECURED_TRANSPORT 變數是必要的，因為在本機執行時，OpenTelemetry 中的 clientPython 會拒絕本機開發憑證。再次啟動 應用程式主機：

dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj

一旦應用程式主機啟動，請前往儀錶板。請注意，除了控制台紀錄輸出之外，結構化紀錄也會同時傳送至儀錶板。

總結

雖然有數個超出本文範圍的考慮，但您已瞭解如何建置與 .NET Aspire整合的 Python 解決方案。您也已瞭解如何使用 AddPythonApp API 來裝載 Python 應用程式。

另請參閱

GitHub：.NET Aspire 範例—Python 主機整合

共用方式為