You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Nightly builds and NuGet feed](#nightly-builds-and-nuget-feed)
19
26
-[Contributing](#contributing)
20
27
-[More information](#more-information)
@@ -28,119 +35,139 @@ The easiest way to install the Giraffe template is by running the following comm
28
35
dotnet new -i "giraffe-template::*"
29
36
```
30
37
31
-
This will pull and install the [giraffe-template NuGet package](https://www.nuget.org/packages/giraffe-template/)in your .NET environment and make it available to subsequent `dotnet new` commands.
38
+
This will pull and install the latest [giraffe-template NuGet package](https://www.nuget.org/packages/giraffe-template/)into your .NET environment and make it available to subsequent `dotnet new` commands.
32
39
33
-
## Basics
34
-
35
-
After the template has been installed you can create a new Giraffe web application by simply running `dotnet new giraffe` in your terminal:
40
+
## Updating the template
36
41
37
-
```
38
-
dotnet new giraffe
39
-
```
42
+
Whenever there is a new version of the Giraffe template you can update it by re-running the [instructions from the installation](#installation).
40
43
41
-
If you wish to use [Paket](https://fsprojects.github.io/Paket/) for your dependency management use the `--UsePaket` parameter when creating a new application:
44
+
You can also explicitly set the version when installing the template:
42
45
43
46
```
44
-
dotnet new giraffe --UsePaket
47
+
dotnet new -i "giraffe-template::0.11.0"
45
48
```
46
49
47
-
The Giraffe template only supports the F# language at the moment.
48
-
49
-
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.
50
-
51
-
Further information and more help can be found by running `dotnet new giraffe --help` in your terminal.
52
-
53
-
### ATTENTION: dotnet new bug in some versions of .NET Core 2.0
54
-
55
-
Affected SDKs:
56
-
57
-
- .NET SDK 2.1.X where X < 300
58
-
- This was fixed in SDK versions 2.1.300+
59
-
- Why? It's a bug in the templating engine: (https://github.com/dotnet/templating/issues/1373)
60
-
- This affects all templates which support only one language (like Giraffe which only supports F#)
61
-
- 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.
50
+
## Basics
62
51
63
-
How can I know what version of the SDK I use?
52
+
After the template has been installed you can create a new Giraffe web application by simply running `dotnet new giraffe` in your terminal:
64
53
65
54
```
66
-
dotnet --info
55
+
dotnet new giraffe
67
56
```
68
57
69
-
Short term fix:
70
-
71
-
Just specify the language when invoking, like
58
+
If you wish to use [Paket](https://fsprojects.github.io/Paket/) for your dependency management use the `--Paket` or `-P` parameter when creating a new application:
72
59
73
60
```
74
-
dotnet new giraffe -lang F#
61
+
dotnet new giraffe --Paket
75
62
```
76
63
77
-
Long term fix:
64
+
The Giraffe template only supports the F# language at the moment (given that Giraffe is an F# web framework this is on purpose).
78
65
79
-
Upgrade your SDK to versions 2.1.300+ (.NET Core 2.1)
66
+
Further information and more help can be found by running `dotnet new giraffe --help` in your terminal.
80
67
81
-
## Optional parameters
68
+
## Template Options
82
69
83
-
### --ViewEngine
70
+
### ViewEngine
84
71
85
-
The Giraffe template supports three different view engines:
72
+
The Giraffe template supports four project templates, three different view engines and one API only template:
86
73
87
74
-`giraffe` (default)
88
75
-`razor`
89
76
-`dotliquid`
90
77
-`none`
91
78
92
-
You can optionally specify the `--ViewEngine` parameter (short `-V`) to pass in one of the supported values:
79
+
Use the `--ViewEngine` parameter (short `-V`) to set one of the supported values from above:
93
80
94
81
```
95
82
dotnet new giraffe --ViewEngine razor
96
83
```
97
84
98
-
The same using the abbreviated `-V` parameter:
85
+
The same command can be abbreviated using the`-V` parameter:
99
86
100
87
```
101
88
dotnet new giraffe -V razor
102
89
```
103
90
104
-
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.
91
+
If you do not specify the `--ViewEngine` parameter then the `dotnet new giraffe` command will automatically create a Giraffe web application with the `Giraffe.ViewEngine` templating engine.
105
92
106
-
### --IncludeTests
93
+
### Solution
107
94
108
-
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:
95
+
When running `dotnet new giraffe` the created project will only be a single Giraffe project which can be added to an existing .NET Core solution. However, when generating a new Giraffe project from a blank sheet then the `--Solution` (or short `-S`) parameter can simplify the generation of an entire solution, including a `.sln` file and accompanied test projects:
109
96
110
97
```
111
-
dotnet new giraffe --IncludeTests
98
+
dotnet new giraffe --Solution
112
99
```
113
100
114
-
This parameter can also be combined with other parameters:
101
+
This will create the following structure:
115
102
116
103
```
117
-
dotnet new giraffe --ViewEngine razor --IncludeTests
104
+
src/
105
+
- AppName/
106
+
- Views/
107
+
- ...
108
+
- WebRoot/
109
+
- ...
110
+
- Models.fs
111
+
- Program.fs
112
+
...
113
+
tests/
114
+
- AppName.Tests/
115
+
- Tests.fs
116
+
...
117
+
build.bat
118
+
build.sh
119
+
AppName.sln
120
+
README.md
118
121
```
119
122
120
-
### --UsePaket
123
+
### ExcludeTests
121
124
122
-
If you prefer [Paket](https://fsprojects.github.io/) for managing your project dependencies then you can specify `--UsePaket` (`-U` for short):
125
+
When creating a new Giraffe application with the `--Solution` (`-S`) flag enabled, then by default the outputted project structure will include a unit test project as well. If this is not desired then add the `--ExcludeTests` or short handed `-E` parameter to prevent tests from being created:
123
126
124
127
```
125
-
dotnet new giraffe --UsePaket
128
+
dotnet new giraffe -S -E
126
129
```
127
130
128
-
This will exclude the package references from the *fsproj* file and include the needed *paket.dependencies* and *paket.references* files.
131
+
### Paket
129
132
130
-
> 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`).
133
+
If you prefer [Paket](https://fsprojects.github.io/) for managing your project dependencies then specify the `--Paket` (or `-P`) parameter to do so:
131
134
132
-
See the [Paket documentation](https://fsprojects.github.io/) for more details.
135
+
```
136
+
dotnet new giraffe --Paket
137
+
```
133
138
134
-
## Updating the template
139
+
This will exclude the package references from the `.fsproj` files and include the needed `paket.dependencies` and `paket.references` files.
135
140
136
-
Whenever there is a new version of the Giraffe template you can update it by re-running the [instructions from the installation](#installation).
141
+
For more information regarding the NuGet management and restore options via Paket please see the official [Paket documentation](https://fsprojects.github.io/) for details.
137
142
138
-
You can also explicitly set the version when installing the template:
143
+
## Known Issues
144
+
145
+
### Cyclic reference
146
+
147
+
Please be 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.
148
+
149
+
The same happens if you run a blanket `dotnet new giraffe` from within a folder which is called `Giraffe` as well.
150
+
151
+
### .NET Core 2.0 issues
152
+
153
+
The `dotnet new giraffe` command was temporarily broken in certain versions of .NET Core 2.x where all templates with a single supported language (e.g. like Giraffe which only supports F#) were throwing an error.
154
+
155
+
The affected SDKs are `2.1.x` where `x < 300`. The issue has been fixed in the SDK versions `2.1.300+`.
156
+
157
+
If you do run into this issue the workaround is to explicitly specify the language:
139
158
140
159
```
141
-
dotnet new -i "giraffe-template::0.11.0"
160
+
dotnet new giraffe -lang F#
142
161
```
143
162
163
+
### Using Visual Studio
164
+
165
+
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`.
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.
155
182
156
-
## Using Visual Studio
157
-
158
-
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:
0 commit comments