Creating an Extension Buildpack for .NET Apps

This topic explains how to write extension buildpacks for .NET apps.

Prerequisites

  • Linux or MacOS development machine or virtual machine
  • Golang v1.10 or later programming language
  • direnv environment variable manager for your shell

Initialize an Extension Buildpack

  1. To install the buildpack-packager CLI tool, run the commands below. The buildpack-packager provides boilerplate code that you can use to start writing your buildpack.

    go get github.com/cloudfoundry/libbuildpack/
    go install github.com/cloudfoundry/libbuildpack/packager
    
  2. To create your buildpack, run the following command:

    buildpack-packager init --name MY-BUILPACK-NAME --path=BUILDPACK-DIRECTORY
    

    Where:

    • MY-BUILDPACK-NAME is the name of the buildpack you are creating.
    • BUILDPACK-DIRECTORY is the directory created by the command. This directory contains the boilerplate code.

    For example:

    $ buildpack-packager init --name my-example --path=my-example-buildpack
    

  3. To activate direnv in your buildpack directory, run the following commands:

    cd my-example-buildpack
    direnv allow
    

Create an Extension Buildpack to Supply Additional DLLs to a .NET Framework App

Most .NET Framework apps are pushed with the Hosted Web Core (HWC) buildpack. The HWC buildpack contains an opinionated list of .NET dependencies and does not contain all the DLLs that every app could need.

If your app requires dependencies not contained in the HWC buildpack, we recommend that you create an extension buildpack. This extension buildpack references and supplies these dependencies to the app’s container when you push the app.

Note: You cannot add modules or extensions directly to HWC. HWC contains a number of built-in HWC features, like the URL Rewrite module and HTTP compression. Extensions should only provide additional functionality to your app. For more information about existing HWC features, see Features in HWC Buildpack.

To create an extension buildpack containing additional DLLs, follow the steps below:

  1. Create a list of the dependencies that your published app requires.

  2. Copy the DLLs for the dependencies into a zip file.

  3. Upload the zip file containing your dependencies to a private web server that is accessible by Cloud Foundry. You can also use an S3 bucket or Azure Storage.

  4. On the command line, browse to the directory created by the buildpack-packager init command above.

  5. Edit the manifest.yml file by adding a dependency section that references the DLL zip file as follows:

    dependencies:
    - name: my-binary
      uri: http://s3.amazon.com/my-bucket/DLL-ZIP-FILE
      version: 0.0.1
      sha256: GENERATED-SHA-256
      cf_stacks:
      - windows2016
    

    Where:

    • DLL-ZIP-FILE is the name of your DLL zip file.
    • GENERATED-SHA-256 is a SHA generated by running the following command:

      shasum -a256 DLL-ZIP-FILE
      

      Where DLL-ZIP-FILE is the name of your DLL zip file.

  6. Ensure the include_files section of the manifest contains bin/supply.exe.

  7. Edit the supply script, my-example-buildpack/src/my-example/supply.go, to add dependencies to the container’s PATH as follows:

    1. Add a stager.InstallDependency for the dependency and version you have in your manifest.yml file.
    2. Add a stager.AddBinDependency for every DLL file you want your app to be able to access. For example:

      dep := libbuildpack.Dependency{Name: "my-binary", Version: "0.0.1"}
      if err := s.Installer.InstallDependency(dep, s.Stager.DepDir()); err != nil {
        return err
      }
      if err := s.Stager.AddBinDependencyLink(filepath.Join(s.Stager.DepDir(), "MyBinary.dll"), "MyBinary.dll"); err != nil {
        return err
      }
      
  8. Edit scripts/build.sh to cross-compile as follows:

    GOOS=windows go build -ldflags="-s -w" -o bin/supply.exe mysql/supply/cli
    

Complete Extension Buildpack

  1. To build a cached buildpack artifact, run the following command:

    buildpack-packager build -cached -stack windows2016
    

    Note: If the buildpack code contains a mistake, buildpack-packager throws an error. Once all local errors are corrected, you must push your app to with the new extension buildpack to determine whether the new buildpack functions as intended.

  2. Upload the buildpack to a private web server accessible to Cloud Foundry. You can also use an S3 bucket or Azure Storage. You can upload the finished buildpack to the same web server as your dependencies.

  3. To deploy your app with the extension buildpack, run the following command:

    cf push my-app -s windows2016 -b BUILDPACK-URL -b hwc_buildpack
    

    Where BUILDPACK-URL is the URL where you uploaded the buildpack. For example:

    $ cf push my-app -s windows2016 -b http://s3.amazon.com/my-bucket/my-example-buildpack.zip -b hwc_buildpack
    

If your extension buildpack does not include the correct dependencies, you will receive an error message.

Combine Extension Buildpack with Other Features

If your extension buildpack has executables or scripts that need to be run, you can reference them either in the start command or in profile scripts.

  • For more information about the start command, see command in Deploying with Application Manifests.

  • For more information about profile scripts, see Configure Pre-Runtime Hooks in Deploy an Application.

Create a pull request or raise an issue on the source for this page in GitHub