Skip to content
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

Fix-up dotnet command docs #1705

Merged
merged 7 commits into from
Mar 21, 2017
Merged

Fix-up dotnet command docs #1705

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
971ad33
Initial commit
Mar 10, 2017
9d80e27
Add links to Frameworks topic
Mar 10, 2017
29b2ab9
React to feedback
Mar 13, 2017
03ed8ba
Minor updates
Mar 15, 2017
30ec582
Merge branch 'master' into guardrex/dotnet-command-fixup
guardrex Mar 15, 2017
9cd1b11
Drop "portable" language for "framework-dependent" language
Mar 20, 2017
89799e8
React to feedback
Mar 21, 2017
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
34 changes: 15 additions & 19 deletions docs/core/tools/dotnet-add-package.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
---
title: dotnet-add package command | Microsoft Docs
description: The dotnet-add package command provides a convenient option to add NuGet package reference to a project.
keywords: dotnet-add , CLI, CLI command, .NET Core
keywords: dotnet-add, CLI, CLI command, .NET Core
author: spboyer
ms.author: mairaw
ms.date: 03/06/2017
ms.date: 03/15/2017
ms.topic: article
ms.prod: .net-core
ms.technology: dotnet-cli
ms.devlang: dotnet
ms.assetid: 88e0da69-a5ea-46cc-8b46-5493242b7af9
---

# dotnet-add package

## Name
Expand All @@ -19,22 +20,19 @@ ms.assetid: 88e0da69-a5ea-46cc-8b46-5493242b7af9

## Synopsis

```
dotnet add [project] package <package_name> [-v|--version] [-f|--framework] [-n|--no-restore] [-s|--source] [--package-directory]
dotnet add package [-h|--help]
```
`dotnet add [<PROJECT>] package <PACKAGE_NAME> [-v|--version] [-f|--framework] [-n|--no-restore] [-s|--source] [--package-directory] [-h|--help]`

## Description

The `dotnet add package` provides a convenient option to add a package reference to a project file. After running the command, there is a compatibility check to ensure the package attempting to be added is compatible with all of the frameworks in the project. If the check passes, a [restore](dotnet-restore.md) is run and the `<PackageReference>` fragment is added to the project file.
The `dotnet add package` command provides a convenient option to add a package reference to a project file. After running the command, there's a compatibility check to ensure the package is compatible with the frameworks in the project. If the check passes, a `<PackageReference>` element is added to the project file and [dotnet restore](dotnet-restore.md) is run.

For example, adding `Newtonsoft.Json` to *ToDo.csproj* produces an output similar to the following:
For example, adding `Newtonsoft.Json` to *ToDo.csproj* produces output similar to the following:

```
Microsoft (R) Build Engine version 15.1.545.13942
Copyright (C) Microsoft Corporation. All rights reserved.

Writing /var/folders/gj/1mgg_4jx7mbdqbhw1kgcpcjr0000gn/T/tmpm0kTMD.tmp
Writing /var/folders/gj/1mgg_4jx7mbdqbhw1kgcpcjr0000gn/T/tmpm0kTMD.tmp
info : Adding PackageReference for package 'Newtonsoft.Json' into project 'ToDo.csproj'.
log : Restoring packages for ToDo.csproj...
info : GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/index.json
Expand All @@ -45,21 +43,19 @@ info : Package 'Newtonsoft.Json' is compatible with all the specified frameworks
info : PackageReference for package 'Newtonsoft.Json' version '9.0.1' added to file 'ToDo.csproj'.
```

