Skip to content

Updates to the CLI commands reference #1129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 14, 2016
Merged

Updates to the CLI commands reference #1129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
240292c
reviewed cli commands topics
mairaw Oct 7, 2016
07a6bdf
removed byline
mairaw Oct 7, 2016
97d27b3
minor fixes
mairaw Oct 7, 2016
c69c0b9
fixed broken links
mairaw Oct 8, 2016
a95de69
addressed feedback
mairaw Oct 13, 2016
3c364aa
clarified language
mairaw Oct 13, 2016
8c49a7d
fixed typo
mairaw Oct 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 40 additions & 23 deletions docs/core/tools/dotnet-build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,31 @@
---
title: dotnet-build
description: dotnet-build
keywords: .NET, .NET Core
title: dotnet-build command | .NET Core SDK
description: The dotnet-build command builds a project and all of its dependencies.
keywords: dotnet-build, CLI, CLI command, .NET Core
author: mairaw
manager: wpickett
ms.date: 06/20/2016
ms.date: 10/13/2016
ms.topic: article
ms.prod: .net-core
ms.technology: .net-core-technologies
ms.devlang: dotnet
ms.assetid: 70285a83-4103-4617-be8b-d0e1e9a4a91d
---

dotnet-build
===========
#dotnet-build

## NAME
## Name
dotnet-build -- Builds a project and all of its dependencies

## SYNOPSIS
## Synopsis

`dotnet build [--output]
`dotnet build [--help] [--output]
[--build-base-path] [--framework]
[--configuration] [--runtime] [--version-suffix]
[--build-profile] [--no-incremental] [--no-dependencies]
[<project>]`
[<project>]`

## DESCRIPTION
## Description

