Skip to content

Perl hosting integration#1155

Open
Omnideth wants to merge 14 commits intoCommunityToolkit:mainfrom
Omnideth:feature-perl-integration
Open

Perl hosting integration#1155
Omnideth wants to merge 14 commits intoCommunityToolkit:mainfrom
Omnideth:feature-perl-integration

Conversation

@Omnideth
Copy link
Copy Markdown

** Closes #1153 **

Added a whole perl integration with a roadmap and everything.

PR Checklist

  • Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
  • Based off latest main branch of toolkit
  • PR doesn't include merge commits (always rebase on top of our main, if needed)
  • New integration
    • Docs are written
    • Added description of major feature to project description for NuGet package (4000 total character limit, so don't push entire description over that)
  • Tests for the changes have been added (for bug fixes / features) (if applicable)
  • Contains NO breaking changes
  • Every new API (including internal ones) has full XML docs
  • Code follows all style conventions

No breaking changes noticed.

Other information

I'm open to feedback or revisions, please let me know if you have any questions.

Copilot AI review requested due to automatic review settings March 11, 2026 16:17
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 11, 2026

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.sh | bash -s -- 1155

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.ps1) } 1155"

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a new CommunityToolkit.Aspire.Hosting.Perl hosting integration to run Perl scripts/APIs under Aspire, along with tests, documentation, and multiple example applications demonstrating different Perl dependency-management approaches.

Changes:

  • Added CommunityToolkit.Aspire.Hosting.Perl integration (resources, annotations, services, docs).
  • Added a new Perl test project plus CI wiring to run it.
  • Added multiple Perl examples (cpan/cpanm/carton/perlbrew + a multi-resource demo with a Blazor frontend), plus devcontainer updates to support Perl tooling.

Reviewed changes

Copilot reviewed 129 out of 178 changed files in this pull request and generated 23 comments.

