Merge remote-tracking branch 'origin/master' into core-golden-path

smwentum · Nov 16, 2016 · 4635d84 · 4635d84
2 parents 2b2bbaf + 1a84c69
commit 4635d84
Show file tree

Hide file tree

Showing 31 changed files with 2,465 additions and 23 deletions.
diff --git a/docs/cli-preview3/contributing.md → docs/core/preview3/contributing.md b/docs/cli-preview3/contributing.md → docs/core/preview3/contributing.md
@@ -1,6 +1,6 @@
 # Using the cli-preview3 folder and sub-folders
 
-This folder is the top-level node that matches the [docs](../welcome.md)
+This folder is the top-level node that matches the tools
 folder, but contains deltas for the .NET Core tooling Preview 3 release.
 
 The goal of this separate parallel folder structure is to provide a location
@@ -28,7 +28,7 @@ top of the topic:
 We've created a snippet to include with the following syntax:
 
 ```markdown
-[!include[current release track](../includes/warning.md)]
+[!include[current release track](../../includes/warning.md)]
 ```
 
 ### Link instructions
@@ -49,4 +49,4 @@ When the time comes, we can merge each current release into the main
 [docs](../docs) folder, merge the TOC nodes, and publish as a separate doc
 set. We may need to merge modifications to both the LTS version of a file
 and the current release of a file, but we should be able to find those
