Skip to content

Commit 1a84c69

Browse files
author
Zlatko Knezevic
authored
CLI Preview 3 docs (#1233)
Add CLI Preview 3 documentation This will add Preview 3 CLI documentation in a separate folder under docs/core/preview3. The CLI Preview 3 bits are the first released bits to contain the MSbuild support and have no support for working with project.json projects. Changes done: * Modified the extensiblity document to add extending the tools via targets in NuGet packages * Added dependency management documetn that explains how to do package management manually in the new csproj format * Added csproj reference guide (NOTE: this needs completing) * Added dotnet-migrate command docs * Fixed all of the other command references to be correct as to Preview 3 bits
1 parent 3ea9ca4 commit 1a84c69

29 files changed

+2434
-8
lines changed

‎docs/cli-preview3/contributing.md‎ renamed to ‎docs/core/preview3/contributing.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Using the cli-preview3 folder and sub-folders
22

3-
This folder is the top-level node that matches the [docs](../welcome.md)
3+
This folder is the top-level node that matches the tools
44
folder, but contains deltas for the .NET Core tooling Preview 3 release.
55

66
The goal of this separate parallel folder structure is to provide a location
@@ -28,7 +28,7 @@ top of the topic:
2828
We've created a snippet to include with the following syntax:
2929

3030
```markdown
31-
[!include[current release track](../includes/warning.md)]
31+
[!include[current release track](../../includes/warning.md)]
3232
```
3333

3434
### Link instructions
@@ -49,4 +49,4 @@ When the time comes, we can merge each current release into the main
4949
[docs](../docs) folder, merge the TOC nodes, and publish as a separate doc
5050
set. We may need to merge modifications to both the LTS version of a file
5151
and the current release of a file, but we should be able to find those
52-
changes relatively easily.
52+
changes relatively easily.

‎docs/core/preview3/deploying/index.md‎

Lines changed: 417 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/core/preview3/tools/csproj.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: csproj reference | .NET Core SDK
3+
description: Learn about the differences between existing and .NET Core csproj files
4+
keywords: reference, csproj, .NET Core
5+
author: blackdwarf
6+
ms.author: mairaw
7+
manager: wpickett
8+
ms.date: 10/12/2016
9+
ms.topic: article
10+
ms.prod: .net-core
11+
ms.technology: .net-core-technologies
12+
ms.devlang: dotnet
13+
ms.assetid: bdc29497-64f2-4d11-a21b-4097e0bdf5c9
14+
---
15+
16+
Additions to csproj format for .NET Core
17+
----------------------------------------
18+
19+
# Overview
20+
This document outlines the changes that were added to the csproj files as part of the move from project.json to csproj and
21+
[MSBuild](https://github.com/Microsoft/MSBuild). This document outlines **only the deltas to non-core csproj files**. If
22+
you need more information about general project file syntax and reference, please consult [the MSBuild project file]() documentation.
23+
24+
> **Note:** this document will grow in the future, so please check back to see new additions.
25+
26+
# Additions
27+
28+
## PackageReference
29+
Specifies a NuGet dependency in the project. The `Include` attribute specifies the package ID.
30+
31+
```xml
32+
<PackageReference Include="<package-id>">
33+
<Version></Version>
34+
<PrivateAssets></PrivateAssets>
35+
<IncludeAssets></IncludeAssets>
36+
<ExcludeAssets></ExcludeAssets>
37+
</PackageReference>
38+
```
39+
40+
### Version
41+
`<Version>` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme.
42+
43+
### IncludeAssets
44+
`<IncludeAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should be
45+
consumed.
46+
47+
The element can contain one or more of the following values:
48+
49+
* Compile – are the contents of the lib folder available to compile against
50+
* Runtime – are the contents of the runtime folder distributed
51+
* ContentFiles – are the contents of the contentfiles folder used
52+
* Build – do the props/targets in the build folder get used
53+
* Native - are the contents from native assets copied to the output folder for runtime
54+
* Analyzers – do the analyzers get used
55+
56+
Alternatively, the element can contain:
57+
58+
* None – none of those things get used
59+
* All – all of those things get used.
60+
61+
### ExcludeAssets
62+
`<ExcluseAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should not
63+
be consumed.
64+
65+
The element can contain one or more of the following values:
66+
67+
* Compile – are the contents of the lib folder available to compile against
68+
* Runtime – are the contents of the runtime folder distributed
69+
* ContentFiles – are the contents of the contentfiles folder used
70+
* Build – do the props/targets in the build folder get used
71+
* Native - are the contents from native assets copied to the output folder for runtime
72+
* Analyzers – do the analyzers get used
73+
74+
Alternatively, the element can contain:
75+
76+
* None – none of those things get used
77+
* All – all of those things get used.
78+
79+
### PrivateAssets
80+
`<PrivateAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should be
81+
consumed but that they should not flow to the next project.
82+
83+
> **Note:** this is a new term for project.json/xproj `SupressParent` element.
84+
85+
The element can contain one or more of the following values:
86+
87+
* Compile – are the contents of the lib folder available to compile against
88+
* Runtime – are the contents of the runtime folder distributed
89+
* ContentFiles – are the contents of the contentfiles folder used
90+
* Build – do the props/targets in the build folder get used
91+
* Native - are the contents from native assets copied to the output folder for runtime
92+
* Analyzers – do the analyzers get used
93+
94+
Alternatively, the element can contain:
95+
96+
* None – none of those things get used
97+
* All – all of those things get used.
98+
99+
## DotnetCliToolReference
100+
`<DotnetCliToolReference>` element specifies the CLI tool that the user wants restores in the context of the project. It is
101+
a replacement for the `tools` node in `project.json`.
102+
103+
### Version
104+
`<Version>` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme.
105+
106+
## RuntimeIdentifiers
107+
`<RuntimeIdentifiers>` element allows specifying a semicolon-delimited list of [Runtime Identifiers](../../rid-catalog.md) for the project.
108+
These allow publishing self-contained deployments.
109+

‎docs/core/preview3/tools/dependencies.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Managing dependencies in .NET Core Preview 3 tooling
3+
description: Preview 3 brings about changes to how dependencies are managed
4+
keywords: CLI, extensibility, custom commands, .NET Core
5+
author: blackdwarf
6+
manager: wpickett
7+
ms.date: 11/12/2016
8+
ms.topic: article
9+
ms.prod: .net-core
10+
ms.technology: .net-core-technologies
11+
ms.devlang: dotnet
12+
ms.assetid: 74b87cdb-a244-4c13-908c-539118bfeef9
13+
---
14+
15+
Managing dependencies in .NET Core Preview 3 tooling
16+
----------------------------------------------------
17+
18+
# Overview
19+
With the move of .NET Core projects from project.json to csproj and MSBuild, a significant invesment also happened that resulted in unification of the project file and assets that allow tracking of depenencies. For .NET Core projects this is similar to what project.json did. There is no separate JSON or XML file that tracks NuGet dependencies. With this change, we've also introduced another type of *reference* into the csproj syntax called the `<PackageReference>`.
20+
21+
This document describes the new reference type. It also shows how to add a package dependency using this new reference type to your project.
22+
23+
# The new <PackageReference> element
24+
The `<PackageReference>` has the following basic structure:
25+
26+
```xml
27+
<PackageReference Include="<Package_ID>">
28+
<Version>PACKAGE_VERSION</Version>
29+
</PackageReference>
30+
```
31+
32+
If you are familiar with MSBuild, it will look familiar to the other [reference types]() that already exist. The key is the `Include` statement which specifies the package id that you wish to add to the project. The `<Version>` child element specified the version to get. The versions are specified as per [NuGet version rules](https://docs.nuget.org/ndocs/create-packages/dependency-versions#version-ranges).
33+
34+
> **Note:** if you are not faimilar with the overall `csproj` syntax, you can use the [MSBuild project reference documentation]() to get acquainted.
35+
36+
Adding a dependency that is available only in a specific target is done using conditions:
37+
38+
```xml
39+
<PackageReference Include="<Package_ID>" Condition="'$(TargetFramework)' == 'netcoreapp1.0'">
40+
<Version>PACKAGE_VERSION</Version>
41+
</PackageReference>
42+
```
43+
44+
The above means that the dependency will only be valid if the build is happening for that given target. The `$(TargetFramework)` in the condition is a MSBuild property that is being set in the project. For most common .NET Core applications, you will not need to do this.
45+
46+
# Adding a dependency to your project
47+
Adding a dependency to your project is straightforward. Here is an example of how to add `JSON.net` version `9.0.1` to your project. Of course, it is applicable to any other NuGet dependency.
48+
49+
When you open your project file, you will see two or more `<ItemGroup>` nodes. You will notice that one of the nodes already has `<PackageReference>` elements in it. You can add your new dependency to this node, or create a new one; it is completely up to you as the result will be the same.
50+
51+
In this example we will use the default template that is dropped by `dotnet new`. This is a simple console application. When we open up the project, we first find the `<ItemGroup>` with already existing `<PackageReference>` in it. We then add the following to it:
52+
53+
```xml
54+
<PackageReference Include="Newtonsoft.Json">
55+
<Version>9.0.1</Version>
56+
</PackageReference>
57+
```
58+
After this, we save the project and run the `dotnet restore` command to install the dependency.
59+
60+
The full project looks like this:
61+
62+
```xml
63+
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
64+
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
65+
66+
<PropertyGroup>
67+
<OutputType>Exe</OutputType>
68+
<TargetFramework>netcoreapp1.0</TargetFramework>
69+
</PropertyGroup>
70+
71+
<ItemGroup>
72+
<Compile Include="**\*.cs" />
73+
<EmbeddedResource Include="**\*.resx" />
74+
</ItemGroup>
75+
76+
<ItemGroup>
77+
<PackageReference Include="Microsoft.NETCore.App">
78+
<Version>1.0.1</Version>
79+
</PackageReference>
80+
<PackageReference Include="Newtonsoft.Json">
81+
<Version>9.0.1</Version>
82+
</PackageReference>
83+
<PackageReference Include="Microsoft.NET.Sdk">
84+
<Version>1.0.0-alpha-20161104-2</Version>
85+
<PrivateAssets>All</PrivateAssets>
86+
</PackageReference>
87+
</ItemGroup>
88+
89+
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
90+
</Project>
91+
```
92+
93+
# Removing a dependency from the project
94+
Removing a dependency from the project file involves simply removing the `<PackageReference>` from the project file.
95+
96+

‎docs/core/preview3/tools/dotnet-build.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: dotnet-build command | .NET Core SDK
3+
description: The dotnet-build command builds a project and all of its dependencies.
4+
keywords: dotnet-build, CLI, CLI command, .NET Core
5+
author: mairaw
6+
manager: wpickett
7+
ms.date: 10/13/2016
8+
ms.topic: article
9+
ms.prod: .net-core
10+
ms.technology: .net-core-technologies
11+
ms.devlang: dotnet
12+
ms.assetid: 70285a83-4103-4617-be8b-d0e1e9a4a91d
13+
---
14+
15+
#dotnet-build
16+
17+
## Name
18+
dotnet-build -- Builds a project and all of its dependencies
19+
20+
## Synopsis
21+
22+
`dotnet build [--help] [--output] [--framework]
23+
[--configuration] [--runtime] [--version-suffix]
24+
[--build-profile] [--no-incremental] [--no-dependencies]
25+
[<project>]`
26+
27+
## Description
28+
29+
The `dotnet build` command builds multiple source file from a source project and its dependencies into a binary.
30+
By default, the resulting binary is in Intermediate Language (IL) and has a DLL extension.
31+
`dotnet build` also drops a `\*.deps` file which outlines what the host needs to run the application.
32+
33+
Building requires the existence of an asset file (a file that lists all of the dependencies of your application), which
34+
means that you have to run [`dotnet restore`](dotnet-restore.md) prior to building your code.
35+
36+
Before any compilation begins, the `build` verb analyzes the project and its dependencies for incremental safety checks.
37+
If all checks pass, then build proceeds with incremental compilation of the project and its dependencies;
38+
otherwise, it falls back to non-incremental compilation. Via a profile flag, users can choose to receive additional
39+
information on how they can improve their build times.
40+
41+
In order to build an executable application instead of a library, you need to set the `<OutputType>` property:
42+
43+
```xml
44+
<PropertyGroup>
45+
<OutputType>Exe</OutputType>
46+
</PropertyGroup>
47+
```
48+
49+
## Options
50+
51+
`-h|--help`
52+
53+
Prints out a short help for the command.
54+
55+
`-o|--output <OUTPUT_DIRECTORY>`
56+
57+
Directory in which to place the built binaries. You also need to define `--framework` when you specify this option.
58+
59+
`-f|--framework <FRAMEWORK>`
60+
61+
Compiles for a specific framework. The framework needs to be defined in the [project file](csproj.md).
62+
63+
`-c|--configuration [Debug|Release]`
64+
65+
Defines a configuration under which to build. If omitted, it defaults to `Debug`.
66+
67+
`-r|--runtime [RUNTIME_IDENTIFIER]`
68+
69+
Target runtime to build for. For a list of Runtime Identifiers (RIDs) you can use, see the [RID catalog](../../rid-catalog.md).
70+
71+
`--version-suffix [VERSION_SUFFIX]`
72+
73+
Defines what `*` should be replaced with in the version field in the project file. The format follows NuGet's version guidelines.
74+
75+
`--build-profile`
76+
77+
Prints out the incremental safety checks that users need to address in order for incremental compilation to be automatically turned on.
78+
79+
`--no-incremental`
80+
81+
Marks the build as unsafe for incremental build. This turns off incremental compilation and forces a clean rebuild of the project dependency graph.
82+
83+
`--no-dependencies`
84+
85+
Ignores project-to-project references and only builds the root project specified to build.
86+
87+
## Examples
88+
89+
Build a project and its dependencies:
90+
91+
`dotnet build`
92+
93+
Build a project and its dependencies using Release configuration:
94+
95+
`dotnet build --configuration Release`
96+
97+
Build a project and its dependencies for a specific runtime (in this example, Ubuntu 16.04):
98+
99+
`dotnet build --runtime ubuntu.16.04-x64`

0 commit comments

Comments
 (0)