Show a summary per file
File Description
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/ResourceCreationTests.cs Validates resource creation/annotations for Perl resources.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PlatformFactAttributes.cs Adds OS-specific xUnit fact attributes for conditional test execution.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlVersionDetectorTests.cs Unit tests for Perl version detection behaviors.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlModuleCheckerTests.cs Tests module detection behavior with environment variables.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlIntegrationTests.cs Integration test exercising a Perl API example via Aspire testing fixture.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlInstallationManagerTests.cs Tests validation + required-command annotations.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlAppResourceTests.cs Validates resource shape/contract expectations.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/PerlAppPublicApiTests.cs Public API argument validation tests.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/LoggingBehaviorTests.cs Tests log output behavior in run vs publish mode.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/DockerfileGenerationTests.cs Tests Dockerfile generation helpers for publish-mode.
tests/CommunityToolkit.Aspire.Hosting.Perl.Tests/CommunityToolkit.Aspire.Hosting.Perl.Tests.csproj Adds Perl test project references (including example AppHost).
src/CommunityToolkit.Aspire.Hosting.Perl/windows-environment-setup.md Windows manual setup documentation for Perl toolchain.
src/CommunityToolkit.Aspire.Hosting.Perl/nuget.config Adds project-local NuGet feed config for the Perl integration.
src/CommunityToolkit.Aspire.Hosting.Perl/docs/using-perl-integration.md Detailed “how to use” guide for the Perl hosting integration.
src/CommunityToolkit.Aspire.Hosting.Perl/docs/roadmap.md Roadmap doc for future Perl integration work.
src/CommunityToolkit.Aspire.Hosting.Perl/Services/PerlVersionDetector.cs Implements file/CLI/perlbrew-based version detection.
src/CommunityToolkit.Aspire.Hosting.Perl/Services/PerlModuleChecker.cs Implements module-installed probing via perl -M....
src/CommunityToolkit.Aspire.Hosting.Perl/Services/PerlInstallationManager.cs Implements perl installation validation via perl -v.
src/CommunityToolkit.Aspire.Hosting.Perl/Services/CpanfileParser.cs Parses cpanfile to extract required module names.
src/CommunityToolkit.Aspire.Hosting.Perl/README.md Package README plus links to docs/roadmap and credits.
src/CommunityToolkit.Aspire.Hosting.Perl/PerlbrewEnvironment.cs Models perlbrew environment paths and helpers.
src/CommunityToolkit.Aspire.Hosting.Perl/PerlPackageManager.cs Adds package manager enum + mapping to executable names.
src/CommunityToolkit.Aspire.Hosting.Perl/PerlModuleInstallerResource.cs Introduces installer resource type for module installs.
src/CommunityToolkit.Aspire.Hosting.Perl/PerlLaunchConfiguration.cs Defines JSON-serializable launch configuration shape (internal).
src/CommunityToolkit.Aspire.Hosting.Perl/PerlAppResource.cs Adds Perl app resource type (executable + service discovery).
src/CommunityToolkit.Aspire.Hosting.Perl/EntrypointType.cs Adds entrypoint type enum (script/api/module/executable).
src/CommunityToolkit.Aspire.Hosting.Perl/CommunityToolkit.Aspire.Hosting.Perl.csproj New Perl integration project definition.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlbrewResourceEnvironmentAnnotation.cs Marker annotation for perlbrew environment wiring.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlbrewEnvironmentAnnotation.cs Annotation holding perlbrew config + resolved environment.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlRequiredModuleAnnotation.cs Annotation capturing required module install settings.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlProjectInstallerAnnotation.cs Links resource to project dependency installer resource.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlPackageManagerAnnotation.cs Tracks package manager selection for a resource.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlModuleInstallerAnnotation.cs Links resource to per-module installer child resource.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlLocalLibResourceEnvironmentAnnotation.cs Marker annotation for resource env local::lib wiring.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlLocalLibInstallerEnvironmentAnnotation.cs Marker annotation for installer env local::lib wiring.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlLocalLibAnnotation.cs Stores configured local::lib path.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlEntrypointAnnotation.cs Stores entrypoint type + value for launch behavior.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlCertificateTrustAnnotation.cs Marker annotation for certificate trust registration.
src/CommunityToolkit.Aspire.Hosting.Perl/Annotations/PerlCartonDeploymentAnnotation.cs Tracks carton deployment-mode choice for publish.
global.json Adds Microsoft Testing Platform runner metadata.
examples/perl/perlbrew-environment-minimal/scripts/Worker.pl Example worker validating perlbrew-selected Perl version.
examples/perl/perlbrew-environment-minimal/nuget.config Example-local NuGet feed config.
examples/perl/perlbrew-environment-minimal/README.md Example documentation for perlbrew environment usage.
examples/perl/perlbrew-environment-minimal/PerlbrewEnvironmentMinimal.ServiceDefaults/PerlbrewEnvironmentMinimal.ServiceDefaults.csproj Example service defaults project.
examples/perl/perlbrew-environment-minimal/PerlbrewEnvironmentMinimal.ServiceDefaults/Extensions.cs Example service defaults extensions.
examples/perl/perlbrew-environment-minimal/PerlbrewEnvironmentMinimal.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/perlbrew-environment-minimal/PerlbrewEnvironmentMinimal.AppHost/PerlbrewEnvironmentMinimal.AppHost.csproj Example AppHost project.
examples/perl/perlbrew-environment-minimal/PerlbrewEnvironmentMinimal.AppHost/AppHost.cs Example AppHost wiring for perlbrew worker.
examples/perl/perlbrew-environment-minimal/.aspire/settings.json Aspire settings for example.
examples/perl/multi-resource/scripts/secondLayerApi.pl Second-layer Perl API example script.
examples/perl/multi-resource/scripts/Worker.pl Multi-resource example worker script w/ OpenTelemetry spans.
examples/perl/multi-resource/scripts/API.pl Multi-resource example API script (calls second layer).
examples/perl/multi-resource/nuget.config Example-local NuGet feed config.
examples/perl/multi-resource/MultiResource.ServiceDefaults/MultiResource.ServiceDefaults.csproj Multi-resource service defaults project.
examples/perl/multi-resource/MultiResource.ServiceDefaults/Extensions.cs Multi-resource service defaults extensions.
examples/perl/multi-resource/MultiResource.Driver/wwwroot/lib/bootstrap/dist/css/bootstrap-reboot.rtl.min.css Vendor static asset for example UI.
examples/perl/multi-resource/MultiResource.Driver/wwwroot/lib/bootstrap/dist/css/bootstrap-reboot.min.css Vendor static asset for example UI.
examples/perl/multi-resource/MultiResource.Driver/wwwroot/favicon.png Example UI favicon asset.
examples/perl/multi-resource/MultiResource.Driver/wwwroot/app.css Example UI styling.
examples/perl/multi-resource/MultiResource.Driver/appsettings.json Example driver app settings.
examples/perl/multi-resource/MultiResource.Driver/Properties/launchSettings.json Example driver launch settings.
examples/perl/multi-resource/MultiResource.Driver/Program.cs Example Blazor driver wiring + service discovery client.
examples/perl/multi-resource/MultiResource.Driver/MultiResource.Driver.csproj Example Blazor driver project.
examples/perl/multi-resource/MultiResource.Driver/Components/_Imports.razor Example UI imports.
examples/perl/multi-resource/MultiResource.Driver/Components/Routes.razor Example UI router.
examples/perl/multi-resource/MultiResource.Driver/Components/Pages/Weather.razor Example UI page.
examples/perl/multi-resource/MultiResource.Driver/Components/Pages/NotFound.razor Example UI page.
examples/perl/multi-resource/MultiResource.Driver/Components/Pages/Home.razor Example UI page that calls Perl endpoints.
examples/perl/multi-resource/MultiResource.Driver/Components/Pages/Error.razor Example UI error page.
examples/perl/multi-resource/MultiResource.Driver/Components/Pages/Counter.razor Example UI page.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/ReconnectModal.razor.js Example reconnect modal JS.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/ReconnectModal.razor.css Example reconnect modal CSS.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/ReconnectModal.razor Example reconnect modal component.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/NavMenu.razor.css Example nav menu CSS.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/NavMenu.razor Example nav menu component.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/MainLayout.razor.css Example layout CSS.
examples/perl/multi-resource/MultiResource.Driver/Components/Layout/MainLayout.razor Example layout component.
examples/perl/multi-resource/MultiResource.Driver/Components/App.razor Example UI host page.
examples/perl/multi-resource/MultiResource.AppHost/cpanfile Example Carton dependency manifest.
examples/perl/multi-resource/MultiResource.AppHost/appsettings.json Example AppHost settings.
examples/perl/multi-resource/MultiResource.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/multi-resource/MultiResource.AppHost/MultiResource.AppHost.csproj Example AppHost project.
examples/perl/multi-resource/MultiResource.AppHost/AppHost.cs Example orchestration: 2 Perl APIs + worker + Blazor frontend.
examples/perl/multi-resource/.aspire/settings.json Aspire settings for example.
examples/perl/cpanm-script-minimal/scripts/Worker.pl Minimal cpanm script worker example.
examples/perl/cpanm-script-minimal/nuget.config Example-local NuGet feed config.
examples/perl/cpanm-script-minimal/README.md Example documentation for cpanm script scenario.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.ServiceDefaults/Extensions.cs Example service defaults extensions.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.ServiceDefaults/CpanmScriptMinimal.ServiceDefaults.csproj Example service defaults project.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.Driver/Program.cs Example driver program.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.AppHost/CpanmScriptMinimal.AppHost.csproj Example AppHost project.
examples/perl/cpanm-script-minimal/CpanmScriptMinimal.AppHost/AppHost.cs Example AppHost wiring for cpanm worker.
examples/perl/cpanm-script-minimal/.aspire/settings.json Aspire settings for example.
examples/perl/cpanm-api-integration/scripts/API.pl Minimal API used by integration tests.
examples/perl/cpanm-api-integration/nuget.config Example-local NuGet feed config.
examples/perl/cpanm-api-integration/README.md Example documentation for cpanm API scenario.
examples/perl/cpanm-api-integration/CpanmApiIntegration.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/cpanm-api-integration/CpanmApiIntegration.AppHost/CpanmApiIntegration.AppHost.csproj Example AppHost project.
examples/perl/cpanm-api-integration/CpanmApiIntegration.AppHost/AppHost.cs Example AppHost wiring for cpanm API.
examples/perl/cpanm-api-integration/.aspire/settings.json Aspire settings for example.
examples/perl/cpan-script-minimal/scripts/Worker.pl Minimal “default cpan” worker example.
examples/perl/cpan-script-minimal/nuget.config Example-local NuGet feed config.
examples/perl/cpan-script-minimal/README.md Example documentation for default cpan scenario.
examples/perl/cpan-script-minimal/CpanScriptMinimal.ServiceDefaults/Extensions.cs Example service defaults extensions.
examples/perl/cpan-script-minimal/CpanScriptMinimal.ServiceDefaults/CpanScriptMinimal.ServiceDefaults.csproj Example service defaults project.
examples/perl/cpan-script-minimal/CpanScriptMinimal.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/cpan-script-minimal/CpanScriptMinimal.AppHost/CpanScriptMinimal.AppHost.csproj Example AppHost project.
examples/perl/cpan-script-minimal/CpanScriptMinimal.AppHost/AppHost.cs Example AppHost wiring for default cpan worker.
examples/perl/cpan-script-minimal/.aspire/settings.json Aspire settings for example.
examples/perl/carton-api-minimal/scripts/API.pl Minimal Carton API example script (incl. HTTPS wiring).
examples/perl/carton-api-minimal/nuget.config Example-local NuGet feed config.
examples/perl/carton-api-minimal/README.md Example documentation for Carton API scenario.
examples/perl/carton-api-minimal/CartonApiMinimal.ServiceDefaults/Extensions.cs Example service defaults extensions.
examples/perl/carton-api-minimal/CartonApiMinimal.ServiceDefaults/CartonApiMinimal.ServiceDefaults.csproj Example service defaults project.
examples/perl/carton-api-minimal/CartonApiMinimal.AppHost/cpanfile Example Carton dependency manifest.
examples/perl/carton-api-minimal/CartonApiMinimal.AppHost/Properties/launchSettings.json Example AppHost launch settings.
examples/perl/carton-api-minimal/CartonApiMinimal.AppHost/CartonApiMinimal.AppHost.csproj Example AppHost project.
examples/perl/carton-api-minimal/CartonApiMinimal.AppHost/AppHost.cs Example AppHost wiring for Carton API + cert mapping.
examples/perl/carton-api-minimal/.aspire/settings.json Aspire settings for example.
docs/diagnostics.md.bak Backup copy of diagnostics doc (should not be committed).
docs/diagnostics.md Extends diagnostics doc with Perl-specific experimental IDs.
README.md Adds Perl integration entry + badges/links to root README.
CommunityToolkit.Aspire.slnx Adds Perl projects/examples to solution listing.
CODEOWNERS.bak Backup copy of CODEOWNERS (should not be committed).
CODEOWNERS Adds ownership entries for Perl integration.
.gitignore.bak Backup copy of gitignore (should not be committed).
.gitignore Ignores Perl example local libs + cpanfile.snapshot.
.github/workflows/tests.yaml.bak Backup copy of workflow (should not be committed).
.github/workflows/tests.yaml Adds Hosting.Perl.Tests to CI matrix.
.devcontainer/post-create.sh Installs Perl tooling/deps in devcontainer setup.
.devcontainer/devcontainer.json Adds Node + Perl extensions to devcontainer config.