The *ToDo.csproj* file now contains a [`<PackageReference>`](https://docs.microsoft.com/nuget/consume-packages/package-references-in-project-files) fragment for the referenced package.
The *ToDo.csproj* file now contains a [`<PackageReference>`](https://docs.microsoft.com/nuget/consume-packages/package-references-in-project-files) element for the referenced package.

```xml
<PackageReference Include="Newtonsoft.Json">
<Version>9.0.1</Version>
</PackageReference>
<PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
```

## Arguments

`project`
`PROJECT`

The project file to operate on. If not specified, the command searches the current directory for one.
Specifies the project file. If not specified, the command searches the current directory for one.

`package_name`
`PACKAGE_NAME`

The package reference to add.

Expand All @@ -75,15 +71,15 @@ Version of the package.

`-f|--framework <FRAMEWORK>`

Adds a package reference only when targeting a specific framework.
Adds a package reference only when targeting a specific [framework](../../standard/frameworks.md).

`-n|--no-restore`

Adds a package reference without performing restore preview and compatibility check.
Adds a package reference without performing a restore preview and compatibility check.

`-s|--source <SOURCE>`

Uses a specific NuGet package source to use during the restore operation.
Uses a specific NuGet package source during the restore operation.

`--package-directory <PACKAGE_DIRECTORY>`

Expand Down
24 changes: 11 additions & 13 deletions docs/core/tools/dotnet-add-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,27 @@ description: The dotnet-add reference command provides a convenient option to ad
keywords: dotnet-add, CLI, CLI command, .NET Core
author: spboyer
ms.author: mairaw
ms.date: 03/13/2017
ms.date: 03/15/2017
ms.topic: article
ms.prod: .net-core
ms.technology: dotnet-cli
ms.devlang: dotnet
ms.assetid: 5e2a3efd-443c-4f23-a1b1-a662a5387879
---

# dotnet-add reference

## Name

`dotnet-add reference` - Adds project to project references.
`dotnet-add reference` - Adds project-to-project (P2P) references.

## Synopsis

```
dotnet add [project] reference [-f|--framework] <project_references>
dotnet add reference [-h|--help]
```
`dotnet add [<PROJECT>] reference [-f|--framework] <PROJECT_REFERENCES> [-h|--help]`

## Description

The `dotnet add reference` command provides a convenient option to add project references to a project. After running the command, the [`<ProjectReference>`](https://docs.microsoft.com/visualstudio/msbuild/common-msbuild-project-items) fragments are added to the project file.
The `dotnet add reference` command provides a convenient option to add project references to a project. After running the command, the [`<ProjectReference>`](https://docs.microsoft.com/visualstudio/msbuild/common-msbuild-project-items) elements are added to the project file.

```xml
<ItemGroup>
Expand All @@ -38,13 +36,13 @@ The `dotnet add reference` command provides a convenient option to add project r

## Arguments

`project`
`PROJECT`

Project file to operate on. If not specified, the command will search the current directory for one.
Specifies the project file. If not specified, the command will search the current directory for one.

`project_references`
`PROJECT_REFERENCES`

Project to project references to add. You can specify one or multiple projects. [Glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) are supported on Unix/Linux-based terminals.
Project-to-project (P2P) references to add. Specify one or more projects. [Glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) are supported on Unix/Linux-based systems.

## Options

Expand All @@ -54,7 +52,7 @@ Prints out a short help for the command.

`-f|--framework <FRAMEWORK>`

Adds project references only when targeting a specific framework.
Adds project references only when targeting a specific [framework](../../standard/frameworks.md).

## Examples

Expand All @@ -66,6 +64,6 @@ Add multiple project references:

`dotnet add reference lib1/lib1.csproj lib2/lib2.csproj`

Add multiple project references using a glob pattern on Unix/Linux:
Add multiple project references using a globbing pattern on Linux/Unix:

`dotnet add app/app.csproj reference **/*.csproj`
49 changes: 23 additions & 26 deletions docs/core/tools/dotnet-build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,54 +4,51 @@ description: The dotnet-build command builds a project and all of its dependenci
keywords: dotnet-build, CLI, CLI command, .NET Core
author: blackdwarf
ms.author: mairaw
ms.date: 03/06/2017
ms.date: 03/15/2017
ms.topic: article
ms.prod: .net-core
ms.technology: dotnet-cli
ms.devlang: dotnet
ms.assetid: 5e1a2bc4-a919-4a86-8f33-a9b218b1fcb3
---
#dotnet-build

# dotnet-build

## Name

`dotnet-build` - Builds a project and all of its dependencies.

## Synopsis

```
dotnet build [project] [-o|--output] [-f|--framework] [-c|--configuration] [-r|--runtime] [--version-suffix] [--no-incremental] [--no-dependencies] [-v|--verbosity]
dotnet build [--help]
```
`dotnet build [<PROJECT>] [-o|--output] [-f|--framework] [-c|--configuration] [-r|--runtime] [--version-suffix] [--no-incremental] [--no-dependencies] [-v|--verbosity] [-h|--help]`

## Description
The `dotnet build` command builds the project and its dependencies into a set of binaries. The binaries are the symbol files used for debugging (having a `*.pdb` extension) as well as the project's code in Intermediate Language (IL) with a `*.dll` extension. Additionally, a JSON file that lists out the dependencies of the application with the `*.deps.json` extension will be produced. Finally, a `runtime.config.json` file will be produced as well. This file specifies which shared runtime and version the built code will run against.

If the project has third-party dependencies, such as libraries from NuGet, these will be resolved from the NuGet cache and will not be available with the project's built output. With that in mind, the product of `dotnet build` is not ready to be transferred to another machine to run. This is in contrast to the behavior of .NET Framework in which building an executable project (an application) will produce an output that is possible to run on any machine that has .NET Framework installed. In order to get a similar experience in .NET Core, you have to use the [dotnet publish](dotnet-publish.md) command. More information about this can be found in the [.NET Core Application Deployment](../deploying/index.md) document.
The `dotnet build` command builds the project and its dependencies into a set of binaries. The binaries include the project's code in Intermediate Language (IL) files with a *.dll* extension and symbol files used for debugging with a *.pdb* extension. A dependencies JSON file (*\*.deps.json*) is produced that lists the dependencies of the application. A *\*.runtimeconfig.json* file is produced, which specifies the shared runtime and its version for the application.

Building requires the existence of an *assets.json* file (a file that lists all of the dependencies of your application), which means that you have to run [`dotnet restore`](dotnet-restore.md) prior to building the project. Lack of the assets file manifests as the inability of the tooling to resolve reference assemblies which will result in errors.
If the project has third-party dependencies, such as libraries from NuGet, they're resolved from the NuGet cache and aren't available with the project's built output. With that in mind, the product of `dotnet build` isn't ready to be transferred to another machine to run. This is in contrast to the behavior of the .NET Framework in which building an executable project (an application) produces output that's runnable on any machine where the .NET Framework is installed. To have a similar experience with .NET Core, you use the [dotnet publish](dotnet-publish.md) command. For more information, see [.NET Core Application Deployment](../deploying/index.md).

`dotnet build` uses MSBuild to build the project, thus it supports both parallel builds and incremental builds. Please refer to [MSBuild documentation](https://docs.microsoft.com/visualstudio/msbuild/msbuild) to get more information on those topics.
Building requires the *project.assets.json* file, which lists the dependencies of your application. The file is created when you execute [`dotnet restore`](dotnet-restore.md) before building the project. Without the assets file in place, the tooling cannot resolve reference assemblies, which will result in errors.

In addition to its options, the `dotnet build` command will accept MSBuild options as well, such as `/p` for setting properties or `/l` to define a logger. You can find out more about these options in the [`dotnet msbuild`](dotnet-msbuild.md) command documentation.
`dotnet build` uses MSBuild to build the project; thus, it supports both parallel and incremental builds. Refer to [Incremental Builds](https://docs.microsoft.com/visualstudio/msbuild/incremental-builds) for more information.

Whether the project is executable or not is determined by the `<OutputType>` property in the project file. The following example shows a project that will produce executable code:
In addition to its options, the `dotnet build` command accepts MSBuild options, such as `/p` for setting properties or `/l` to define a logger. Learn more about these options in the [MSBuild Command-Line Reference](https://docs.microsoft.com/visualstudio/msbuild/msbuild-command-line-reference).

Whether the project is executable or not is determined by the `<OutputType>` property in the project file. The following example shows a project that will produce executable code:

```xml
<PropertyGroup>
<OutputType>Exe</OutputType>
</PropertyGroup>
```

In order to produce a library, simply omit that property. The main difference in output is that the IL DLL for a library will not contain any entry points and it will not be possible to execute it.
In order to produce a library, omit the `<OutputType>` property. The main difference in built output is that the IL DLL for a library doesn't contain entry points and can't be executed.

## Arguments

`project`
`PROJECT`

The project file to build.
If a project file is not specified, MSBuild searches the current working directory for a file that has a file extension that ends in `proj` and uses that file.
The project file to build. If a project file is not specified, MSBuild searches the current working directory for a file that has a file extension that ends in *proj* and uses that file.

## Options

Expand All @@ -65,29 +62,29 @@ Directory in which to place the built binaries. You also need to define `--frame

`-f|--framework <FRAMEWORK>`

Compiles for a specific framework. The framework needs to be defined in the [project file](csproj.md).
Compiles for a specific [framework](../../standard/frameworks.md). The framework must be defined in the [project file](csproj.md).

`-c|--configuration [Debug|Release]`
`-c|--configuration <CONFIGURATION>`

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

`-r|--runtime [RUNTIME_IDENTIFIER]`
`-r|--runtime <RUNTIME_IDENTIFIER>`

Target runtime to build for. For a list of Runtime Identifiers (RIDs) you can use, see the [RID catalog](../rid-catalog.md).
Specifies the target runtime. For a list of Runtime Identifiers (RIDs), 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 file. The format follows NuGet's version guidelines.
Defines the version suffix for an asterisk (`*`) in the version field of the project file. The format follows NuGet's version guidelines.

`--no-incremental`

Marks the build as unsafe for incremental build. This turns off incremental compilation and forces a clean rebuild of the project dependency graph.
Marks the build as unsafe for incremental build. This turns off incremental compilation and forces a clean rebuild of the project's dependency graph.

`--no-dependencies`

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

`-v|--verbosity`
`-v|--verbosity <LEVEL>`

Sets the verbosity level of the command. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`.

Expand Down
32 changes: 18 additions & 14 deletions docs/core/tools/dotnet-clean.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,51 +4,55 @@ description: The dotnet-clean command cleans the current directory.
keywords: dotnet-clean, CLI, CLI command, .NET Core
author: blackdwarf
ms.author: mairaw
ms.date: 03/06/2017
ms.date: 03/15/2017
ms.topic: article
ms.prod: .net-core
ms.technology: dotnet-cli
ms.devlang: dotnet
ms.assetid: eff65fa1-bab4-4421-8260-d0a284b690b2
---
#dotnet-clean

# dotnet-clean

## Name

`dotnet-clean` - Cleans the output of a project.

## Synopsis

```
dotnet clean [project] [-o|--output] [-f|--framework] [-c|--configuration] [-v|--verbosity]
dotnet clean [--help]
```
`dotnet clean [<PROJECT>] [-o|--output] [-f|--framework] [-c|--configuration] [-v|--verbosity] [-h|--help]`

## Description

The `dotnet clean` command will clean the output of the previous build. It is implemented as an MSBuild target, so the project will get evaluated. Only the outputs that were created during the build are cleaned. Both intermediate (`obj`) and final output (`bin`) folders are cleaned.
The `dotnet clean` command cleans the output of the previous build. It's implemented as an [MSBuild target](https://docs.microsoft.com/visualstudio/msbuild/msbuild-targets), so the project is evaluated when the command is run. Only the outputs created during the build are cleaned. Both intermediate (*obj*) and final output (*bin*) folders are cleaned.

## Arguments

`PROJECT`

The MSBuild project to clean. If a project file is not specified, MSBuild searches the current working directory for a file that has a file extension that ends in *proj* and uses that file.

## Options

`-h|--help`

Prints out a short help for the command.
Prints out a short help for the command.

`-o|--output <OUTPUT_DIRECTORY>`

Directory in which the built binaries were placed. You also need to define `--framework` when you specify this option. If you didn't specify this property during build time, you don't have to specify it for clean.
Directory in which the build outputs are placed. Specify the `-f|--framework <FRAMEWORK>` switch with the output directory switch if you specified the framework when the project was built.

`-f|--framework <FRAMEWORK>`

The framework that was specified at build time. If you didn't specify this property during build time, you don't have to specify it for clean. The framework needs to be defined in the [project file](csproj.md).
The [framework](../../standard/frameworks.md) that was specified at build time. The framework must be defined in the [project file](csproj.md). If you specified the framework at build time, you must specify the framework when cleaning.

`-c|--configuration [Debug|Release]`
`-c|--configuration <CONFIGURATION>`

Defines a configuration under which the build was running. If omitted, it defaults to `Debug`. If you didn't specify this property during build time, you don't have to specify it for clean.
Defines the configuration. If omitted, it defaults to `Debug`. This property is only required when cleaning if you specified it during build time.

`-v|--verbosity <Quiet|Minimal|Normal|Diag>`
`-v|--verbosity <LEVEL>`

Defines verbosity to use for the invocation of the `dotnet clean` command. The verbosity levels are standard [MSBuild verbosity levels](https://docs.microsoft.com/visualstudio/msbuild/msbuild-command-line-reference).
Sets the verbosity level of the command. Allowed levels are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

## Examples

Expand Down
Loading