PythonAppResourceBuilderExtensions Methods

Docs / Reference / Search C# APIs / Aspire.Hosting.Python / PythonAppResourceBuilderExtensions / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting.Python PythonAppResourceBuilderExtensions Methods

Class Methods 11 members

Provides extension methods for adding Python applications to an Hosting.IDistributedApplicationBuilder.

AddPythonApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PythonAppResource>

Adds a Python application to the application model.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L68-L69

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the python application.

scriptPath string The path to the script relative to the app directory to run.

Returns

IResourceBuilder<PythonAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This method executes a Python script directly using python script.py. By default, the virtual environment is resolved using the following priority:

Use PythonAppResourceBuilderExtensions.WithVirtualEnvironment to specify a different virtual environment path. Use WithArgs to pass arguments to the script.

Python applications automatically have debugging support enabled.

Examples

Add a FastAPI Python application to the application model:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonApp("fastapi-app", "../api", "main.py")
       .WithArgs("arg1", "arg2");

builder.Build().Run();

Obsolete — Use AddPythonScript, AddPythonModule, or AddPythonExecutable and chain with .WithArgs(...) instead.

AddPythonApp(IDistributedApplicationBuilder, string, string, string, string[]) extension IResourceBuilder<PythonAppResource>

Adds a python application with a virtual environment to the application model.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath,
        params string[] scriptArgs)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L176-L180

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the python app files.

scriptPath string The path to the script relative to the app directory to run.

scriptArgs string[] The arguments for the script.

Returns

IResourceBuilder<PythonAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This overload is obsolete. Use one of the more specific methods instead:

• PythonAppResourceBuilderExtensions.AddPythonApp - To run a Python script file
• PythonAppResourceBuilderExtensions.AddPythonModule - To run a Python module via python -m
• PythonAppResourceBuilderExtensions.AddPythonExecutable - To run an executable from the virtual environment

Chain with WithArgs to pass arguments:

builder.AddPythonScript("name", "dir", "script.py")
       .WithArgs("arg1", "arg2");

Obsolete — Use AddPythonScript, AddPythonModule, or AddPythonExecutable and chain with .WithVirtualEnvironment(...).WithArgs(...) instead.

AddPythonApp(IDistributedApplicationBuilder, string, string, string, string, string[]) extension IResourceBuilder<PythonAppResource>

Adds a python application with a virtual environment to the application model.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string scriptPath,
        string virtualEnvironmentPath,
        params string[] scriptArgs)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L219-L223

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the python app files.

scriptPath string The path to the script to run, relative to the app directory.

virtualEnvironmentPath string Path to the virtual environment.

scriptArgs string[] The arguments for the script.

Returns

IResourceBuilder<PythonAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This overload is obsolete. Use one of the more specific methods instead:

• PythonAppResourceBuilderExtensions.AddPythonApp - To run a Python script file
• PythonAppResourceBuilderExtensions.AddPythonModule - To run a Python module via python -m
• PythonAppResourceBuilderExtensions.AddPythonExecutable - To run an executable from the virtual environment

Chain with PythonAppResourceBuilderExtensions.WithVirtualEnvironment and WithArgs:

builder.AddPythonScript("name", "dir", "script.py")
       .WithVirtualEnvironment("myenv")
       .WithArgs("arg1", "arg2");