You can also share your feedback on Copilot code review. Take the survey.

@aaronpowell aaronpowell changed the title The Camel Cometh Perl hosting integration Mar 12, 2026
Copy link
Copy Markdown
Member

@aaronpowell aaronpowell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Solid bones within this integration. I've left a bunch of comments around some stuff I'd like cleaned up/changed, and some things that I don't think integrations should be handling.

Also, with the examples, I'd prefer to see them combined into a single example project rather than lots of small ones. This makes it easier to run the example and view the entire process of how the integration works, rather than having to jump between a bunch of different implementations.

And for codeowner, I'll send you an invite to the maintainer group, so you get notifications for review.

@Omnideth Omnideth requested a review from aaronpowell March 20, 2026 23:39
@Omnideth
Copy link
Copy Markdown
Author

I believe I have completed all issues, but there were quite a few. I tried to resolve them directly after a commit.

Please let me know if you see any stragglers.

Copy link
Copy Markdown
Member

@aaronpowell aaronpowell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have one outstanding question regarding the CI setup and Windows and also you'll need to merge with main and update the SDK for the app host to 13.2.0 now that that has been released.

Comment on lines +71 to +74
- name: Install cpanminus
if: runner.os == 'Linux'
shell: bash
run: sudo apt-get install -y cpanminus
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What will we be doing with Windows runners? Or are those tests not going to be run on Windows?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay so, strawberry perl on windows comes with cpanm, which is a better package manager for CLI than the cpan.

