Windows build	Linux build	Docker	Code quality	Test coverage
				Boilerplate Nothing to test

Binaries	Chocolatey package

hello-netcoreapp is a basic .NET Core console application that prints "Hello World!". This repository contains additional scripts and files for building the app and creating release artifacts for a framework-dependent deployment (FDD), self-contained deployment (SCD), Docker image, Chocolatey package and AppImage.

This repository is meant to be a starting point for any new .NET Core console application. You can fork it and base your project upon it. If you improve anything in your fork, please create a PR ☺ .

The basic app was created using dotnet new console with the .NET Core SDK 2.0 and then extended for our purposes.

• Terminology
• Directory structure
• Build
  • Via cloud service
    • AppVeyor
    • Travis CI
    • Docker Cloud
  • Locally
    • FDD + SCD + Chocolatey package + AppImage
      • Build all artifacts
      • Build one artifact
    • Docker image
• Run
  • FDD
  • SCD
  • Docker container
  • Chocolatey package
  • AppImage
• Simplify running the app
• Uninstall

• FDD - Framework-dependent deployment:

  The app relies on an installed version of either the cross-platform .NET Core runtime or the Windows-only full .NET Framework. But it's completely portable to all operating systems where the runtime is installed.

• SCD - Self-contained deployment:

  The app is completely self-contained. .NET Core runtime files are delivered with the executable, making this package slightly bigger than an FDD. It's independent of an installed .NET Core runtime, but not portable, so multiple SCDs must be created and each one only runs on a family of operating systems.

• Docker image:

  The app can be run as Docker container (Linux and Windows), which is based on the official Microsoft/dotnet Docker image, using the image for FDDs that Microsoft recommends for use in production.

• Chocolatey package:

  Chocolatey is a package manager for Windows, allowing you to install apps with one CLI command. Its package format is very similar to NuGet's. See https://chocolatey.org/ for details.

• AppImage:

  AppImage is a new packaging format that allows you to execute an app on most Linux distributions without having to install any runtimes, dependencies or the app itself. It's portable, can optionally be integrated into the OS (MIME type registration, inclusion in start menu, ...) and optionally run in a sandbox like Firejail. See http://appimage.org/ for details.

For more info about FDD and SCD see: https://docs.microsoft.com/en-us/dotnet/articles/core/deploying/

• .github/: Contains GitHub specific files, like a code of conduct, contributing guidelines, as well as issue and pull request templates
• .vscode/: Contains files for debugging the app and the PowerShell scripts in Visual Studio Code
  • Used in case you open the root directory of the repository as workspace in Visual Studio Code
• appimage/: Contains files related to the AppImage
• artifacts/: Not contained in the git repository, but gets created when one of the build scripts is run
  • After a build script is run it contains the resulting release artifacts, such as hello-netcoreapp_v0.1.0_linux-x64.tar.gz
• docker/: Dockerfiles for building Docker images for Linux and Windows containers with the app
• docs/: Documentation about this project in Markdown files
• src/: Contains the application source code, basically just a main class (Program.cs) and project file (hello-netcoreapp.csproj)
  • .vscode/: Contains files for debugging the app in Visual Studio Code
    • Used in case you open the src directory of the repository as workspace in Visual Studio Code
• chocolatey/: Contains files related to the Chocolatey package
  • The hello-netcoreapp.portable.nuspec describes the package, the README.md is shown on Chocolatey or MyGet after publishing
  • hello-netcoreapp.nuspec is for building a meta package that just "points" to the portable version
• scripts/: Contains scripts for building the app and creating release artifacts
  • The *.ps1 scripts are for use in Windows (PowerShell), the *.sh scripts are for use in Linux.
• .travis.yml: Configuration file for Travis CI (Continuous Integration and Deployment cloud service, Linux)
• .appveyor.yml: Configuration file for AppVeyor (Continuous Integration and Deployment cloud service, Windows)
• VERSION: A file containing the version of the app. Gets injected into some other files before building.

This repository contains .appveyor.yml, which is a configuration file for the CI / CD cloud service AppVeyor.

It's configured to do the following:

1. Run the build script build.ps1, which produces *.zip archives for FDD and SCD, as well as a Chocolatey package
2. If a Git tag was pushed:

   • Deploy all artifacts to this repository's GitHub Releases

     Note: If the release already exists, existing files get overwritten (not all, only those where a new file was built, keeping files from the Travis CI build in case it finished first)

   • Deploy the Chocolatey package to this app's MyGet feed

This repository contains .travis.yml, which is a configuration file for the CI / CD cloud service Travis CI.

It's configured to do the following:

1. Run the build script build.sh, which produces *.tar.gz archives for FDD and SCD, as well as an AppImage
2. If a Git tag was pushed:
   • Deploy all artifacts to this repository's GitHub Releases

     Note: If the release already exists, existing files get overwritten (not all, only those where a new file was built, keeping files from the AppVeyor build in case it finished first)

