Skip to content

Latest commit

 

History

History
202 lines (125 loc) · 7.86 KB

build-aspire-apps-with-python.md

File metadata and controls

202 lines (125 loc) · 7.86 KB
titledescriptionms.date
Orchestrate Python apps in .NET Aspire
Learn how to integrate Python apps into a .NET Aspire app host project.
04/15/2025

Orchestrate Python apps in .NET Aspire

In this article, you learn how to use Python apps in a .NET Aspire app host. The sample app in this article demonstrates launching a Python application. The Python extension for .NET Aspire requires the use of virtual environments.

[!INCLUDE aspire-prereqs]

Additionally, you need to install Python on your machine. The sample app in this article was built with Python version 3.12.4 and pip version 24.1.2. To verify your Python and pip versions, run the following commands:

python --version
pip --version

To download Python (including pip), see the Python download page.

Create a .NET Aspire project using the template

To get started launching a Python project in .NET Aspire, use the starter template to first create a .NET Aspire application host:

dotnet new aspire -o PythonSample

In the same terminal session, change directories into the newly created project:

cd PythonSample

After the template is created, launch the app host with the following command to ensure that the app host and the .NET Aspire dashboard run successfully:

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

If the .NET Aspire Dashboard doesn't open, open it with the link in the console output. At this point the dashboard won't show any resources. Stop the app host by pressing Ctrl + C in the terminal.

Prepare a Python app

From your previous terminal session where you created the .NET Aspire solution, create a new directory to contain the Python source code.

mkdir hello-python

Change directories into the newly created hello-python directory:

cd hello-python

Initialize the Python virtual environment

To work with Python apps, they need to be within a virtual environment. To create a virtual environment, run the following command:

python -m venv .venv

For more information on virtual environments, see the Python: Install packages in a virtual environment using pip and venv.

To activate the virtual environment, enabling installation and usage of packages, run the following command:

Unix/macOS

source .venv/bin/activate

Windows

.venv\Scripts\Activate.ps1

Ensure that pip within the virtual environment is up-to-date by running the following command:

python -m pip install --upgrade pip

Install Python packages

Install the Flask package by creating a requirements.txt file in the hello-python directory and adding the following line:

Flask==3.0.3

Then, install the Flask package by running the following command:

python -m pip install -r requirements.txt

After Flask is installed, create a new file named main.py in the hello-python directory and add the following code:

importosimportflaskapp=flask.Flask(__name__) @app.route('/', methods=['GET'])defhello_world(): return'Hello, World!'if__name__=='__main__': port=int(os.environ.get('PORT', 8111)) app.run(host='0.0.0.0', port=port)

The preceding code creates a simple Flask app that listens on port 8111 and returns the message "Hello, World!" when the root endpoint is accessed.

Update the app host project

Install the Python hosting package by running the following command:

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

After the package is installed, the project XML should have a new package reference similar to the following example:

:::code language="xml" source="snippets/PythonSample/PythonSample.AppHost/PythonSample.AppHost.csproj" highlight="15":::

Replace the app host Program.cs code with the following snippet. This code adds the Python project to .NET Aspire by calling the AddPythonApp API and specifying the project name, project path, and the entry point file:

:::code source="snippets/PythonSample/PythonSample.AppHost/Program.cs" highlight="6":::

Important

The preceding code suppresses the ASPIREHOSTINGPYTHON001 diagnostic error. This error is generated because the AddPythonApp API is experimental and might change in future release. For more information, see Compiler Error ASPIREHOSTINGPYTHON001.

Run the app

Now that you've added the Python hosting package, updated the app host Program.cs file, and created a Python project, you can run the app host:

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

Launch the dashboard by clicking the link in the console output. The dashboard should display the Python project as a resource.

:::image source="media/python-dashboard.png" lightbox="media/python-dashboard.png" alt-text=".NET Aspire dashboard: Python sample app.":::

Select the Endpoints link to open the hello-python endpoint in a new browser tab. The browser should display the message "Hello, World!":

:::image source="media/python-hello-world.png" lightbox="media/python-hello-world.png" alt-text=".NET Aspire dashboard: Python sample app endpoint.":::

Stop the app host by pressing Ctrl + C in the terminal.

Add telemetry support

To add a bit of observability, add telemetry to help monitor the dependant Python app. In the Python project, add the following OpenTelemetry packages as a dependency in the requirements.txt file:

:::code language="text" source="snippets/PythonSample/hello-python/requirements.txt" highlight="2-5":::

Next, reinstall the Python app requirements into the virtual environment by running the following command:

python -m pip install -r requirements.txt

The preceding command installs the OpenTelemetry package and the OTLP exporter, in the virtual environment. Update the Python app to include the OpenTelemetry code, by replacing the existing main.py code with the following:

:::code language="python" source="snippets/PythonSample/hello-python/main.py":::

Update the app host project's launchSettings.json file to include the ASPIRE_ALLOW_UNSECURED_TRANSPORT environment variable under the http profile:

:::code language="json" source="snippets/PythonSample/PythonSample.AppHost/Properties/launchSettings.json" highlight="26":::

The ASPIRE_ALLOW_UNSECURED_TRANSPORT variable is required because when running locally the OpenTelemetry client in Python rejects the local development certificate. Launch the app host again:

dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj --launch-profile http

Important

The .NET Aspire app host must be run using HTTP instead of HTTPS. The OpenTelemetry library requires HTTP when running in a local dev environment.

Once the app host is running, navigate to the dashboard and select the Structured logging tab. Notice that it now contains logging events.

:::image source="media/python-telemetry-in-dashboard.png" lightbox="media/python-telemetry-in-dashboard.png" alt-text=".NET Aspire dashboard: Structured logging from Python process.":::

Summary

While there are several considerations that are beyond the scope of this article, you learned how to build .NET Aspire solution that integrates with Python. You also learned how to use the AddPythonApp API to host Python apps.

See also

close