So on Linux distros often you need to use cpan to install cpanm. That's what this is trying to do.

I was assuming the tests would run on both, and that on the Linux side we'd just sneak in cpanm before the tests run.

This is my first time using actions though so it may not be right.

@Omnideth Omnideth force-pushed the feature-perl-integration branch from 615e9d4 to 2cfef06 Compare March 26, 2026 00:45
@Omnideth Omnideth requested a review from aaronpowell March 26, 2026 00:46
@Omnideth
Copy link
Copy Markdown
Author

Additionally it looks like the Windows runtime is getting a failure because of one of the other projects having too long a name. Looks like the otel collector.

Error: error: unable to create file examples/opentelemetry-collector/CommunityToolkit.Aspire.Hosting.OpenTelemetryCollector.ServiceDefaults/CommunityToolkit.Aspire.Hosting.OpenTelemetryCollector.ServiceDefaults.csproj: Filename too long

@aaronpowell
Copy link
Copy Markdown
Member

Additionally it looks like the Windows runtime is getting a failure because of one of the other projects having too long a name. Looks like the otel collector.

Error: error: unable to create file examples/opentelemetry-collector/CommunityToolkit.Aspire.Hosting.OpenTelemetryCollector.ServiceDefaults/CommunityToolkit.Aspire.Hosting.OpenTelemetryCollector.ServiceDefaults.csproj: Filename too long

