# PerlAppResourceBuilderExtensions Methods - Package: [CommunityToolkit.Aspire.Hosting.Perl](/reference/api/csharp/communitytoolkit.aspire.hosting.perl.md) - Type: [PerlAppResourceBuilderExtensions](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions.md) - Kind: `Methods` - Members: `12` Extension methods for adding Perl application resources to the application model. ## AddPerlApi(IDistributedApplicationBuilder, string, string, string) - Name: `AddPerlApi(IDistributedApplicationBuilder, string, string, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L95) Adds a Perl API server resource (e.g., Mojolicious, Dancer2) to the application model. Passes the `daemon` subcommand so HTTP frameworks start a listener. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder 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` -- 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: ```csharp var builder = DistributedApplication.CreateBuilder(args); builder.AddPerlApi("perl-api", "../api", "API.pl"); builder.Build().Run(); ``` ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## AddPerlExecutable(IDistributedApplicationBuilder, string, string, string) - Name: `AddPerlExecutable(IDistributedApplicationBuilder, string, string, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L137) 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. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder 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` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Examples ```csharp var builder = DistributedApplication.CreateBuilder(args); builder.AddPerlExecutable("myapp", "../perl-app", "my-compiled-perl"); builder.Build().Run(); ``` ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## AddPerlModule(IDistributedApplicationBuilder, string, string, string) - Name: `AddPerlModule(IDistributedApplicationBuilder, string, string, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L116) Adds a Perl module to the application model. The module is executed using `perl -MModule::Name -e "Module::Name->run()"`. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder 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` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Examples ```csharp var builder = DistributedApplication.CreateBuilder(args); builder.AddPerlModule("worker", "../perl-worker", "MyApp::Worker"); builder.Build().Run(); ``` ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## AddPerlScript(IDistributedApplicationBuilder, string, string, string) - Name: `AddPerlScript(IDistributedApplicationBuilder, string, string, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L55) Adds a Perl script resource (worker, CLI tool, background service) to the application model. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder 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` -- 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: ```csharp var builder = DistributedApplication.CreateBuilder(args); builder.AddPerlScript("my-worker", "../scripts", "Worker.pl"); builder.Build().Run(); ``` ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithCarton(IResourceBuilder) - Name: `WithCarton(IResourceBuilder)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.PackageManager.cs#L176-L194) 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(IResourceBuilder, bool)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withprojectdependencies-iresourcebuilder-tresource-bool) to run `carton install` at startup. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithCarton( this IResourceBuilder builder) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks Carton only supports project-level dependency installation via `cpanfile`. Calling [PerlAppResourceBuilderExtensions.WithPackage(IResourceBuilder, string, bool, bool)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withpackage-iresourcebuilder-tresource-string-bool-bool) after `WithCarton()` will throw because Carton does not support installing individual modules. To install Carton, you may use "cpanm Carton". ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithCpanMinus(IResourceBuilder) - Name: `WithCpanMinus(IResourceBuilder)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.PackageManager.cs#L28-L43) Configures the Perl application to use cpanm (App::cpanminus) as its package manager instead of the default cpan. Call this before [PerlAppResourceBuilderExtensions.WithPackage(IResourceBuilder, string, bool, bool)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withpackage-iresourcebuilder-tresource-string-bool-bool) to change how packages are installed. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithCpanMinus( this IResourceBuilder builder) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithLocalLib(IResourceBuilder, string) - Name: `WithLocalLib(IResourceBuilder, string)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L474-L492) 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. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithLocalLib( this IResourceBuilder builder, string path = "local") { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) 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` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks Sets the following environment variables: - `PERL5LIB` -- `/lib/perl5` (module search path) - `PERL_LOCAL_LIB_ROOT` -- `` - `PERL_MM_OPT` -- `INSTALL_BASE=` - `PERL_MB_OPT` -- `--install_base ` These ensure modules are resolved from and installed into the local directory without requiring system-level permissions. 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. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithPackage(IResourceBuilder, string, bool, bool) - Name: `WithPackage(IResourceBuilder, string, bool, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.PackageManager.cs#L222-L235) 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(IResourceBuilder)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withcpanminus-iresourcebuilder-tresource) was called. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithPackage( this IResourceBuilder builder, string packageName, bool force = false, bool skipTest = false) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) 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` -- 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(IResourceBuilder)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withcpanminus-iresourcebuilder-tresource) was called. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithPerlbrew(IResourceBuilder, string, string?) - Name: `WithPerlbrew(IResourceBuilder, string, string?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L332) Configures the Perl application to use a specific perlbrew-managed Perl version. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithPerlbrew( this IResourceBuilder builder, string version, string? perlbrewRoot = null) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) 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` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithPerlbrewEnvironment(IResourceBuilder, string, string?) - Name: `WithPerlbrewEnvironment(IResourceBuilder, string, string?)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L364-L435) 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. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithPerlbrewEnvironment( this IResourceBuilder builder, string version, string? perlbrewRoot = null) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) 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` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## Remarks Perlbrew is Linux-only. On Windows, an `InvalidOperationException` is thrown with a recommendation to use [Berrybrew](https://github.com/stevieb9/berrybrew). When combined with [PerlAppResourceBuilderExtensions.WithLocalLib(IResourceBuilder, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.perl/perlappresourcebuilderextensions/methods.md#withlocallib-iresourcebuilder-tresource-string), modules are installed into the local directory rather than the perlbrew tree, keeping the perlbrew installation clean and enabling per-project module isolation. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithPerlCertificateTrust(IResourceBuilder) > **Experimental:** CTASPIREPERL001 - [Learn more](/diagnostics/ctaspireperl001/) - Name: `WithPerlCertificateTrust(IResourceBuilder)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.cs#L509-L533) 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. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithPerlCertificateTrust( this IResourceBuilder builder) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) The resource builder. ## Returns `IResourceBuilder` -- A reference to the `ApplicationModel.IResourceBuilder`1`. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System. ## WithProjectDependencies(IResourceBuilder, bool) - Name: `WithProjectDependencies(IResourceBuilder, bool)` - Modifiers: `extension` - Returns: `IResourceBuilder` - Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResourceBuilderExtensions.PackageManager.cs#L266-L298) 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]` If the active package manager is `cpan` (the default), it is automatically switched to `cpanm` since `cpan` does not support `--installdeps`. ```csharp public static class PerlAppResourceBuilderExtensions { public static IResourceBuilder WithProjectDependencies( this IResourceBuilder builder, bool cartonDeployment = false) { // ... } } ``` ## Parameters - `builder` (`IResourceBuilder`) 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` -- 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. ## ATS metadata ### ATS export - Available to Polyglot AppHosts through the Aspire Type System.