Orquestre aplicativos de Python no .NET Aspire

Artigo
12/13/2024

Neste artigo, você aprenderá a usar aplicativos Python em um host de aplicativo .NET Aspire. O aplicativo de exemplo neste artigo demonstra a inicialização de um aplicativo Python. A extensão Python para .NET Aspire requer o uso de ambientes virtuais.

Pré-requisitos

Para trabalhar com .NET.NET Aspire, você precisa do seguinte instalado localmente:

.NET 8,0 ou .NET 9,0
Um tempo de execução de contêiner compatível com OCI, como:
- Docker ambiente de trabalho ou Podman. Para obter mais informações, consulte Container runtime.
Um ambiente de desenvolvedor integrado (IDE) ou editor de código, como:
- Visual Studio 2022 versão 17.9 ou superior (opcional)
- Visual Studio Code (Opcional)
  - C# Dev Kit: Extensão (Opcional)
- JetBrains Rider com o plugin .NET.NET Aspire (Opcional)

Para obter mais informações, consulte .NET.NET Aspirede configuração e ferramentas e .NET.NET Aspire SDK.

Além disso, você precisa instalar Python em sua máquina. O aplicativo de exemplo neste artigo foi criado com Python versão 3.12.4 e pip versão 24.1.2. Para verificar as versões Python e pip, execute os seguintes comandos:

python --version

pip --version

Para transferir Python (incluindo pip), consulte a página de transferência de Python.

Criar um projeto .NET.NET Aspire usando o modelo

Para começar a iniciar um projeto de Python em .NET Aspire primeiro use o modelo inicial para criar um host de aplicativo .NET Aspire:

dotnet new aspire -o PythonSample

Na mesma sessão de terminal, altere os diretórios para o projeto recém-criado:

cd PythonSample

Depois de criar o modelo, inicie o aplicativo host com o seguinte comando para garantir que o aplicativo host e o painel de controlo .NET.NET Aspire sejam iniciados com êxito:

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

Assim que o host do aplicativo estiver iniciado, deve ser possível clicar no link do painel na saída do console. Neste ponto, o painel não mostrará nenhum recurso. Pare o host do aplicativo pressionando Ctrl + C no terminal.

Preparar um aplicativo Python

A partir da sessão de terminal anterior em que você criou a solução .NET Aspire, crie um novo diretório para conter o código-fonte Python.

mkdir hello-python

Altere os diretórios para o diretório hello-python recém-criado :

cd hello-python

Inicializar o ambiente virtual Python

Para trabalhar com aplicativos Python, eles precisam estar em um ambiente virtual. Para criar um ambiente virtual, execute o seguinte comando:

python -m venv .venv

Para obter mais informações sobre ambientes virtuais, consulte o Python: Instalar pacotes em um ambiente virtual usando pip e venv.

Para ativar o ambiente virtual, permitindo a instalação e o uso de pacotes, execute o seguinte comando:

Unix/macOS
Windows

source .venv/bin/activate

.venv\Scripts\Activate.ps1

Certifique-se de que pip dentro do ambiente virtual está up-to-date executando o seguinte comando:

python -m pip install --upgrade pip

Instalar pacotes Python

Instale o pacote Flask criando um arquivo requirements.txt no diretório hello-python e adicionando a seguinte linha:

Flask==3.0.3

Em seguida, instale o pacote Flask executando o seguinte comando:

python -m pip install -r requirements.txt

Depois que o Flask estiver instalado, crie um novo arquivo chamado main.py no diretório hello-python e adicione o seguinte código:

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)

O código anterior cria uma aplicação Flask simples que escuta na porta 8111 e retorna a mensagem "Hello, World!" quando o endpoint raiz é acessado.

Atualizar o projeto de host do aplicativo

Instale o pacote de hospedagem Python executando o seguinte comando:

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

Depois que o pacote for instalado, o XML do projeto deve ter uma nova referência de pacote semelhante à seguinte:

<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>

Atualize o arquivo Program.cs host do aplicativo para incluir o projeto Python, chamando a API AddPythonApp e especificando o nome do projeto, o caminho do projeto e o arquivo de ponto de entrada:

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();

Importante

A API AddPythonApp é experimental e pode mudar em versões futuras. Para obter mais informações, consulte ASPIREHOSTINGPYTHON001.

Executar o aplicativo

Agora que você adicionou o pacote de hospedagem Python, atualizou o arquivo Program.cs host do aplicativo e criou um projeto Python, você pode executar o host do aplicativo:

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

Inicie o painel clicando no link na saída do console. O painel deve exibir o projeto Python como um recurso.

Selecione o link Endpoints para abrir o endpoint hello-python num novo separador do navegador. O navegador deve exibir a mensagem "Olá, Mundo!".

Painel de controlo

Pare o host do aplicativo pressionando Ctrl + C no terminal.

Adicione suporte de telemetria.

Para adicionar um pouco de observabilidade, adicione telemetria para ajudar a monitorizar a aplicação dependente de Python. No projeto Python, adicione o seguinte pacote de OpenTelemetry como uma dependência no arquivo requirements.txt:

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

A atualização de requisito anterior adiciona o pacote OpenTelemetry e o exportador OTLP. Em seguida, reinstale os requisitos do aplicativo Python no ambiente virtual executando o seguinte comando:

python -m pip install -r requirements.txt

O comando anterior instala o pacote OpenTelemetry e o exportador OTLP, no ambiente virtual. Atualize o aplicativo Python para incluir o código OpenTelemetry, substituindo o código main.py existente pelo seguinte:

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)

Atualize o arquivo de launchSettings.json do projeto host do aplicativo para incluir a variável de ambiente 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"
      }
    }
  }
}

A variável ASPIRE_ALLOW_UNSECURED_TRANSPORT é necessária porque, ao executar localmente, o cliente OpenTelemetry em Python rejeita o certificado de desenvolvimento local. Inicie o host do aplicativo novamente:

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

Depois de iniciar o host da aplicação, navegue até o painel e repare que, além da saída do log do console, o log estruturado também está a ser encaminhado para o painel.

Resumo

Embora haja várias considerações que estão além do escopo deste artigo, aprendeu-se como criar a solução .NET Aspire que se integra ao Python. Você também aprendeu como usar a API AddPythonApp para hospedar aplicativos Python.

Ver também

GitHub: .NET Aspire Samples— Integração de hospedagemPython

Partilhar via