PerlAppResourceBuilderExtensions Methods
ClassMethods12 members
Extension methods for adding Perl application resources to the application model.
AddPerlApi(IDistributedApplicationBuilder, string, string, string)Section titled AddPerlApi(IDistributedApplicationBuilder, string, string, string)extensionIResourceBuilder<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
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder to add the resource to.resourceNamestringThe name of the resource.appDirectorystring 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). scriptNamestring 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)extensionIResourceBuilder<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
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder to add the resource to.resourceNamestringThe name of the resource.appDirectorystringThe path to the working directory for the application.executablePathstringThe 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)extensionIResourceBuilder<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
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder to add the resource to.resourceNamestringThe name of the resource.appDirectorystringThe path to the working directory for the application.moduleNamestringThe 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)extensionIResourceBuilder<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
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder to add the resource to.resourceNamestringThe name of the resource.appDirectorystring 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). scriptNamestring 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>)extensionIResourceBuilder<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
builderIResourceBuilder<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>)extensionIResourceBuilder<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
builderIResourceBuilder<TResource>The resource builder.Returns
IResourceBuilder<TResource>A reference to the ApplicationModel.IResourceBuilder`1.WithLocalLib(IResourceBuilder<TResource>, string)Section titled WithLocalLib(IResourceBuilder<TResource>, string)extensionIResourceBuilder<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
builderIResourceBuilder<TResource>The resource builder.pathstringoptional 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)extensionIResourceBuilder<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
builderIResourceBuilder<TResource>The resource builder.packageNamestringThe name of the Perl module to install (e.g., "Mojolicious", "DBI").forcebooloptionalIf true, force installation even if the module is already installed or tests fail.skipTestbooloptionalIf 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?)extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder.versionstring The perlbrew version name. Accepts both "5.38.0" and "perl-5.38.0". perlbrewRootstring?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?)extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder.versionstring The perlbrew version name. Accepts both "5.38.0" and "perl-5.38.0". perlbrewRootstring?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>)extensionIResourceBuilder<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
builderIResourceBuilder<TResource>The resource builder.Returns
IResourceBuilder<TResource>A reference to the ApplicationModel.IResourceBuilder`1.WithProjectDependencies(IResourceBuilder<TResource>, bool)Section titled WithProjectDependencies(IResourceBuilder<TResource>, bool)extensionIResourceBuilder<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
builderIResourceBuilder<TResource>The resource builder.cartonDeploymentbooloptional 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.