AddPythonExecutable(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PythonAppResource>

Adds a Python executable to the application model.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonExecutable(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string executableName)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L141

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the python application.

executableName string The name of the executable in the virtual environment (e.g., "pytest", "uvicorn", "flask").

Returns

IResourceBuilder<PythonAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This method runs an executable from the virtual environment's bin directory. By default, the virtual environment folder is expected to be named .venv and located in the app directory. Use PythonAppResourceBuilderExtensions.WithVirtualEnvironment to specify a different virtual environment path. Use WithArgs to pass arguments to the executable.

Unlike scripts and modules, Python executables do not have debugging support enabled by default. Use PythonAppResourceBuilderExtensions.WithDebugging to explicitly enable debugging support if the executable is a Python-based tool that can be debugged.

Examples

Add a pytest executable to the application model:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonExecutable("pytest", "../api", "pytest")
       .WithArgs("-q")
       .WithDebugging();

builder.Build().Run();

AddPythonModule(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PythonAppResource>

Adds a Python module to the application model.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<PythonAppResource> AddPythonModule(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string moduleName)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L103-L104

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to.

name string The name of the resource.

appDirectory string The path to the directory containing the python application.

moduleName string The name of the Python module to run (e.g., "flask", "uvicorn").

Returns

IResourceBuilder<PythonAppResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This method runs a Python module using python -m <module>. By default, the virtual environment folder is expected to be named .venv and located in the app directory. Use PythonAppResourceBuilderExtensions.WithVirtualEnvironment to specify a different virtual environment path. Use WithArgs to pass arguments to the module.

Python modules automatically have debugging support enabled.

Examples

Add a Flask module to the application model:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddPythonModule("flask-dev", "../flaskapp", "flask")
       .WithArgs("run", "--debug", "--host=0.0.0.0");

builder.Build().Run();

AddUvicornApp(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<UvicornAppResource>

Adds a Uvicorn-based Python application to the distributed application builder with HTTP endpoint configuration.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<UvicornAppResource> AddUvicornApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string app)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L264-L347

Parameters

builder IDistributedApplicationBuilder The distributed application builder to which the Uvicorn application resource will be added.

name string The unique name of the Uvicorn application resource.

appDirectory string The directory containing the Python application files.

app string The ASGI app import path which informs Uvicorn which module and variable to load as your web application. For example, "main:app" means "main.py" file and variable named "app".

Returns

IResourceBuilder<UvicornAppResource> A resource builder for further configuration of the Uvicorn Python application resource.

Remarks

This method configures the application to use Uvicorn as the ASGI server and exposes an HTTP endpoint. When publishing, it sets the entry point to use the Uvicorn executable with appropriate arguments for host and port.

By default, the virtual environment folder is expected to be named .venv and located in the app directory. Use PythonAppResourceBuilderExtensions.WithVirtualEnvironment to specify a different virtual environment path.

In non-publish mode, the --reload flag is automatically added to enable hot reload during development.

Examples

Add a FastAPI application using Uvicorn:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddUvicornApp("api", "../fastapi-app", "main:app")
    .WithUv()
    .WithExternalHttpEndpoints();

builder.Build().Run();

WithDebugging(IResourceBuilder<T>) extension IResourceBuilder<T>

Enables debugging support for the Python application.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDebugging<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L939-L1031

Parameters

builder IResourceBuilder<T> The resource builder.

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for method chaining.

Remarks

This method adds the Python.PythonExecutableDebuggableAnnotation to the resource, which enables debugging support. The debugging configuration is automatically set up based on the entrypoint type (Script, Module, or Executable).

The debug configuration includes the Python interpreter path from the virtual environment, the program or module to debug, and appropriate launch settings.

WithEntrypoint(IResourceBuilder<T>, EntrypointType, string) extension IResourceBuilder<T>

Configures the entrypoint for the Python application.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEntrypoint<T>(
        this IResourceBuilder<T> builder,
        EntrypointType entrypointType,
        string entrypoint)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L1067-L1125

Parameters

builder IResourceBuilder<T> The resource builder.

entrypointType EntrypointType The type of entrypoint (Script, Module, or Executable).

entrypoint string The entrypoint value (script path, module name, or executable name).

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for method chaining.

Remarks

This method allows you to change the entrypoint configuration of a Python application after it has been created. The command and arguments will be updated based on the specified entrypoint type:

• Script: Runs as python <scriptPath>
• Module: Runs as python -m <moduleName>
• Executable: Runs the executable directly from the virtual environment

Important: This method resets all command-line arguments. If you need to add arguments after changing the entrypoint, call WithArgs after this method.

Examples

Change a Python app from running a script to running a module:

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithEntrypoint(EntrypointType.Module, "uvicorn")
    .WithArgs("main:app", "--reload");

WithPip(IResourceBuilder<T>, bool, string[]?) extension IResourceBuilder<T>

Configures the Python resource to use pip as the package manager and optionally installs packages before the application starts.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithPip<T>(
        this IResourceBuilder<T> builder,
        bool install = true,
        string[]? installArgs = null)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L1163-L1206

Parameters

builder IResourceBuilder<T> The resource builder.

install bool optional When true (default), automatically installs packages before the application starts. When false, only sets the package manager annotation without creating an installer resource.

installArgs string[]? optional The command-line arguments passed to pip install command.

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for method chaining.

Exceptions

ArgumentNullException Thrown when builder is null.

Remarks

This method creates a child resource that runs pip install in the working directory of the Python application. The Python application will wait for this resource to complete successfully before starting.

Pip will automatically detect and use either pyproject.toml or requirements.txt based on which file exists in the application directory. If pyproject.toml exists, pip will use it. Otherwise, if requirements.txt exists, pip will use that. Calling this method will replace any previously configured package manager (such as uv).

Examples

Add a Python app with automatic pip package installation:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithPip()  // Automatically installs from pyproject.toml or requirements.txt
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();

WithUv(IResourceBuilder<T>, bool, string[]?) extension IResourceBuilder<T>

Adds a UV environment setup task to ensure the virtual environment exists before running the Python application.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUv<T>(
        this IResourceBuilder<T> builder,
        bool install = true,
        string[]? args = null)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L1259-L1276

Parameters

builder IResourceBuilder<T> The resource builder.

install bool optional When true (default), automatically runs uv sync before the application starts. When false, only sets the package manager annotation without creating an installer resource.

args string[]? optional Optional custom arguments to pass to the uv command. If not provided, defaults to ["sync"].

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for method chaining.

Exceptions

ArgumentNullException Thrown when builder is null.

Remarks

This method creates a child resource that runs uv sync in the working directory of the Python application. The Python application will wait for this resource to complete successfully before starting.

UV (https://github.com/astral-sh/uv) is a modern Python package manager written in Rust that can manage virtual environments and dependencies with significantly faster performance than traditional tools. The uv sync command ensures that the virtual environment exists, Python is installed if needed, and all dependencies specified in pyproject.toml are installed and synchronized.

Calling this method will replace any previously configured package manager (such as pip).

Examples

Add a Python app with automatic UV environment setup:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithUv()  // Automatically runs 'uv sync' before starting the app
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();

Add a Python app with custom UV arguments:

var builder = DistributedApplication.CreateBuilder(args);

var python = builder.AddPythonScript("api", "../python-api", "main.py")
    .WithUv(args: ["sync", "--python", "3.12", "--no-dev"])  // Custom uv sync args
    .WithHttpEndpoint(port: 5000);

builder.Build().Run();

WithVirtualEnvironment(IResourceBuilder<T>, string, bool) extension IResourceBuilder<T>

Configures a custom virtual environment path for the Python application.

public static class PythonAppResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithVirtualEnvironment<T>(
        this IResourceBuilder<T> builder,
        string virtualEnvironmentPath,
        bool createIfNotExists = true)
    {
        // ...
    }
}

PythonAppResourceBuilderExtensions.cs#L880-L917

Parameters

builder IResourceBuilder<T> The resource builder.

virtualEnvironmentPath string The path to the virtual environment. Can be absolute or relative to the app directory. When relative, it is resolved from the working directory of the Python application. Common values include ".venv", "venv", or "myenv".

createIfNotExists bool optional Whether to automatically create the virtual environment if it doesn't exist. Defaults to true. Set to false to disable automatic venv creation (the venv must already exist).

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for method chaining.

Remarks

This method updates the Python executable path to use the specified virtual environment.

By default ( createIfNotExists = true), if the virtual environment doesn't exist, it will be automatically created before running the application (when using pip package manager, not uv). Set createIfNotExists to false to disable this behavior and require the venv to already exist.

Virtual environments allow Python applications to have isolated dependencies separate from the system Python installation. This is the recommended approach for Python applications.

When you explicitly specify a virtual environment path using this method, the path is used verbatim. The automatic multi-location lookup (checking both app and AppHost directories) only applies when using the default ".venv" path during initial app creation via AddPythonScript, AddPythonModule, or AddPythonExecutable.

Examples

Configure a Python app to use a custom virtual environment:

var python = builder.AddPythonApp("api", "../python-api", "main.py")
    .WithVirtualEnvironment("myenv");

// Disable automatic venv creation (require venv to exist)
var python2 = builder.AddPythonApp("api2", "../python-api2", "main.py")
    .WithVirtualEnvironment("myenv", createIfNotExists: false);