The Docker image for Linux containers gets automatically build by Docker Cloud and pushed to the Docker Hub repository. This is because Docker Hub itself doesn't support multi-stage builds as of now (2017-07-08).

You can create the FDD, SCD, Docker image, Chocolatey package and AppImage locally as well.

• For building the FDDs and SCDs you need to have either the .NET Core SDK or Docker installed
  • Building the FDDs for .NET Framework 4.5.1 and 4.6.1 requires Windows
• For building the Docker image you need to have Docker installed
• For building the Chocolatey package you need to either use Windows and have Chocolatey installed or have Docker installed
• For building the AppImage you need to either use Linux or have Docker installed

Depending on your OS and installed software, run the following scripts:

The SCDs that are built depend on the runtime identifiers in the *.csproj. To add or remove SCDs, just edit that file accordingly (see available runtime identifiers).

Note: When running the build-with-docker.ps1 script, the build.sh script will be executed inside of a Docker container. This script requires some files to have LF as line ending instead of CRLF. Commiting files with CRLF endings won't help - check your Git configuration core.autocrlf instead.

To build just one artifact, you can pass the necessary arguments to the script, like so:

• .\scripts\build.ps1 -publishType "fdd" -frameworkOrRuntime "netcoreapp2.0"
• .\scripts\build-with-docker.ps1 -publishType "scd" -frameworkOrRuntime "linux-x64"
• ./scripts/build.sh "fdd" "netcoreapp2.0"
• ./scripts/build-with-docker.sh "scd" "linux-x64"

The same restrictions apply as when building all artifacts with calling the build script without arguments, so the AppImage and Chocolatey packages aren't built in all cases.

Note: When building the Linux container image in Windows, the build.sh script will be executed inside of the Docker builder container. This script requires some files to have LF as line ending instead of CRLF. Commiting files with CRLF endings won't help - check your Git configuration core.autocrlf instead.

In the root directory of the repository, depending on which container host system you want to target:

• For Linux containers, run: docker build -f docker/Dockerfile -t local/hello-netcoreapp .
  • Works on both Linux and Windows
• For Windows containers, run: docker build -f docker/Dockerfile.nano -t local/hello-netcoreapp:nanoserver .
  • Only works on Windows

Note: You don't need to create a Windows container image for using Docker in Windows. Linux containers work just fine on Windows. Creating a Windows container image is specifically for actual Windows containers, see https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/.

You can run the console app either as FDD, SCD, Docker container, Chocolatey package or AppImage.

All artifacts are available for download from this repository's GitHub Releases. The Chocolatey package is also available on this app's MyGet feed.

Alternatively you can build the artifacts on your own (see the Build section in this README).

Depending on the operating system you use when building, there are multiple FDDs:

• hello-netcoreapp_v0.1.0_netcoreapp2.0 (when built on Windows and Linux)
• hello-netcoreapp_v0.1.0_net451 (when built on Windows)
• hello-netcoreapp_v0.1.0_net461 (when built on Windows)

Note: For running hello-netcoreapp_v0.1.0_netcoreapp2.0 you need to have the .NET Core runtime installed. The other FDDs are for Windows only and do not require any runtime being installed. Windows already comes with the full .NET Framework, so those FDDs work out of the box. Use the net461 version for up-to-date Windows systems and the net451 one for Windows 8.1 and Windows Server 2008 R2.

You can copy the archive (hello-netcoreapp_v0.1.0_netcoreapp2.0.zip or hello-netcoreapp_v0.1.0_netcoreapp2.0.tar.gz) to wherever you want to run the app, extract the archive and run:

• dotnet path/to/hello-netcoreapp.dll

Note: Depending on your system you might need to install the dependencies listed here:

