PerlAppResourceBuilderExtensions Methods
Class Methods 12 members
Extension methods for adding Perl application resources to the application model.
AddPerlApi(IDistributedApplicationBuilder, string, string, string) Section titled AddPerlApi(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PerlAppResource> Adds a Perl API server resource (e.g., Mojolicious, Dancer2) to the application model. Passes the
daemon subcommand so HTTP frameworks start a listener. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<PerlAppResource> AddPerlApi( this IDistributedApplicationBuilder builder, string resourceName, string appDirectory, string scriptName) { // ... }}Parameters
builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to. resourceName string The name of the resource. appDirectory string The path to the directory containing the Perl script. Resolved relative to the AppHost project directory; becomes the resource's working directory and the anchor for all relative path resolution (script path, WithLocalLib, cpanfile discovery). scriptName string The API script path, relative to appDirectory. Do not include the appDirectory prefix — the script is resolved relative to appDirectory automatically. Returns
IResourceBuilder<PerlAppResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
This method configures a Perl API script and passes the default API subcommand ( daemon) so frameworks such as Mojolicious start an HTTP server. The working directory is set to appDirectory and all relative paths (including WithLocalLib and cpanfile discovery) resolve against it.
Examples
For your AppHost / Application Model, you'd add a Perl API like this:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddPerlApi("perl-api", "../api", "API.pl");
builder.Build().Run();AddPerlExecutable(IDistributedApplicationBuilder, string, string, string) Section titled AddPerlExecutable(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PerlAppResource> Adds a Perl executable (compiled binary or PAR-packed application) to the application model. The executable is run directly rather than through the
perl interpreter. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<PerlAppResource> AddPerlExecutable( this IDistributedApplicationBuilder builder, string resourceName, string appDirectory, string executablePath) { // ... }}Parameters
builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to. resourceName string The name of the resource. appDirectory string The path to the working directory for the application. executablePath string The path to the executable, relative to appDirectory. Returns
IResourceBuilder<PerlAppResource> A reference to the ApplicationModel.IResourceBuilder`1. Examples
var builder = DistributedApplication.CreateBuilder(args);builder.AddPerlExecutable("myapp", "../perl-app", "my-compiled-perl");builder.Build().Run();AddPerlModule(IDistributedApplicationBuilder, string, string, string) Section titled AddPerlModule(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PerlAppResource> Adds a Perl module to the application model. The module is executed using
perl -MModule::Name -e "Module::Name->run()". public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<PerlAppResource> AddPerlModule( this IDistributedApplicationBuilder builder, string resourceName, string appDirectory, string moduleName) { // ... }}Parameters
builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to. resourceName string The name of the resource. appDirectory string The path to the working directory for the application. moduleName string The fully qualified Perl module name (e.g., "MyApp::Main"). Returns
IResourceBuilder<PerlAppResource> A reference to the ApplicationModel.IResourceBuilder`1. Examples
var builder = DistributedApplication.CreateBuilder(args);builder.AddPerlModule("worker", "../perl-worker", "MyApp::Worker");builder.Build().Run();AddPerlScript(IDistributedApplicationBuilder, string, string, string) Section titled AddPerlScript(IDistributedApplicationBuilder, string, string, string) extension IResourceBuilder<PerlAppResource> Adds a Perl script resource (worker, CLI tool, background service) to the application model.
public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<PerlAppResource> AddPerlScript( this IDistributedApplicationBuilder builder, string resourceName, string appDirectory, string scriptName) { // ... }}Parameters
builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to. resourceName string The name of the resource. appDirectory string The path to the directory containing the Perl script. Resolved relative to the AppHost project directory; becomes the resource's working directory and the anchor for all relative path resolution (script path, WithLocalLib, cpanfile discovery). scriptName string The path to the script relative to appDirectory. Do not include the appDirectory prefix — the script is resolved relative to appDirectory automatically. Returns
IResourceBuilder<PerlAppResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
This method executes a Perl script directly using perl -s scriptName. The working directory is set to appDirectory and all relative paths (including WithLocalLib and cpanfile discovery) resolve against it.
Examples
For your AppHost / Application Model, you'd add a Perl script like this:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddPerlScript("my-worker", "../scripts", "Worker.pl");
builder.Build().Run();WithCarton(IResourceBuilder<TResource>) Section titled WithCarton(IResourceBuilder<TResource>) extension IResourceBuilder<TResource> Configures the Perl application to use Carton as its package manager. Carton manages dependencies via
cpanfile and a lock file ( cpanfile.snapshot), enabling reproducible builds. Use PerlAppResourceBuilderExtensions.WithProjectDependencies to run carton install at startup. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithCarton<TResource>( this IResourceBuilder<TResource> builder) { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
Carton only supports project-level dependency installation via
cpanfile. Calling PerlAppResourceBuilderExtensions.WithPackage after WithCarton() will throw because Carton does not support installing individual modules. To install Carton, you may use "cpanm Carton". WithCpanMinus(IResourceBuilder<TResource>) Section titled WithCpanMinus(IResourceBuilder<TResource>) extension IResourceBuilder<TResource> Configures the Perl application to use cpanm (App::cpanminus) as its package manager instead of the default cpan. Call this before
PerlAppResourceBuilderExtensions.WithPackage to change how packages are installed. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithCpanMinus<TResource>( this IResourceBuilder<TResource> builder) { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. WithLocalLib(IResourceBuilder<TResource>, string) Section titled WithLocalLib(IResourceBuilder<TResource>, string) extension IResourceBuilder<TResource> Configures the Perl application to use a local::lib directory for module isolation. Sets
PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MM_OPT, and PERL_MB_OPT environment variables so that modules are resolved from and installed into the local directory. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithLocalLib<TResource>( this IResourceBuilder<TResource> builder, string path = "local") { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. path string optional The path to the local::lib directory. Relative paths are resolved against the resource's working directory ( appDirectory), not the AppHost project. Rooted paths (e.g., /opt/perl-libs or C:\perl-libs) are used as-is. Defaults to "local" (the Carton convention). Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
Sets the following environment variables:
PERL5LIB—<resolved>/lib/perl5(module search path)PERL_LOCAL_LIB_ROOT—<resolved>PERL_MM_OPT—INSTALL_BASE=<resolved>PERL_MB_OPT—--install_base <resolved>
If the active package manager is cpan (the default), it is automatically switched to cpanm since cpan does not support the --local-lib flag. While it is possible to use cpan with Local::Lib it is complicated to model in Aspire.
WithPackage(IResourceBuilder<TResource>, string, bool, bool) Section titled WithPackage(IResourceBuilder<TResource>, string, bool, bool) extension IResourceBuilder<TResource> Adds a Perl package (module) to be installed before the application starts. Uses the configured package manager: cpan by default, or cpanm if
PerlAppResourceBuilderExtensions.WithCpanMinus was called. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithPackage<TResource>( this IResourceBuilder<TResource> builder, string packageName, bool force = false, bool skipTest = false) { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. packageName string The name of the Perl module to install (e.g., "Mojolicious", "DBI"). force bool optional If true, force installation even if the module is already installed or tests fail. skipTest bool optional If true, skip running tests during installation. Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
A child installer resource is created that runs before the main application starts. If the module is already installed (verified via
perl -MModuleName -e 1), installation is skipped. The installer uses the active package manager — cpan by default, or cpanm if PerlAppResourceBuilderExtensions.WithCpanMinus was called. WithPerlbrew(IResourceBuilder<T>, string, string?) Section titled WithPerlbrew(IResourceBuilder<T>, string, string?) extension IResourceBuilder<T> Configures the Perl application to use a specific perlbrew-managed Perl version.
public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<T> WithPerlbrew<T>( this IResourceBuilder<T> builder, string version, string? perlbrewRoot = null) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder. version string The perlbrew version name. Accepts both "5.38.0" and "perl-5.38.0". perlbrewRoot string? optional Optional explicit path to the perlbrew root directory. If null, resolves from the PERLBREW_ROOT environment variable, or defaults to ~/perl5/perlbrew. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1. WithPerlbrewEnvironment(IResourceBuilder<T>, string, string?) Section titled WithPerlbrewEnvironment(IResourceBuilder<T>, string, string?) extension IResourceBuilder<T> Configures the Perl application to use a specific perlbrew-managed Perl version. This resolves the Perl executable from the perlbrew installation and updates the resource's command and environment variables so that all subsequent operations use the specified Perl version.
public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<T> WithPerlbrewEnvironment<T>( this IResourceBuilder<T> builder, string version, string? perlbrewRoot = null) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder. version string The perlbrew version name. Accepts both "5.38.0" and "perl-5.38.0". perlbrewRoot string? optional Optional explicit path to the perlbrew root directory. If null, resolves from the PERLBREW_ROOT environment variable, or defaults to ~/perl5/perlbrew. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
Perlbrew is Linux-only. On Windows, an InvalidOperationException is thrown with a recommendation to use Berrybrew.
When combined with PerlAppResourceBuilderExtensions.WithLocalLib, modules are installed into the local directory rather than the perlbrew tree, keeping the perlbrew installation clean and enabling per-project module isolation.
WithPerlCertificateTrust(IResourceBuilder<TResource>) Section titled WithPerlCertificateTrust(IResourceBuilder<TResource>) extension IResourceBuilder<TResource> Configures certificate trust for the Perl application by setting SSL/TLS environment variables that common Perl HTTP libraries respect. Sets
SSL_CERT_FILE (IO::Socket::SSL / LWP), PERL_LWP_SSL_CA_FILE (LWP::UserAgent), and MOJO_CA_FILE (Mojolicious) to the certificate bundle path provided by Aspire. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithPerlCertificateTrust<TResource>( this IResourceBuilder<TResource> builder) { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. WithProjectDependencies(IResourceBuilder<TResource>, bool) Section titled WithProjectDependencies(IResourceBuilder<TResource>, bool) extension IResourceBuilder<TResource> Configures project-level dependency installation for the Perl application. Runs the appropriate install command based on the active package manager:
- cpanm:
cpanm --installdeps --notest . - carton:
carton install [--deployment]
cpan (the default), it is automatically switched to cpanm since cpan does not support --installdeps. public static class PerlAppResourceBuilderExtensions{ public static IResourceBuilder<TResource> WithProjectDependencies<TResource>( this IResourceBuilder<TResource> builder, bool cartonDeployment = false) { // ... }}Parameters
builder IResourceBuilder<TResource> The resource builder. cartonDeployment bool optional If true and using Carton, adds --deployment for reproducible installs from cpanfile.snapshot. Ignored for other package managers. Returns
IResourceBuilder<TResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
Expects a
cpanfile in the resource's working directory ( appDirectory). If the cpanfile is in a different location, adjust appDirectory accordingly. When using Carton with cartonDeployment set to true, a cpanfile.snapshot must also be present.