The `dotnet build` command builds multiple source file from a source project and its dependencies into a binary.
By default, the resulting binary is in Intermediate Language (IL) and has a DLL extension.
Expand Down Expand Up @@ -55,31 +54,35 @@ In order to build an executable application instead of a library, you need a [sp
}
```

## OPTIONS
## Options

`-o`, `--output` [DIR]
`-h|--help`

Directory in which to place the built binaries.
Prints out a short help for the command.

`-b`, `--build-base-path` [DIR]
`-o|--output <OUTPUT_DIRECTORY>`

Directory in which to place the built binaries. You also need to define `--framework` when you specify this option.

`-b|--build-base-path <OUTPUT_DIRECTORY>`

Directory in which to place temporary outputs.

`-f`, `--framework` [FRAMEWORK]
`-f|--framework <FRAMEWORK>`

Compiles for a specific framework. The framework needs to be defined in the project.json file.
Compiles for a specific framework. The framework needs to be defined in the [project.json](project-json.md#frameworks) file.

`-c`, `--configuration` [Debug|Release]
`-c|--configuration [Debug|Release]`

Defines a configuration under which to build. If omitted, it defaults to Debug.
Defines a configuration under which to build. If omitted, it defaults to `Debug`.

`-r`, `--runtime` [RUNTIME_IDENTIFIER]
`-r|--runtime [RUNTIME_IDENTIFIER]`

Target runtime to build for.
Target runtime to build for. For a list of Runtime Identifiers (RIDs) you can use, see the [RID catalog](../rid-catalog.md).

`--version-suffix` [VERSION_SUFFIX]
`--version-suffix [VERSION_SUFFIX]`

Defines what `*` should be replaced with in the version field in the project.json file. The format follows NuGet's version guidelines.
Defines what `*` should be replaced with in the version field in the [project.json](project-json.md#version) file. The format follows NuGet's version guidelines.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would a link to "NuGet's version guidelines" be useful here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would, I just need to find it 😄
I'll check with the team if there is any.


`--build-profile`

Expand All @@ -92,3 +95,17 @@ Marks the build as unsafe for incremental build. This turns off incremental comp
`--no-dependencies`

Ignores project-to-project references and only builds the root project specified to build.

## Examples

Build a project and its dependencies:

`dotnet build`

Build a project and its dependencies using Release configuration:

`dotnet build --configuration Release`

Build a project and its dependencies for a specific runtime (in this example, Ubuntu 16.04):

`dotnet build --runtime ubuntu.16.04-x64`
77 changes: 34 additions & 43 deletions docs/core/tools/dotnet-install-script.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,36 @@
---
title: dotnet-install scripts reference
description: dotnet-install scripts reference
keywords: .NET, .NET Core
title: dotnet-install scripts | .NET Core SDK
description: Learn about the dotnet-install scripts to install the .NET Core CLI tools and the shared runtime.
keywords: dotnet-install, dotnet-install scripts, .NET Core
author: mairaw
manager: wpickett
ms.date: 06/20/2016
ms.date: 10/12/2016
ms.topic: article
ms.prod: .net-core
ms.technology: .net-core-technologies
ms.devlang: dotnet
ms.assetid: 59b9c456-2bfd-4adc-8202-a1c6a0a6c787
---

dotnet-install scripts reference
================================
#dotnet-install scripts reference

## NAME
dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and shared runtime
## Name
dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and the shared runtime

## SYNOPSIS
## Synopsis
Windows:

`dotnet-install.ps1 [-Channel] [-Version]
[-InstallDir] [-Debug] [-NoPath]
[-SharedRuntime]`

OS X/Linux:
macOS/Linux:

`dotnet-install.sh [--channel] [--version]
[--install-dir] [--debug] [--no-path]
[--shared-runtime]`

## DESCRIPTION
## Description
The `dotnet-install` scripts are used to perform a non-admin install of the CLI toolchain and the shared runtime. You can download the scripts from our [CLI GitHub repo](https://github.com/dotnet/cli/tree/rel/1.0.0-preview2/scripts/obtain).

Their main use case is to help with automation scenarios and non-admin installations. There are two scripts, one for PowerShell that works on Windows and a bash script that works on Linux/OS X. They both have the same behavior. Bash script also "understands" PowerShell switches so you can use them across the board.
Expand All @@ -43,7 +42,7 @@ By default, the script will add the install location to the $PATH for the curren

Before running the script, please install all the required [dependencies](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md).

You can install a specific version using the `--version` argument. The version needs to be specified as 3-part version (for example 1.0.0-13232). If omitted, it will default to the first global.json file found in the hierarchy above the folder where the script was invoked in that contains the `sdkVersion` property. If that is not present, it will use Latest.
You can install a specific version using the `--version` argument. The version needs to be specified as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) file found in the hierarchy above the folder where the script was invoked in that contains the `sdkVersion` property. If that is not present, it will use Latest.

You can also use this script to get the SDK or shared runtime debug binaries with debug symbols by using the `--debug` argument. If you do not do this on first install and realize you do need debug symbols later on, you can re-run the script with this argument and the version of the bits you installed.

Expand All @@ -53,83 +52,75 @@ Options are different between script implementations.
### PowerShell (Windows)
`-Channel [CHANNEL]`

Which channel (for example, "future", "preview", "production") to install from. The default value is "Production".
Which channel (for example, `future`, `preview`, `production`) to install from. The default value is `production`.

`-Version [VERSION]`

Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to the first global.json that contains the sdkVersion property; if that is not present, it will use Latest.
Which version of CLI to install; you need to specify the version as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) that contains the [sdkVersion](global-json.md#sdkversion) property; if that is not present, it will use Latest.

`-InstallDir [DIR]`

Path to install to. The directory is created if it doesn't exist. The default value is `%LocalAppData%\.dotnet`.
Path to install to. The directory is created if it doesn't exist. The default value is *%LocalAppData%\.dotnet*.

`-Debug`

**true** to indicate that larger packages containing debugging symbols should be used; otherwise, **false**. The default value is **false**.
`true` to indicate that larger packages containing debugging symbols should be used; otherwise, `false`. The default value is `false`.

`-NoPath`

**true** to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, **false**.
The default value is **false**, that is, the PATH is modified.
`true` to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, `false`.
The default value is `false`, that is, the PATH is modified.
This makes the CLI tools available immediately after install.

`-SharedRuntime`

**true** to install just the shared runtime bits; **false** to install the entire SDK. The default value is **false**.
`true` to install just the shared runtime bits; `false` to install the entire SDK. The default value is `false`.

### Bash (OS X/Linux)
### Bash (macOS/Linux)
`--channel [CHANNEL]`

Which channel (for example "future", "preview", "production") to install from. The default value is "Production".

`--version [VERSION]`

Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to the first global.json that contains the sdkVersion property; if that is not present, it will use Latest.
Which version of CLI to install; you need to specify the version as 3-part version (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) that contains the [sdkVersion](global-json.md#sdkversion) property; if that is not present, it will use Latest.

`--install-dir [DIR]`

Path to where to install. The directory is created if it doesn't exist. The default value is `$HOME/.dotnet`.

`--debug`

**true** to indicate that larger packages containing debugging symbols should be used; otherwise, **false**. The default value is **false**.
`true` to indicate that larger packages containing debugging symbols should be used; otherwise, `false`. The default value is `false`.

`--no-path`

**true** to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, **false**.
The default value is **false**, that is, the PATH is modified.
`true` to indicate that the prefix/installdir are not exported to the path for the current session; otherwise, `false`.
The default value is `false`, that is, the PATH is modified.
This makes the CLI tools available immediately after install.

`--shared-runtime`

**true** to install just the shared runtime bits; **false** to install the entire SDK. The default value is **false**.
`true` to install just the shared runtime bits; `false` to install the entire SDK. The default value is `false`.

## EXAMPLES
## Examples

Install the dev latest version to the default location:

Windows:

```
./dotnet-install.ps1 -Channel Future
```
`./dotnet-install.ps1 -Channel Future`

OS X/Linux:
macOS/Linux:

```
./dotnet-install.sh --channel Future
```
`./dotnet-install.sh --channel Future`

Installs the dev latest version to the default location.
Install the latest preview to the specified location:

Windows:

```
./dotnet-install.ps1 -Channel preview -InstallDir C:\cli
```

OS X/Linux:
`./dotnet-install.ps1 -Channel preview -InstallDir C:\cli`

```
./dotnet-install.sh --channel preview --install-dir ~/cli
```
macOS/Linux:

Installs the latest preview to the specified location.
`./dotnet-install.sh --channel preview --install-dir ~/cli`
57 changes: 28 additions & 29 deletions docs/core/tools/dotnet-new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,29 @@
---
title: dotnet-new
description: dotnet-new
keywords: .NET, .NET Core
title: dotnet-new command | .NET Core
description: The dotnet-new command creates new .NET Core projects in the current directory.
keywords: dotnet-new, CLI, CLI command, .NET Core
author: mairaw
manager: wpickett
ms.date: 06/20/2016
ms.date: 10/12/2016
ms.topic: article
ms.prod: .net-core
ms.technology: .net-core-technologies
ms.devlang: dotnet
ms.assetid: 263c3d05-3a47-46a6-8023-3ca16b488410
---

dotnet-new
==========
#dotnet-new

## NAME
dotnet-new -- Creates a new .NET Core project
## Name
dotnet-new -- Creates a new .NET Core project in the current directory

## SYNOPSIS
`dotnet new [--type] [--lang]`
## Synopsis
`dotnet new [--help] [--type] [--lang]`

## DESCRIPTION
## Description
The `dotnet new` command provides a convenient way to initialize a valid .NET Core project and sample source code to try out the Command Line Interface (CLI) toolset.

This command is invoked in the context of a directory. When invoked, the command will result in two main artifacts being dropped to the directory:
This command is invoked in the context of a directory. When invoked, the command will result in two main artifacts being dropped to the current directory:

1. A `Program.cs` (or `Program.fs`) file that contains a sample "Hello World" program.
2. A valid `project.json` file.
Expand All @@ -33,28 +32,28 @@ After this, the project is ready to be compiled and/or edited further.

## Options

`-l`, `--lang [C#|F#]`
`-h|--help`

Language of the project. Defaults to `C#`. `csharp` (`fsharp`) or `cs` (`fs`) are also valid options.
Prints out a short help for the command.

`-t`, `--type`
`-l|--lang <C#|F#>`

Type of the project. Valid values are `console`, `web`, `lib` and `xunittest`.
Language of the project. Defaults to `C#`. Other valid values are `csharp`, `fsharp`, `cs` and `fs`.

## EXAMPLES
`-t|--type`

`dotnet new`

Drops a C# project in the current directory.
Type of the project. Valid values for C# are `console`, `web`, `lib` and `xunittest` and for F# only `console` is valid.

`dotnet new --lang f#`
Drops an F# project in the current directory.
## Examples

Create a C# console application project in the current directory:

`dotnet new --lang c#`

Drops an C# project in the current directory.
`dotnet new` or `dotnet new --lang c#`

Create an F# console application project in the current directory:

`dotnet new --lang f#`

Create a new ASP.NET Core C# application project in the current directory:

`dotnet new -t web`

Drops a new ASP.NET Core project in the current directory.
`dotnet new -t web`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these descriptions be more explicit about the defaults? I.e. say that the first two examples create a console application and the the third example creates a C# application.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that. Fixed.

Loading