• Windows
• Linux (For example for Ubuntu that's: apt-get install -y --no-install-recommends libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev uuid-dev unzip)
• macOS

Copy the archive (for example hello-netcoreapp_v0.1.0_linux-x64.zip or hello-netcoreapp_v0.1.0_linux-x64.tar.gz) to wherever you want to run the app (only the OS has to match), extract the archive and run:

• Linux: path/to/hello-netcoreapp
• Windows: path/to/hello-netcoreapp.exe

• The simplest way is to create the Docker container from the Docker image on Docker Hub:
  • docker run philippgille/hello-netcoreapp

    Note: This currently only works for Linux containers (on either Linux or Windows)

• Alternatively you can build the image locally (see the Build section in this README) and then create a container from the image in the local image cache:
  • For the Linux container: docker run local/hello-netcoreapp
    • Works on both Linux and Windows
  • For the Windows container: docker run local/hello-netcoreapp:nanoserver
    • Only works on Windows

Note 1: You can only install and run Chocolatey packages on Windows!

Note 2: Depending on your system you might need to install Microsoft Visual C++ 2015 Redistributable Update 3, as mentioned in the documentation about the .NET Core prerequisites for Windows

First you need to install the package with one of the following ways:

• The simplest way to install it is via the MyGet feed, which also allows you to easily update the app later:
  • choco install hello-netcoreapp --source https://www.myget.org/F/hello-netcoreapp
• AppVeyor also automatically publishes all *.nupkg artifacts to a project's NuGet feed, so this works as well:
  • choco install hello-netcoreapp --source https://ci.appveyor.com/nuget/hello-netcoreapp
• Alternatively install the downloaded or locally built package:
  • choco install path\to\hello-netcoreapp.portable.0.1.0.nupkg
  • (Simply installing the meta package hello-netcoreapp.0.1.0.nupkg works if the portable package exists in the same directory)
• Alternatively you can also install via the package specification file in this repository:
  1. Either run build.ps1 or manually place artifacts\hello-netcoreapp_v0.1.0_win-x64 in chocolatey\tools
  2. choco install chocolatey\hello-netcoreapp.nuspec

Then run: hello-netcoreapp

Note: The package is installed in %ChocolateyInstall%/lib (e.g. C:\ProgramData\Chocolatey\lib)

Note 1: You can only use AppImages on Linux and you must either have fuse installed or mount or extract the AppImage, see AppImage/AppImageKit/wiki/FUSE

Note 2: Depending on your system you might need to install the dependencies listed in the documentation about the .NET Core prerequisites for Linux. For example for Ubuntu that's:

• apt-get install -y --no-install-recommends libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev uuid-dev unzip

After downloading the AppImage, you have to make it executable: chmod u+x hello-netcoreapp_v0.1.0_linux-x64.AppImage

Then run: hello-netcoreapp_v0.1.0_linux-x64.AppImage

For integrating the AppImage into your OS (MIME type registration, start menu), you can run the optional AppImage daemon. Read more about it here: https://github.com/AppImage/AppImageKit/blob/appimagetool/master/README.md#appimaged-usage

Note: This is not necessary if you installed the app with Chocolatey.

The app is portable, meaning the FDD or SCD can reside anywhere on your system (for example in $env:USERPROFILE\MyPortableApps\hello-netcoreapp on Windows or $HOME/myPortableApps/hello-netcoreapp on Linux), and Docker containers can be run anywhere anyway.

Now you should do the following, so you don't have to enter the full path of the executable (for FDD / SCD) or full docker command when you want to run the app:

• On Windows: Create a function (like an alias, but supports passing arguments) for the app for PowerShell:
  1. Edit the file returned by $PROFILE.CurrentUserAllHosts and add:
     • For FDD: function hello-netcoreapp { dotnet $env:USERPROFILE\MyPortableApps\hello-netcoreapp\hello-netcoreapp.dll $args }
     • For SCD: function hello-netcoreapp { $env:USERPROFILE\MyPortableApps\hello-netcoreapp\hello-netcoreapp.exe $args }
     • For Docker: function hello-netcoreapp { docker run --rm local/hello-netcoreapp $args }
  2. Source your Profile so that the alias becomes available immediately: . $PROFILE.CurrentUserAllHosts
• On Linux: Create a function (like an alias, but supports passing arguments) for the app for Bash:
  1. Edit ~/.bashrc and add:
     • For FDD: function hello-netcoreapp() { dotnet $HOME/myPortableApps/hello-netcoreapp/hello-netcoreapp.dll $@; }
     • For SCD: function hello-netcoreapp() { $HOME/myPortableApps/hello-netcoreapp/hello-netcoreapp $@; }
     • For Docker: function hello-netcoreapp() { docker run --rm philippgille/hello-netcoreapp $@; }
  2. Source your bashrc so that the alias becomes available immediately: source ~/.bashrc
• Linux alternative for SCD: Create a symbolic link in a directory that's already in the PATH:
  • ln -s $HOME/myPortableApps/hello-netcoreapp/hello-netcoreapp /usr/local/bin/hello-netcoreapp

Now you can run the following command on any OS and from any directory (and also pass arguments):

• hello-netcoreapp

Note: You shouldn't add the whole app directory to the PATH, because the directory contains many files and in some cases this leads to tab auto-completion for files like hello-netcoreapp.deps.json.

• FDD:
  1. Delete the directory that contains the hello-netcoreapp.dll
  2. Remove the function from your PowerShell profile / ~/.bashrc in case you set it
• SCD:
  1. Delete the directory that contains the hello-netcoreapp.exe (Windows) / hello-netcoreapp (Linux)
  2. Remove the function from your PowerShell profile / ~/.bashrc in case you set it
• Docker image:
  1. Delete the container: docker container rm <id>
  2. Delete the image: docker image rm philippgille/hello-netcoreapp
  3. Remove the function from your PowerShell profile / ~/.bashrc in case you set it
• Chocolatey package:
  • If you installed the meta package: choco uninstall hello-netcoreapp
  • Otherwise: choco uninstall hello-netcoreapp.portable
• AppImage:
  • Just delete the *.AppImage file