Windows long names strikes again! You can change the path length restrictions on Windows

Copy link
Copy Markdown
Author

@Omnideth Omnideth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@Omnideth Omnideth force-pushed the feature-perl-integration branch from 1dda708 to 80887c5 Compare April 1, 2026 03:05
Omnideth added 13 commits April 1, 2026 07:29
… the apis, and the FactAttributes were in violation of xUnit3003.
-Removing redundant .csproj files.
-Removing aspire cli based .aspire/settings.json files
-Switched LinuxOnly/WindowsOnly attributes to the Toolkit's own version.
This commit pulls the perl install since both test runners come with perl.  It replaces it with a cpanminus install on the linux box.  Windows will have it already with Strawberry Perl.

It also undoes region use and inflates the file count accordingly.
-Avoiding DCP
-Cleaning up stylistically, getting cheap wins on expression bodied methods, etc.
-Second pass at minimizing the scope of #pragma usage.
-First pass at a mass test upgrade.

All that remains is a final test pass, documentation restructure, and example consolidation.
…r stripping down the examples to one.

I have either broken something with HTTPS on the dashboard, or I've found a bug, but it's too late to solve now.
… be the final one after testing on a Linux machine - it will condense the examples to one single project and pull the rest for a separate samples repo.
Examples cleaned up, condensed to one minimal example to show two perl things acting together with aspire as the glue.
…things on the resources themselves. To that end I've cut those tests and removed the logging statements.
…thors, but the Java integration had tags and description still. Will remediate if necessary.
@Omnideth Omnideth force-pushed the feature-perl-integration branch from c3c14c4 to fdf6a17 Compare April 1, 2026 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Perl hosting integration

3 participants