-changes relatively easily.
+changes relatively easily.
diff --git a/docs/core/preview3/deploying/index.md b/docs/core/preview3/deploying/index.md
diff --git a/docs/core/preview3/tools/csproj.md b/docs/core/preview3/tools/csproj.md
@@ -0,0 +1,109 @@
+---
+title: csproj reference | .NET Core SDK
+description: Learn about the differences between existing and .NET Core csproj files
+keywords: reference, csproj, .NET Core
+author: blackdwarf
+ms.author: mairaw
+manager: wpickett
+ms.date: 10/12/2016
+ms.topic: article
+ms.prod: .net-core
+ms.technology: .net-core-technologies
+ms.devlang: dotnet
+ms.assetid: bdc29497-64f2-4d11-a21b-4097e0bdf5c9
+---
+
+Additions to csproj format for .NET Core
+----------------------------------------
+
+# Overview 
+This document outlines the changes that were added to the csproj files as part of the move from project.json to csproj and 
+[MSBuild](https://github.com/Microsoft/MSBuild). This document outlines **only the deltas to non-core csproj files**. If 
+you need more information about general project file syntax and reference, please consult [the MSBuild project file]() documentation. 
+
+> **Note:** this document will grow in the future, so please check back to see new additions. 
+
+# Additions
+
+## PackageReference
+Specifies a NuGet dependency in the project. The `Include` attribute specifies the package ID. 
+
+```xml
+<PackageReference Include="<package-id>">
+    <Version></Version>
+    <PrivateAssets></PrivateAssets>
+    <IncludeAssets></IncludeAssets>
+    <ExcludeAssets></ExcludeAssets>
+</PackageReference>
+```
+
+### Version
+`<Version>` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme.
+
+### IncludeAssets
+`<IncludeAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should be 
+consumed. 
+
+The element can contain one or more of the following values:
+
+* Compile – are the contents of the lib folder available to compile against
+* Runtime – are the contents of the runtime folder distributed
+* ContentFiles – are the contents of the contentfiles folder used
+* Build – do the props/targets in the build folder get used
+* Native - are the contents from native assets copied to the output folder for runtime
+* Analyzers – do the analyzers get used
+
+Alternatively, the element can contain:
+
+* None – none of those things get used
+* All – all of those things get used.
+
+### ExcludeAssets
+`<ExcluseAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should not 
+be consumed.
+
+The element can contain one or more of the following values:
+
+* Compile – are the contents of the lib folder available to compile against
+* Runtime – are the contents of the runtime folder distributed
+* ContentFiles – are the contents of the contentfiles folder used
+* Build – do the props/targets in the build folder get used
+* Native - are the contents from native assets copied to the output folder for runtime
+* Analyzers – do the analyzers get used
+
+Alternatively, the element can contain:
+
+* None – none of those things get used
+* All – all of those things get used.
+
+### PrivateAssets
+`<PrivateAssets>` child element specifies what assets belonging to the package specified by parent `<PackageReference>` should be 
+consumed but that they should not flow to the next project. 
+
+> **Note:** this is a new term for project.json/xproj `SupressParent` element. 
+
+The element can contain one or more of the following values:
+
+* Compile – are the contents of the lib folder available to compile against
+* Runtime – are the contents of the runtime folder distributed
+* ContentFiles – are the contents of the contentfiles folder used
+* Build – do the props/targets in the build folder get used
+* Native - are the contents from native assets copied to the output folder for runtime
+* Analyzers – do the analyzers get used
+
+Alternatively, the element can contain:
+
+* None – none of those things get used
+* All – all of those things get used.
+
+## DotnetCliToolReference
+`<DotnetCliToolReference>` element specifies the CLI tool that the user wants restores in the context of the project. It is 
+a replacement for the `tools` node in `project.json`. 
+
+### Version
+`<Version>` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme.
+
+## RuntimeIdentifiers
+`<RuntimeIdentifiers>` element allows specifying a semicolon-delimited list of [Runtime Identifiers](../../rid-catalog.md) for the project. 
+These allow publishing self-contained deployments. 
+
diff --git a/docs/core/preview3/tools/dependencies.md b/docs/core/preview3/tools/dependencies.md
@@ -0,0 +1,96 @@
+---
+title: Managing dependencies in .NET Core Preview 3 tooling
+description: Preview 3 brings about changes to how dependencies are managed
+keywords: CLI, extensibility, custom commands, .NET Core
+author: blackdwarf
+manager: wpickett
+ms.date: 11/12/2016
+ms.topic: article
+ms.prod: .net-core
+ms.technology: .net-core-technologies
+ms.devlang: dotnet
+ms.assetid: 74b87cdb-a244-4c13-908c-539118bfeef9
+---
+
+Managing dependencies in .NET Core Preview 3 tooling
+----------------------------------------------------
+
+# Overview
+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>`. 
+
+This document describes the new reference type. It also shows how to add a package dependency using this new reference type to your project. 
+
+# The new <PackageReference> element
+The `<PackageReference>` has the following basic structure:
+
+```xml
+<PackageReference Include="<Package_ID>">
+    <Version>PACKAGE_VERSION</Version>
+</PackageReference>
+```
+
+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).  
+
+> **Note:** if you are not faimilar with the overall `csproj` syntax, you can use the [MSBuild project reference documentation]() to get acquainted.  
+
+Adding a dependency that is available only in a specific target is done using conditions:
+
+```xml
+<PackageReference Include="<Package_ID>" Condition="'$(TargetFramework)' == 'netcoreapp1.0'">
+    <Version>PACKAGE_VERSION</Version>
+</PackageReference>
+```
+
+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. 
+
+# Adding a dependency to your project
+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. 
+
+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. 
+
+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:
+
+```xml
+<PackageReference Include="Newtonsoft.Json">
+    <Version>9.0.1</Version>
+</PackageReference>
+```
+After this, we save the project and run the `dotnet restore` command to install the dependency. 
+
+The full project looks like this:
+
+```xml
+<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp1.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="**\*.cs" />
+    <EmbeddedResource Include="**\*.resx" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NETCore.App">
+      <Version>1.0.1</Version>
+    </PackageReference>
+    <PackageReference Include="Newtonsoft.Json">
+        <Version>9.0.1</Version>
+    </PackageReference>
+    <PackageReference Include="Microsoft.NET.Sdk">
+      <Version>1.0.0-alpha-20161104-2</Version>
+      <PrivateAssets>All</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+</Project>
+```
+
+# Removing a dependency from the project
+Removing a dependency from the project file involves simply removing the `<PackageReference>` from the project file. 
+
+
diff --git a/docs/core/preview3/tools/dotnet-build.md b/docs/core/preview3/tools/dotnet-build.md
@@ -0,0 +1,99 @@
+---
+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: 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
+
+## Name 
+dotnet-build -- Builds a project and all of its dependencies 
+
+## Synopsis
+
+`dotnet build [--help] [--output]  [--framework]  
+    [--configuration]  [--runtime] [--version-suffix]
+    [--build-profile]  [--no-incremental] [--no-dependencies]
+    [<project>]`
+
+## 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. 
+`dotnet build` also drops a `\*.deps` file which outlines what the host needs to run the application.  
+
+Building requires the existence of an asset 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 your code.
+
+Before any compilation begins, the `build` verb analyzes the project and its dependencies for incremental safety checks.
+If all checks pass, then build proceeds with incremental compilation of the project and its dependencies; 
+otherwise, it falls back to non-incremental compilation. Via a profile flag, users can choose to receive additional 
+information on how they can improve their build times.
+
+In order to build an executable application instead of a library, you need to set the `<OutputType>` property:
+
+```xml
+<PropertyGroup>
+    <OutputType>Exe</OutputType>
+</PropertyGroup>
+```
+
+## Options
+
+`-h|--help`
+
+Prints out a short help for the command.  
+
+`-o|--output <OUTPUT_DIRECTORY>`
+
+Directory in which to place the built binaries. You also need to define `--framework` when you specify this option.
+
+`-f|--framework <FRAMEWORK>`
+
+Compiles for a specific framework. The framework needs to be defined in the [project file](csproj.md).
+
+`-c|--configuration [Debug|Release]`
+
+Defines a configuration under which to build.  If omitted, it defaults to `Debug`.
+
+`-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). 
+
+`--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. 
+
+`--build-profile`
+
+Prints out the incremental safety checks that users need to address in order for incremental compilation to be automatically turned on.
+
+`--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.
+
+`--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`