dotnet-installer/Documentation/manpages/sdk/dotnet-new.1
2018-03-30 11:48:04 -04:00

588 lines
16 KiB
Groff

.\"t
.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "dotnet new command \- .NET Core CLI" "1" "" "" ".NET Core"
.hy
.SH dotnet new
.PP
.SH NAME
.PP
\f[C]dotnet\ new\f[] \- Creates a new project, configuration file, or solution based on the specified template.
.SH SYNOPSIS
.SS .NET Core 2.0
.IP
.nf
\f[C]
dotnet\ new\ <TEMPLATE>\ [\-\-force]\ [\-i|\-\-install]\ [\-lang|\-\-language]\ [\-n|\-\-name]\ [\-o|\-\-output]\ [\-u|\-\-uninstall]\ [Template\ options]
dotnet\ new\ <TEMPLATE>\ [\-l|\-\-list]\ [\-\-type]
dotnet\ new\ [\-h|\-\-help]
\f[]
.fi
.SS .NET Core 1.x
.IP
.nf
\f[C]
dotnet\ new\ <TEMPLATE>\ [\-lang|\-\-language]\ [\-n|\-\-name]\ [\-o|\-\-output]\ [\-all|\-\-show\-all]\ [\-h|\-\-help]\ [Template\ options]
dotnet\ new\ <TEMPLATE>\ [\-l|\-\-list]
dotnet\ new\ [\-all|\-\-show\-all]
dotnet\ new\ [\-h|\-\-help]
\f[]
.fi
.PP
* * * * *
.SH DESCRIPTION
.PP
The \f[C]dotnet\ new\f[] command provides a convenient way to initialize a valid .NET Core project.
.PP
The command calls the template engine to create the artifacts on disk based on the specified template and options.
.SS Arguments
.PP
\f[C]TEMPLATE\f[]
.PP
The template to instantiate when the command is invoked.
Each template might have specific options you can pass.
For more information, see Template options.
.SS .NET Core 2.0
.PP
The command contains a default list of templates.
Use \f[C]dotnet\ new\ \-l\f[] to obtain a list of the available templates.
The following table shows the templates that come pre\-installed with the .NET Core 2.0 SDK.
The default language for the template is shown inside the brackets.
.PP
.TS
tab(@);
l l l.
T{
Template description
T}@T{
Template name
T}@T{
Languages
T}
_
T{
Console application
T}@T{
\f[C]console\f[]
T}@T{
[C#], F#, VB
T}
T{
Class library
T}@T{
\f[C]classlib\f[]
T}@T{
[C#], F#, VB
T}
T{
Unit test project
T}@T{
\f[C]mstest\f[]
T}@T{
[C#], F#, VB
T}
T{
xUnit test project
T}@T{
\f[C]xunit\f[]
T}@T{
[C#], F#, VB
T}
T{
ASP.NET Core empty
T}@T{
\f[C]web\f[]
T}@T{
[C#], F#
T}
T{
ASP.NET Core Web App (Model\-View\-Controller)
T}@T{
\f[C]mvc\f[]
T}@T{
[C#], F#
T}
T{
ASP.NET Core Web App
T}@T{
\f[C]razor\f[]
T}@T{
[C#]
T}
T{
ASP.NET Core with Angular
T}@T{
\f[C]angular\f[]
T}@T{
[C#]
T}
T{
ASP.NET Core with React.js
T}@T{
\f[C]react\f[]
T}@T{
[C#]
T}
T{
ASP.NET Core with React.js and Redux
T}@T{
\f[C]reactredux\f[]
T}@T{
[C#]
T}
T{
ASP.NET Core Web API
T}@T{
\f[C]webapi\f[]
T}@T{
[C#], F#
T}
T{
global.json file
T}@T{
\f[C]globaljson\f[]
T}@T{
T}
T{
Nuget config
T}@T{
\f[C]nugetconfig\f[]
T}@T{
T}
T{
Web config
T}@T{
\f[C]webconfig\f[]
T}@T{
T}
T{
Solution file
T}@T{
\f[C]sln\f[]
T}@T{
T}
T{
Razor page
T}@T{
\f[C]page\f[]
T}@T{
T}
T{
MVC ViewImports
T}@T{
\f[C]viewimports\f[]
T}@T{
T}
T{
MVC ViewStart
T}@T{
\f[C]viewstart\f[]
T}@T{
T}
.TE
.SS .NET Core 1.x
.PP
The command contains a default list of templates.
Use \f[C]dotnet\ new\ \-all\f[] to obtain a list of the available templates.
The following table shows the templates that come pre\-installed with the .NET Core 1.x SDK.
The default language for the template is shown inside the brackets.
.PP
.TS
tab(@);
l l l.
T{
Template description
T}@T{
Template name
T}@T{
Languages
T}
_
T{
Console application
T}@T{
\f[C]console\f[]
T}@T{
[C#], F#
T}
T{
Class library
T}@T{
\f[C]classlib\f[]
T}@T{
[C#], F#
T}
T{
Unit test project
T}@T{
\f[C]mstest\f[]
T}@T{
[C#], F#
T}
T{
xUnit test project
T}@T{
\f[C]xunit\f[]
T}@T{
[C#], F#
T}
T{
ASP.NET Core empty
T}@T{
\f[C]web\f[]
T}@T{
[C#]
T}
T{
ASP.NET Core Web App
T}@T{
\f[C]mvc\f[]
T}@T{
[C#], F#
T}
T{
ASP.NET Core Web API
T}@T{
\f[C]webapi\f[]
T}@T{
[C#]
T}
T{
Nuget config
T}@T{
\f[C]nugetconfig\f[]
T}@T{
T}
T{
Web config
T}@T{
\f[C]webconfig\f[]
T}@T{
T}
T{
Solution file
T}@T{
\f[C]sln\f[]
T}@T{
T}
.TE
.PP
* * * * *
.SH OPTIONS
.SS .NET Core 2.0
.PP
\f[C]\-\-force\f[]
.PP
Forces content to be generated even if it would change existing files.
This is required when the output directory already contains a project.
.PP
\f[C]\-h|\-\-help\f[]
.PP
Prints out help for the command.
It can be invoked for the \f[C]dotnet\ new\f[] command itself or for any template, such as \f[C]dotnet\ new\ mvc\ \-\-help\f[].
.PP
\f[C]\-i|\-\-install\ <PATH|NUGET_ID>\f[]
.PP
Installs a source or template pack from the \f[C]PATH\f[] or \f[C]NUGET_ID\f[] provided.
If you want to install a prerelease version of a template package, you need to specify the version in the format of \f[C]<package\-name>::<package\-version>\f[].
By default, \f[C]dotnet\ new\f[] passes * for the version, which represents the last stable package version.
See an example at the Examples section.
.PP
For information on creating custom templates, see Custom templates for dotnet new.
.PP
\f[C]\-l|\-\-list\f[]
.PP
Lists templates containing the specified name.
If invoked for the \f[C]dotnet\ new\f[] command, it lists the possible templates available for the given directory.
For example if the directory already contains a project, it doesn't list all project templates.
.PP
\f[C]\-lang|\-\-language\ {C#|F#|VB}\f[]
.PP
The language of the template to create.
The language accepted varies by the template (see defaults in the arguments section).
Not valid for some templates.
.PP
\f[C]\-n|\-\-name\ <OUTPUT_NAME>\f[]
.PP
The name for the created output.
If no name is specified, the name of the current directory is used.
.PP
\f[C]\-o|\-\-output\ <OUTPUT_DIRECTORY>\f[]
.PP
Location to place the generated output.
The default is the current directory.
.PP
\f[C]\-\-type\f[]
.PP
Filters templates based on available types.
Predefined values are \[lq]project\[rq], \[lq]item\[rq] or \[lq]other\[rq].
.PP
\f[C]\-u|\-\-uninstall\ <PATH|NUGET_ID>\f[]
.PP
Uninstalls a source or template pack at the \f[C]PATH\f[] or \f[C]NUGET_ID\f[] provided.
.RS
.PP
[!NOTE] To uninstall a template using a \f[C]PATH\f[], you need to fully qualify the path.
For example, \f[I]C:/Users/<USER>/Documents/Templates/GarciaSoftware.ConsoleTemplate.CSharp\f[] will work, but \f[I]./GarciaSoftware.ConsoleTemplate.CSharp\f[] from the containing folder will not.
Additionally, do not include a final terminating directory slash on your template path.
.RE
.SS .NET Core 1.x
.PP
\f[C]\-all|\-\-show\-all\f[]
.PP
Shows all templates for a specific type of project when running in the context of the \f[C]dotnet\ new\f[] command alone.
When running in the context of a specific template, such as \f[C]dotnet\ new\ web\ \-all\f[], \f[C]\-all\f[] is interpreted as a force creation flag.
This is required when the output directory already contains a project.
.PP
\f[C]\-h|\-\-help\f[]
.PP
Prints out help for the command.
It can be invoked for the \f[C]dotnet\ new\f[] command itself or for any template, such as \f[C]dotnet\ new\ mvc\ \-\-help\f[].
.PP
\f[C]\-l|\-\-list\f[]
.PP
Lists templates containing the specified name.
If invoked for the \f[C]dotnet\ new\f[] command, it lists the possible templates available for the given directory.
For example if the directory already contains a project, it doesn't list all project templates.
.PP
\f[C]\-lang|\-\-language\ {C#|F#}\f[]
.PP
The language of the template to create.
The language accepted varies by the template (see defaults in the arguments section).
Not valid for some templates.
.PP
\f[C]\-n|\-\-name\ <OUTPUT_NAME>\f[]
.PP
The name for the created output.
If no name is specified, the name of the current directory is used.
.PP
\f[C]\-o|\-\-output\ <OUTPUT_DIRECTORY>\f[]
.PP
Location to place the generated output.
The default is the current directory.
.PP
* * * * *
.SS Template options
.PP
Each project template may have additional options available.
The core templates have the following additional options:
.SS .NET Core 2.0
.PP
\f[B]console, angular, react, reactredux\f[]
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]classlib\f[]
.PP
\f[C]\-f|\-\-framework\ <FRAMEWORK>\f[] \- Specifies the framework to target.
Values: \f[C]netcoreapp2.0\f[] to create a .NET Core Class Library or \f[C]netstandard2.0\f[] to create a .NET Standard Class Library.
The default value is \f[C]netstandard2.0\f[].
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]mstest, xunit\f[]
.PP
\f[C]\-p|\-\-enable\-pack\f[] \- Enables packaging for the project using dotnet pack.
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]globaljson\f[]
.PP
\f[C]\-\-sdk\-version\ <VERSION_NUMBER>\f[] \- Specifies the version of the .NET Core SDK to use in the \f[I]global.json\f[] file.
.PP
\f[B]web\f[]
.PP
\f[C]\-\-use\-launch\-settings\f[] \- Includes \f[I]launchSettings.json\f[] in the generated template output.
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]webapi\f[]
.PP
\f[C]\-au|\-\-auth\ <AUTHENTICATION_TYPE>\f[] \- The type of authentication to use.
The possible values are:
.IP \[bu] 2
\f[C]None\f[] \- No authentication (Default).
.IP \[bu] 2
\f[C]IndividualB2C\f[] \- Individual authentication with Azure AD B2C.
.IP \[bu] 2
\f[C]SingleOrg\f[] \- Organizational authentication for a single tenant.
.IP \[bu] 2
\f[C]Windows\f[] \- Windows authentication.
.PP
\f[C]\-\-aad\-b2c\-instance\ <INSTANCE>\f[] \- The Azure Active Directory B2C instance to connect to.
Use with \f[C]IndividualB2C\f[] authentication.
The default value is \f[C]https://login.microsoftonline.com/tfp/\f[].
.PP
\f[C]\-ssp|\-\-susi\-policy\-id\ <ID>\f[] \- The sign\-in and sign\-up policy ID for this project.
Use with \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-\-aad\-instance\ <INSTANCE>\f[] \- The Azure Active Directory instance to connect to.
Use with \f[C]SingleOrg\f[] authentication.
The default value is \f[C]https://login.microsoftonline.com/\f[].
.PP
\f[C]\-\-client\-id\ <ID>\f[] \- The Client ID for this project.
Use with \f[C]IndividualB2C\f[] or \f[C]SingleOrg\f[] authentication.
The default value is \f[C]11111111\-1111\-1111\-11111111111111111\f[].
.PP
\f[C]\-\-domain\ <DOMAIN>\f[] \- The domain for the directory tenant.
Use with \f[C]SingleOrg\f[] or \f[C]IndividualB2C\f[] authentication.
The default value is \f[C]qualified.domain.name\f[].
.PP
\f[C]\-\-tenant\-id\ <ID>\f[] \- The TenantId ID of the directory to connect to.
Use with \f[C]SingleOrg\f[] authentication.
The default value is \f[C]22222222\-2222\-2222\-2222\-222222222222\f[].
.PP
\f[C]\-r|\-\-org\-read\-access\f[] \- Allows this application read\-access to the directory.
Only applies to \f[C]SingleOrg\f[] or \f[C]MultiOrg\f[] authentication.
.PP
\f[C]\-\-use\-launch\-settings\f[] \- Includes \f[I]launchSettings.json\f[] in the generated template output.
.PP
\f[C]\-uld|\-\-use\-local\-db\f[] \- Specifies LocalDB should be used instead of SQLite.
Only applies to \f[C]Individual\f[] or \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]mvc, razor\f[]
.PP
\f[C]\-au|\-\-auth\ <AUTHENTICATION_TYPE>\f[] \- The type of authentication to use.
The possible values are:
.IP \[bu] 2
\f[C]None\f[] \- No authentication (Default).
.IP \[bu] 2
\f[C]Individual\f[] \- Individual authentication.
.IP \[bu] 2
\f[C]IndividualB2C\f[] \- Individual authentication with Azure AD B2C.
.IP \[bu] 2
\f[C]SingleOrg\f[] \- Organizational authentication for a single tenant.
.IP \[bu] 2
\f[C]MultiOrg\f[] \- Organizational authentication for multiple tenants.
.IP \[bu] 2
\f[C]Windows\f[] \- Windows authentication.
.PP
\f[C]\-\-aad\-b2c\-instance\ <INSTANCE>\f[] \- The Azure Active Directory B2C instance to connect to.
Use with \f[C]IndividualB2C\f[] authentication.
The default value is \f[C]https://login.microsoftonline.com/tfp/\f[] .
.PP
\f[C]\-ssp|\-\-susi\-policy\-id\ <ID>\f[] \- The sign\-in and sign\-up policy ID for this project.
Use with \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-rp|\-\-reset\-password\-policy\-id\ <ID>\f[] \- The reset password policy ID for this project.
Use with \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-ep|\-\-edit\-profile\-policy\-id\ <ID>\f[] \- The edit profile policy ID for this project.
Use with \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-\-aad\-instance\ <INSTANCE>\f[] \- The Azure Active Directory instance to connect to.
Use with \f[C]SingleOrg\f[] or \f[C]MultiOrg\f[] authentication.
The default value is \f[C]https://login.microsoftonline.com/\f[].
.PP
\f[C]\-\-client\-id\ <ID>\f[] \- The Client ID for this project.
Use with \f[C]IndividualB2C\f[], \f[C]SingleOrg\f[], or \f[C]MultiOrg\f[] authentication.
The default value is \f[C]11111111\-1111\-1111\-11111111111111111\f[].
.PP
\f[C]\-\-domain\ <DOMAIN>\f[] \- The domain for the directory tenant.
Use with \f[C]SingleOrg\f[] or \f[C]IndividualB2C\f[] authentication..
The default value is \f[C]qualified.domain.name\f[].
.PP
\f[C]\-\-tenant\-id\ <ID>\f[] \- The TenantId ID of the directory to connect to.
Use with \f[C]SingleOrg\f[] authentication..
The default value is \f[C]22222222\-2222\-2222\-2222\-222222222222\f[].
.PP
\f[C]\-\-callback\-path\ <PATH>\f[] \- The request path within the application's base path of the redirect URI.
Use with \f[C]SingleOrg\f[] or \f[C]IndividualB2C\f[] authentication..
The default value is \f[C]/signin\-oidc\f[].
.PP
\f[C]\-r|\-\-org\-read\-access\f[] \- Allows this application read\-access to the directory.
Only applies to \f[C]SingleOrg\f[] or \f[C]MultiOrg\f[] authentication.
.PP
\f[C]\-\-use\-launch\-settings\f[] \- Includes \f[I]launchSettings.json\f[] in the generated template output.
.PP
\f[C]\-\-use\-browserlink\f[] \- Includes BrowserLink in the project.
.PP
\f[C]\-uld|\-\-use\-local\-db\f[] \- Specifies LocalDB should be used instead of SQLite.
Only applies to \f[C]Individual\f[] or \f[C]IndividualB2C\f[] authentication.
.PP
\f[C]\-\-no\-restore\f[] \- Doesn't perform an implicit restore during project creation.
.PP
\f[B]page\f[]
.PP
\f[C]\-na|\-\-namespace\ <NAMESPACE_NAME>\f[]\- Namespace for the generated code.
The default value is \f[C]MyApp.Namespace\f[].
.PP
\f[C]\-np|\-\-no\-pagemodel\f[] \- Creates the page without a PageModel.
.PP
\f[B]viewimports\f[]
.PP
\f[C]\-na|\-\-namespace\ <NAMESPACE_NAME>\f[]\- Namespace for the generated code.
The default value is \f[C]MyApp.Namespace\f[].
.SS .NET Core 1.x
.PP
\f[B]console, xunit, mstest, web, webapi\f[]
.PP
\f[C]\-f|\-\-framework\f[] \- Specifies the framework to target.
Values: \f[C]netcoreapp1.0\f[] or \f[C]netcoreapp1.1\f[].
The default value is \f[C]netcoreapp1.0\f[].
.PP
\f[B]classlib\f[]
.PP
\f[C]\-f|\-\-framework\f[] \- Specifies the framework to target.
Values: \f[C]netcoreapp1.0\f[], \f[C]netcoreapp1.1\f[], or \f[C]netstandard1.0\f[] to \f[C]netstandard1.6\f[].
The default value is \f[C]netstandard1.4\f[].
.PP
\f[B]mvc\f[]
.PP
\f[C]\-f|\-\-framework\f[] \- Specifies the framework to target.
Values: \f[C]netcoreapp1.0\f[] or \f[C]netcoreapp1.1\f[].
The default value is \f[C]netcoreapp1.0\f[].
.PP
\f[C]\-au|\-\-auth\f[] \- The type of authentication to use.
Values: \f[C]None\f[] or \f[C]Individual\f[].
The default value is \f[C]None\f[].
.PP
\f[C]\-uld|\-\-use\-local\-db\f[] \- Specifies whether or not to use LocalDB instead of SQLite.
Values: \f[C]true\f[] or \f[C]false\f[].
The default value is \f[C]false\f[].
.PP
* * * * *
.SH EXAMPLES
.PP
Create an F# console application project in the current directory:
.PP
\f[C]dotnet\ new\ console\ \-lang\ f#\f[]
.PP
Create a .NET Standard class library project in the specified directory (available only with .NET Core 2.0 SDK or later versions):
.PP
\f[C]dotnet\ new\ classlib\ \-lang\ VB\ \-o\ MyLibrary\f[]
.PP
Create a new ASP.NET Core C# MVC application project in the current directory with no authentication targeting .NET Core 2.0:
.PP
\f[C]dotnet\ new\ mvc\ \-au\ None\ \-f\ netcoreapp2.0\f[]
.PP
Create a new xUnit application targeting .NET Core 2.0:
.PP
\f[C]dotnet\ new\ xunit\ \-\-framework\ netcoreapp2.0\f[]
.PP
List all templates available for MVC:
.PP
\f[C]dotnet\ new\ mvc\ \-l\f[]
.PP
Install version 2.0 of the Single Page Application templates for ASP.NET Core (command option available for .NET Core SDK 1.1 and later versions only):
.PP
\f[C]dotnet\ new\ \-i\ Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0\f[]
.SS See also
.PP
Custom templates for dotnet new
.PD 0
.P
.PD
Create a custom template for dotnet new
.PD 0
.P
.PD
dotnet/dotnet\-template\-samples GitHub repo
.PD 0
.P
.PD
Available templates for dotnet new
.SH AUTHORS
mairaw.