Giraffe web application template for the dotnet new command.

• Installation
• Basics
• Optional parameters
  • --ViewEngine
  • --IncludeTests
  • --UsePaket
• Updating the template
• Nightly builds and NuGet feed
• Contributing
• More information
• License

The easiest way to install the Giraffe template is by running the following command in your terminal:

dotnet new -i "giraffe-template::*"

This will pull and install the giraffe-template NuGet package in your .NET environment and make it available to subsequent dotnet new commands.

After the template has been installed you can create a new Giraffe web application by simply running dotnet new giraffe in your terminal:

dotnet new giraffe

If you wish to use Paket for your dependency management use the --UsePaket parameter when creating a new application:

dotnet new giraffe --UsePaket

The Giraffe template only supports the F# language at the moment.

Please be also aware that you cannot name your project "giraffe" (dotnet new giraffe -o giraffe) as this will lead the .NET Core CLI to fail with the error "NU1108-Cycle detected" when trying to resolve the project's dependencies.

Further information and more help can be found by running dotnet new giraffe --help in your terminal.

Affected SDKs:

• .NET SDK 2.1.X where X < 300
• This was fixed in SDK versions 2.1.300+
• Why? It's a bug in the templating engine: (dotnet/templating#1373)
• This affects all templates which support only one language (like Giraffe which only supports F#)
• The behavior is such that when you run dotnet new [template] you may not get any errors and it will just output the --help text for the template & CLI.

How can I know what version of the SDK I use?

dotnet --info

Short term fix:

Just specify the language when invoking, like

dotnet new giraffe -lang F#

Long term fix:

Upgrade your SDK to versions 2.1.300+ (.NET Core 2.1)

The Giraffe template supports three different view engines:

• giraffe (default)
• razor
• dotliquid
• none

You can optionally specify the --ViewEngine parameter (short -V) to pass in one of the supported values:

dotnet new giraffe --ViewEngine razor

The same using the abbreviated -V parameter:

dotnet new giraffe -V razor

If you do not specify the --ViewEngine parameter then the dotnet new giraffe command will automatically create a Giraffe web application with the default GiraffeViewEngine engine.

When creating a new Giraffe web application you can optionally specify the --IncludeTests (short -I) parameter to automatically generate a default unit test project for your application:

dotnet new giraffe --IncludeTests

This parameter can also be combined with other parameters:

dotnet new giraffe --ViewEngine razor --IncludeTests

If you prefer Paket for managing your project dependencies then you can specify --UsePaket (-U for short):

dotnet new giraffe --UsePaket

This will exclude the package references from the fsproj file and include the needed paket.dependencies and paket.references files.

If you do not run build.bat (or build.sh on **nix) before running dotnet restore you need to manually run ./.paket/paket.exe install (or mono ./.paket/paket.exe install).

See the Paket documentation for more details.

Whenever there is a new version of the Giraffe template you can update it by re-running the instructions from the installation.

You can also explicitly set the version when installing the template:

dotnet new -i "giraffe-template::0.11.0"

All official Giraffe packages are published to the official and public NuGet feed.

Unofficial builds (such as pre-release builds from the develop branch and pull requests) produce unofficial pre-release NuGet packages which can be pulled from the project's public NuGet feed on AppVeyor:

https://ci.appveyor.com/nuget/giraffe-template

If you add this source to your NuGet CLI or project settings then you can pull unofficial NuGet packages for quick feature testing or urgent hot fixes.

The basic giraffe template doesn't work with IIS Express which may be the default IIS used by Visual Studio 2017 to build & publish your application. Make sure to change your drop-down (the top of your window, next to the other Configuration Manager settings) IIS setting to be the name of your project and NOT IIS Express. Example:

Please use the ./build.ps1 PowerShell script to build and test the Giraffe template before submitting a PR.

The ./build.ps1 PowerShell script comes with the following feature switches:

Windows:

> ./build.ps1

MacOS and Linux:

$ pwsh ./build.ps1

Windows:

> ./build.ps1 -InstallTemplate

MacOS and Linux:

$ pwsh ./build.ps1 -InstallTemplate

Windows:

> ./build.ps1 -CreatePermutations

MacOS and Linux:

$ pwsh ./build.ps1 -CreatePermutations

Windows:

> ./build.ps1 -TestPermutations

MacOS and Linux:

$ pwsh ./build.ps1 -TestPermutations

Windows:

> ./build.ps1 -UpdatePaketDependencies

MacOS and Linux:

$ pwsh ./build.ps1 -UpdatePaketDependencies

For more information about Giraffe, how to set up a development environment, contribution guidelines and more please visit the main documentation page.

Apache 2.0