Document how to configure solutions with multiple web projects

[runesoerensen]

We should document how to specify the web application to serve for .NET apps built from a solution file. Here's a draft of what that may look like:

If your application codebase contain a solution with potentially multiple web applications, you’ll need to specify which one to run when deploying your code to Heroku (as there can only be one web process type receiving external HTTP traffic per Heroku application). You can specify this by adding a Procfile to the root of your application directory, defining the special web process type:

web: cd $(dirname $WEB_PROCESS_PATH); ./$(basename $WEB_PROCESS_PATH) --urls http://0.0.0.0:$PORT

Now create a Heroku app for each web application, and set the WEB_PROCESS_PATH config var on each app to the actual published executable path for your project. For the sample solution in this guide:

• Set the WEB_PROCESS_PATH config var to /workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish/BlazorApp for now.
• If you only need to run one web application, you can skip setting the config var and set the full process path in your Procfile, e.g. web: cd /workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish; /workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish/BlazorApp --urls http://0.0.0.0:$PORT

The path may differ a bit from what you see running dotnet publish from your application directory locally, but shouldn’t be too surprising — the path will usually follow this format:

/workspace/{project_name}/bin/{configuration}/{target_framework}/{runtime_identifier}/publish/{project_name}

• The root application directory will always be /workspace.
• The app will be published using the "Release" configuration by default.
• The target framework moniker (e.g. net8.0) will match the TargetFramework value for each project.
• The runtime identifier is based on the target platform. On Heroku, or when using Heroku’s heroku/builder:24 CNB builder, this will likely be either linux-arm64 or linux-amd64.
• The project name will usually match the file stem of the project file (e.g. foo for a foo.csproj file, unless the AssemblyName property is configured).

Now pack build your image locally (making sure to specify both the .NET and Procfile buildpacks (e.g. heroku/dotnet and heroku/procfile) unless you're using --builder heroku/builder:24):

pack build your-image-name \
  --buildpack packaged/aarch64-unknown-linux-musl/debug/heroku_dotnet \
  --buildpack heroku/procfile \
  --path your-solution-directory/

When the build succeeds, inspect and verify the output using pack inspect your-image-name:

TYPE                    SHELL        COMMAND        ARGS                                                                                                        WORK DIR
web (default)                        bash           -c cd $(dirname $WEB_PROCESS_PATH); ./$(basename $WEB_PROCESS_PATH) --urls http://0.0.0.0:$PORT             /workspace
BackgroundWorker                     bash           -c /workspace/BackgroundWorker/bin/Release/net8.0/linux-arm64/publish/BackgroundWorker                      /workspace/BackgroundWorker/bin/Release/net8.0/linux-arm64/publish
BlazorApp                            bash           -c /workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish/BlazorApp --urls http://0.0.0.0:$PORT        /workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish
WebApi                               bash           -c /workspace/WebApi/bin/Release/net8.0/linux-arm64/publish/WebApi --urls http://0.0.0.0:$PORT              /workspace/WebApi/bin/Release/net8.0/linux-arm64/publish

Verify that the web process can be configured and run as expected with the WEB_PROCESS_PATH variable:

docker run --rm -it -e "PORT=8080" -e "WEB_PROCESS_PATH=/workspace/BlazorApp/bin/Release/net8.0/linux-arm64/publish/BlazorApp" -p 8080:8080 --entrypoint web your-image-name