diff --git a/docs/cli-preview3/contributing.md b/docs/core/preview3/contributing.md similarity index 92% rename from docs/cli-preview3/contributing.md rename to docs/core/preview3/contributing.md index 5da06a83ee582..78fd5abff7dc1 100644 --- a/docs/cli-preview3/contributing.md +++ b/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. \ No newline at end of file +changes relatively easily. diff --git a/docs/core/preview3/deploying/index.md b/docs/core/preview3/deploying/index.md new file mode 100644 index 0000000000000..cfa88eb1d43c5 --- /dev/null +++ b/docs/core/preview3/deploying/index.md @@ -0,0 +1,417 @@ +--- +title: .NET Core Application Deployment +description: .NET Core Application Deployment +keywords: .NET, .NET Core, .NET Core deployment +author: rpetrusha +manager: wpickett +ms.date: 11/13/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: da7a31a0-8072-4f23-82aa-8a19184cb701 +--- + +# .NET Core Application Deployment # + +You can create two types of deployments for .NET Core applications: + +- Framework-dependent deployment. As the name implies, framework-dependent deployment (FDD) relies on a shared system-wide version of .NET Core to be present on the target system. Because .NET Core is already present, your app is also portable between installations of .NET Core. Your app contains only its own code and any third-party dependencies that are outside of the .NET Core libraries. FDDs contain .dll files that can be launched by using the [dotnet utility](../tools/dotnet.md) from the command line. For example, `dotnet app.dll` runs an application named `app`. + +- Self-contained deployment. Unlike FDD, a self-contained deployment (SCD) does not rely on any shared components to be present on the target system. All components, including both .NET Core libraries and the .NET Core runtime, are included with the application and are isolated from other .NET Core applications. SCDs include an executable (such as `app.exe` on Windows platforms for an application named `app`), which is a renamed version of the platform-specific .NET Core host, and a .dll file (such as `app.dll`), which is the actual application. + +## Framework-dependent deployments (FDD) ## + +For an FDD, you deploy only your app and any third-party dependencies. You do not have to deploy .NET Core, since your app will use the version of .NET Core that's present on the target system. This is the default deployment model for .NET Core apps. + +### Why create a framework-dependent deployment? ### + +Deploying an FDD has a number of advantages: + +- You do not have to define the target operating systems that your .NET Core app will run on in advance. Because .NET Core uses a common PE file format for executables and libraries regardless of operating system, .NET Core can execute your app regardless of the underlying operating system. For more information on the PE file format, see [.NET Assembly File Format](../../../standard/assembly-format.md). + +- The size of your deployment package is small. You only have to deploy your app and its dependencies, not .NET Core itself. + +- Multiple apps use the same .NET Core installation, which reduces both disk space and memory usage on host systems. + +There are also a few disadvantages: + +- Your app can run only if the version of .NET Core that you target, or a later version, is already installed on the host system. + +- It is possible for the .NET Core runtime and libraries to change without your knowledge in future releases. In rare cases, this may change the behavior of your app. + +### Deploying a framework-dependent deployment ### + +Deploying a framework-dependent deployment with no third-party dependencies simply involves building, testing, and publishing the app. A simple example written in C# illustrates the process. The example uses the [dotnet utility](../tools/dotnet.md) from the command line; however, you can also use a development environment, such as Visual Studio or Visual Studio Code, to compile, test, and publish the example. + +1. Create a directory for your project, and from the command line, type [dotnet new](../tools/dotnet-new.md) to create a new C# console project. + +2. Open the `Program.cs` file in an editor, and replace the auto-generated code with the following code. It prompts the user to enter text, and then displays the individual words entered by the user. It uses the regular expression `\w+` to separate the words in the input text. + + ```cs + using System; + using System.Text.RegularExpressions; + + namespace Applications.ConsoleApps + { + public class ConsoleParser + { + public static void Main() + { + Console.WriteLine("Enter any text, followed by :\n"); + String s = Console.ReadLine(); + ShowWords(s); + Console.Write("\nPress any key to continue... "); + Console.ReadKey(); + } + + private static void ShowWords(String s) + { + String pattern = @"\w+"; + var matches = Regex.Matches(s, pattern); + if (matches.Count == 0) + Console.WriteLine("\nNo words were identified in your input."); + else + { + Console.WriteLine("\nThere are {0} words in your string:", matches.Count); + for (int ctr = 0; ctr < matches.Count; ctr++) + Console.WriteLine(" #{0,2}: '{1}' at position {2}", ctr, + matches[ctr].Value, matches[ctr].Index); + } + } + } + } + ``` + +3. Run the [dotnet restore](../tools/dotnet-restore.md) command to restore the dependencies specified in your project. + +4. Create a debug build of your app by using the [dotnet build](../tools/dotnet-build.md) command. + +5. After you've debugged and tested the program, you can create the files to be deployed with your app by using the `dotnet publish -f netcoreapp1.0 -c release` command. This creates a release (rather than a debug) version of your app. + + The resulting files are placed in a directory named `publish` that is in a subdirectory of your project's `.\bin\release\netcoreapp1.0` subdirectory. + +6. Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions; you can choose not to package it with your application's files. + +The complete set of application files can be deployed in any way you'd like. For example, you can package them in a zip file, use a simple `copy` command, or deploy them with any installation package of your choice. + +In addition to the application binaries, the installer should also either bundle the shared framework installer or check for it as a prerequisite as part of the application installation. Installation of the shared framework requires Administrator/root access since it is machine-wide. + +### Deploying a framework-dependent deployment with third-party dependencies ### + +Deploying a framework-dependent deployment with one or more third-party dependencies involves three additional steps before you can run the `dotnet restore` command: + +1. Add references to any third-party libraries to the `` section of your `csproj` file. The following `` section shows the `` containing the dependencies in the default project with Json.NET as a third-party library. + + ```xml + + + 1.0.1 + + + 9.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + ``` + +Note that the SDK dependency remains in the above example. This is by design, since this depdendency is required to restore all the needed targets to allow the command line tools to function. + +2. If you haven't already, download the NuGet package containing the third-party dependency. To download the package, execute the `dotnet restore` command after adding the dependency. Because the dependency is resolved out of the local NuGet cache at publish time, it must be available on your system. + +Note that a framework-dependent deployment with third-party dependencies will only be as portable as its third-party dependencies. For example, if a third-party library only supports macOS, the app will not be portable to Windows systems. This can happen if the third-party dependency itself depends on native code. A good example of this is Kestrel server. When an FDD is created for an application with this kind of third-party dependency, the published output will contain a folder for each [Runtime Identifier (RID)](../../rid-catalog.md#what-are-rids) that the native dependency supports (and that exists in its NuGet package). + +## Self-contained deployments (SCD) ## + +For a self-contained deployment, you deploy not only your app and any third-party dependencies, but the version of .NET Core that you build your app with. Creating an SCD does not, however, include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) itself on various platforms (for example, OpenSSL on macOS) so these need to be installed before running the application. + +### Why deploy a Self-contained deployment? ### + +Deploying a Self-contained deployment has two major advantages: + +- You have sole control of the version of .NET Core that is deployed with your app. .NET Core can be serviced only by you. + +- You can be assured that the target system can run your .NET Core app, since you're providing the version of .NET Core that it will run on. + +It also has a number of disadvantages: + +- Because .NET Core is included in your deployment package, you must select the target platforms for which you build deployment packages in advance. + +- The size of your deployment package is relatively large, since you have to include .NET Core as well as your app and its third-party dependencies. + +- Deploying numerous self-contained .NET Core apps to a system can consume significant amounts of disk space, since each app duplicates .NET Core files. + +### Deploying a simple self-contained deployment ### + +Deploying a self-contained deployment with no third-party dependencies involves creating the project, modifying the csproj file, building, testing, and publishing the app. A simple example written in C# illustrates the process. The example uses the `dotnet` utility from the command line; however, you can also use a development environment, such as Visual Studio or Visual Studio Code, to compile, test, and publish the example. + +1. Create a directory for your project, and from the command line, type `dotnet new` to create a new C# console project. + +2. Open the `Program.cs` file in an editor, and replace the auto-generated code with the following code. It prompts the user to enter text, and then displays the individual words entered by the user. It uses the regular expression `\w+` to separate the words in the input text. + + ```cs + using System; + using System.Text.RegularExpressions; + + namespace Applications.ConsoleApps + { + public class ConsoleParser + { + public static void Main() + { + Console.WriteLine("Enter any text, followed by :\n"); + String s = Console.ReadLine(); + ShowWords(s); + Console.Write("\nPress any key to continue... "); + Console.ReadKey(); + } + + private static void ShowWords(String s) + { + String pattern = @"\w+"; + var matches = Regex.Matches(s, pattern); + if (matches.Count == 0) + Console.WriteLine("\nNo words were identified in your input."); + else { + Console.WriteLine("\nThere are {0} words in your string:", matches.Count); + for (int ctr = 0; ctr < matches.Count; ctr++) + Console.WriteLine(" #{0,2}: '{1}' at position {2}", ctr, + matches[ctr].Value, matches[ctr].Index); + } + } + } + } + ``` + +3. Create a `` tag under the `` section in your `csproj` file that defines the platforms your app targets, and specify the runtime identifier of each platform that you target. See [Runtime IDentifier catalog](../../rid-catalog.md) for a list of runtime identifiers. For example, the following `runtimes` section indicates that the app runs on 64-bit Windows 10 operating systems and the 64-bit OS X Version 10.11 operating system. + + ```xml + + win10-x64;osx.10.11-x64 + + ``` +Note that you also need to add a semicolon to separate the RIDs. Also, please note that the `` element can go into any `` that you have in your `csproj` file. A complete sample `csproj` file appears later in this section. + +4. Run the `dotnet restore` command to restore the dependencies specified in your project. + +5. Create debug builds of your app on each of the target platforms by using the `dotnet build` command. Unless you specify the runtime identifier you'd like to build, the `dotnet build` command creates a build only for the current system's runtime ID. You can build your app for both target platforms with the commands: + + ```console + dotnet build -r win10-x64 + dotnet build -r osx.10.11-x64 + ``` +The debug builds of your app for each platform will be found in the project's `.\bin\Debug\netcoreapp1.0\` subdirectory. + +6. After you've debugged and tested the program, you can create the files to be deployed with your app for each platform that it targets by using the `dotnet publish` command for both target platforms as follows: + + ```console + dotnet publish -c release -r win10-x64 + dotnet publish -c release -r osx.10.11-x64 + ``` +This creates a release (rather than a debug) version of your app for each target platform. The resulting files are placed in a subdirectory named `publish` that is in a subdirectory of your project's `.\bin\release\netcoreapp1.0\` subdirectory. Note that each subdirectory contains the complete set of files (both your app files and all .NET Core files) needed to launch your app. + +7. Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions; you can choose not to package it with your application's files. + +The published files can be deployed in any way you'd like. For example, you can package them in a zip file, use a simple `copy` command, or deploy them with any installation package of your choice. + +The following is the complete `csproj` file for this project. + +```xml + + + + Exe + netcoreapp1.0 + 1.0.0 + Portable + win10-x64;osx.10.11-x64 + + + + + + + + 1.0.1 + + + 9.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + + + +``` + + +### Deploying a self-contained deployment with third-party dependencies ### + +Deploying a self-contained deployment with one or more third-party dependencies involves adding the third party dependency: + +1. Add references to any third-party libraries to the `` section of your `csproj` file. The following `` section uses Json.NET as a third-party library. + + ```xml + + + 1.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + 9.0.1 + + + ``` +2. If you haven't already, download the NuGet package containing the third-party dependency to your system. To make the dependency available to your app, execute the `dotnet restore` command after adding the dependency. Because the dependency is resolved out of the local NuGet cache at publish time, it must be available on your system. + +The following is the complete csproj file for this project: + +```xml + + + + Exe + netcoreapp1.0 + 1.0.0 + Portable + win10-x64;osx.10.11-x64 + + + + + + + + 1.0.1 + + + 9.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + + + +``` + +When you deploy your application, any third-party dependencies used in your app are also contained with your application files. Third-party libraries do not already have to be present on the system on which the app is running. + +Note that you can only deploy a self-contained deployment with a third-party library to platforms supported by that library. This is similar to having third-party dependencies with native dependencies in your framework-dependent deployment. + +### Deploying a self-contained deployment with a smaller footprint ### + +If the availability of adequate storage space on target systems is likely to be an issue, you can reduce the overall footprint of your app by excluding some system components. To do this, you explicitly define the .NET Core components that your app includes in your csproj file. + +To create a self-contained deployment with a smaller footprint, start by following the first two steps for creating a self-contained deployment. Once you've run the `dotnet new` command and added the C# source code to your app, do the following: + +1. Open the `csproj` file and replace the `frameworks` section with the following: + + ```xml + + netstandard1.6 + + ``` +This operation indicates that, instead of using the entire `netcoreapp1.0` framework, which includes .NET Core CLR, the .NET Core Library, and a number of other system components, our app uses only the .NET Standard Library. + +2. Replace the `dependencies` section with the following: + + ```xml + + + 1.6.0 + + + 1.0.2 + + + 1.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + ``` + + This defines the system components used by our app. The system components packaged with our app include the .NET Standard Library, the .NET Core runtime, and the .NET Core host. This produces a self-contained deployment with a smaller footprint. + +3. As you did in the [Deploying a simple self-contained deployment](#simpleSelf) example, create a `` element within a `` in your `csproj` file that defines the platforms your app targets and specify the runtime identifier of each platform that you target. See [Runtime IDentifier catalog](../../rid-catalog.md) for a list of runtime identifiers. For example, the following example indicates that the app runs on 64-bit Windows 10 operating systems and the 64-bit OS X Version 10.11 operating system. + + ```xml + + win10-x64;osx.10.11-x64 + + ``` + + +A complete sample `csproj` file appears later in this section. + +4. Run the `dotnet restore` command to restore the dependencies specified in your project. + +5. Create debug builds of your app on each of the target platforms by using the `dotnet build` command. Unless you specify the runtime identifier you'd like to build, the `dotnet build` command creates a build only for the current system's runtime ID. You can build your app for both target platforms with the commands: + + ```console + dotnet build -r win10-x64 + dotnet build -r osx.10.11-x64 + ``` + +6. After you've debugged and tested the program, you can create the files to be deployed with your app for each platform that it targets by using the `dotnet publish` command for both target platforms as follows: + + ```console + dotnet publish -c release -r win10-x64 + dotnet publish -c release -r osx.10.11-x64 + ``` +This creates a release (rather than a debug) version of your app for each target platform. The resulting files are placed in a subdirectory named `publish` that is in a subdirectory of your project's `.\bin\release\netstandard1.6\` subdirectory. Note that each subdirectory contains the complete set of files (both your app files and all .NET Core files) needed to launch your app. + +7. Along with your application's files, the publishing process emits a program database (.pdb) file that contains debugging information about your app. The file is useful primarily for debugging exceptions; you can choose not to package it with your application's files. + +The published files can be deployed in any way you'd like. For example, you can package them in a zip file, use a simple `copy` command, or deploy them with any installation package of your choice. + +The following is the complete `csproj` file for this project. + +```xml + + + + Exe + netcoreapp1.0 + 1.0.0 + Portable + win10-x64;osx.10.11-x64 + + + + + + + + 1.6.0 + + + 1.0.2 + + + 1.0.1 + + + 1.0.0-alpha-20161102-2 + All + + + + + +``` + diff --git a/docs/core/preview3/tools/csproj.md b/docs/core/preview3/tools/csproj.md new file mode 100644 index 0000000000000..f11bb892c32f9 --- /dev/null +++ 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 + + + + + + +``` + +### Version +`` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme. + +### IncludeAssets +`` child element specifies what assets belonging to the package specified by parent `` 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 +`` child element specifies what assets belonging to the package specified by parent `` 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 +`` child element specifies what assets belonging to the package specified by parent `` 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 +`` 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 +`` specifies the version of the package to restore. The element respect the rules of the NuGet versioning scheme. + +## 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 new file mode 100644 index 0000000000000..8f8b5a77c6ccf --- /dev/null +++ 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 ``. + +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 element +The `` has the following basic structure: + +```xml + + PACKAGE_VERSION + +``` + +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 `` 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 + + PACKAGE_VERSION + +``` + +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 `` nodes. You will notice that one of the nodes already has `` 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 `` with already existing `` in it. We then add the following to it: + +```xml + + 9.0.1 + +``` +After this, we save the project and run the `dotnet restore` command to install the dependency. + +The full project looks like this: + +```xml + + + + + Exe + netcoreapp1.0 + + + + + + + + + + 1.0.1 + + + 9.0.1 + + + 1.0.0-alpha-20161104-2 + All + + + + + +``` + +# Removing a dependency from the project +Removing a dependency from the project file involves simply removing the `` from the project file. + + diff --git a/docs/core/preview3/tools/dotnet-build.md b/docs/core/preview3/tools/dotnet-build.md new file mode 100644 index 0000000000000..8242dacedd7f4 --- /dev/null +++ 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] + []` + +## 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 `` property: + +```xml + + Exe + +``` + +## Options + +`-h|--help` + +Prints out a short help for the command. + +`-o|--output ` + +Directory in which to place the built binaries. You also need to define `--framework` when you specify this option. + +`-f|--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` diff --git a/docs/core/preview3/tools/dotnet-install-script.md b/docs/core/preview3/tools/dotnet-install-script.md new file mode 100644 index 0000000000000..dd81e19ee4f24 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-install-script.md @@ -0,0 +1,127 @@ +--- +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: 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: 59b9c456-2bfd-4adc-8202-a1c6a0a6c787 +--- + +#dotnet-install scripts reference + +## Name +dotnet-install.ps1 | dotnet-install.sh - script used to install the Command Line Interface (CLI) tools and the shared runtime + +## Synopsis +Windows: + +`dotnet-install.ps1 [-Channel] [-Version] + [-InstallDir] [-Debug] [-NoPath] + [-SharedRuntime]` + +macOS/Linux: + +`dotnet-install.sh [--channel] [--version] + [--install-dir] [--debug] [--no-path] + [--shared-runtime]` + +## 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. + +Installation scripts will download the ZIP/tarball file from the CLI build drops and will proceed to install it in either the default location or in a location specified by `--install-dir`. By default, the installation script +will download the SDK and install it; if you want to get just the shared runtime, you can specify the `--shared-runtime` argument. + +By default, the script will add the install location to the $PATH for the current session. This can be overridden if the `--no-path` argument is used. + +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](global-json.md) file found in the hierarchy above the folder where the script was invoked that contains the `version` 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. + +## Options +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`. + +`-Version [VERSION]` + +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 `version` 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*. + +`-Debug` + +`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. +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`. + +### 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 (for example, 1.0.0-13232). If omitted, it will default to the first [global.json](global-json.md) that contains the `version` 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`. + +`--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. +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`. + +## Examples + +Install the dev latest version to the default location: + +Windows: + +`./dotnet-install.ps1 -Channel Future` + +macOS/Linux: + +`./dotnet-install.sh --channel Future` + +Install the latest preview to the specified location: + +Windows: + +`./dotnet-install.ps1 -Channel preview -InstallDir C:\cli` + +macOS/Linux: + +`./dotnet-install.sh --channel preview --install-dir ~/cli` diff --git a/docs/core/preview3/tools/dotnet-migrate.md b/docs/core/preview3/tools/dotnet-migrate.md new file mode 100644 index 0000000000000..3f6ab519d83c8 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-migrate.md @@ -0,0 +1,96 @@ +--- +title: dotnet-migrate command | .NET Core SDK +description: The dotnet-migrate command migrates a project and all of its dependencies. +keywords: dotnet-migrate, CLI, CLI command, .NET Core +author: mairaw +manager: wpickett +ms.date: 11/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-migrate + +## Name +dotnet-migrate -- Migrates a Preview 2 .NET Core project to Preview 3 .NET Core project + +## Synopsis + +`dotnet migrate [--help] [--template-file] + [--sdk-package-version] [--xproj-file] + [--skip-project-references] [--report-file] [--format-report-file-json] + [--skip-backup] + []` + +## Description +The `dotnet migrate` command will migrate a valid Preview 2 `project.json` based project to a valid Preview 3 `csproj` project. +By default, the command will migrate the root project and any project references that the root project contains. This behavior +can be disabled using the `--skip-project-references` option at runtime. + +Migration can be done on either: + +* A single project by specifying the `project.json` file to migrate +* All of the directories specified in the `global.json` file by passing in a path to the `global.json` file +* On all sub-directories of the given directory recursively + +The migrate command will keep the migrated `project.json` file inside a `backup` directory which it will create if it doesn't +exist. This can be overriden using the `--skip-backup` option. + +By default, the migration operation will output the state of the migration process to standard output (STDOUT). If you use the +`--report-file` option, that output will also be saved to a file that you specify. + +As of Preview 3, the `dotnet migrate` command only supports valid Preview 2 `project.json` files. This means that you cannot +use it to migrate old DNX or Preview 1 `project.json` files directly to csproj; you first need to migrate them to Preview 2 project.json files and then +to csproj files. In the future, we will add support for Preview 1 projects. + +## Options + +`-h|--help` + +Prints out a short help for the command. + +`-t|--template-file ` + +Template csproj file to use for migration. By default, the same template as the one dropped by `dotnet new` will be used. + +`-v|--sdk-package-version ` + +The version of the sdk package that will be referenced in the migrated app. The default is the version of the sdk in dotnet new. + +`-x|--xproj-file ` + +The path to the xproj file to use. Required when there is more than one xproj in a project directory. + +`-s|--skip-project-references [Debug|Release]` + +Skip migrating project references. By default project references are migrated recursively. + +`-r|--report-file ` + +Output migration report to a file in addition to the console. + +`--format-report-file-json ` + +Output migration report file as json rather than user messages. + +`--skip-backup` + +Skip moving project.json, global.json, and \*.xproj to a `backup` directory after successful migration. + +## Examples + +Migrate a project in the current directory and all of its project to project dependencies: + +`dotnet migrate` + +Migrate all projects that `global.json` file points to: + +`dotnet migrate path/to/global.json` + +Migrate only the current project and no project to project dependencies and use a specific SDK version: + +`dotnet migrate -s -v 1.0.0-preview3` + diff --git a/docs/core/preview3/tools/dotnet-msbuild.md b/docs/core/preview3/tools/dotnet-msbuild.md new file mode 100644 index 0000000000000..39b6450d04f4e --- /dev/null +++ b/docs/core/preview3/tools/dotnet-msbuild.md @@ -0,0 +1,91 @@ +<<<<<<< 94aa2d71d55ffa4d42044bb4ebb8d8e06d13d394 +--- +title: dotnet-msmsbuild command | .NET Core SDK +description: The dotnet-msmsbuild command provides access to MSmsbuild command line +keywords: dotnet-msmsbuild, 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-m/msbuild + +## Name +dotnet-msbuild -- msbuilds a project and all of its dependencies + +## Synopsis + +`dotnet msbuild ` + +## Description +The `dotnet msbuild` command allows access to a fully functional MSBuild + +The command has the exact same capablities as existing MSBuild command line client. The options are all the same. You can +use the [existing documentation](https://msdn.microsoft.com/en-us/library/ms164311.aspx) to get familiar with the command +reference. + +## Examples + +Build a project and its dependencies: + +`dotnet msbuild` + +Build a project and its dependencies using Release configuration: + +`dotnet msbuild /p:Configuration=Release--configuration Release` + +Run the publish target and publish for the `osx.10.11-x64` RID: + +`dotnet msbuild /t:Publish /p:RuntimeIdentifiers=osx.10.11-x64` + +======= +--- +title: dotnet-msmsbuild command | .NET Core SDK +description: The dotnet-msmsbuild command provides access to MSmsbuild command line +keywords: dotnet-msmsbuild, 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: ffdc40ba-ef33-463e-aa35-b0af1fe615a2 +--- + +#dotnet-msbuild + +## Name +dotnet-msbuild -- Builds a project and all of its dependencies + +## Synopsis + +`dotnet msbuild ` + +## Description +The `dotnet msbuild` command allows access to a fully functional MSBuild + +The command has the exact same capablities as existing MSBuild command line client. The options are all the same. You can +use the [existing documentation](https://msdn.microsoft.com/en-us/library/ms164311.aspx) to get familiar with the command +reference. + +## Examples + +Build a project and its dependencies: + +`dotnet msbuild` + +Build a project and its dependencies using Release configuration: + +`dotnet msbuild /p:Configuration=Release` + +Run the publish target and publish for the `osx.10.11-x64` RID: + +`dotnet msbuild /t:Publish /p:RuntimeIdentifiers=osx.10.11-x64` + +>>>>>>> Responding to PR feedback diff --git a/docs/core/preview3/tools/dotnet-new.md b/docs/core/preview3/tools/dotnet-new.md new file mode 100644 index 0000000000000..c2199c6c961d7 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-new.md @@ -0,0 +1,59 @@ +--- +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: 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 + +## Name +dotnet-new -- Creates a new .NET Core project in the current directory + +## Synopsis +`dotnet new [--help] [--type] [--lang]` + +## 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 current directory: + +1. A `Program.cs` (or `Program.fs`) file that contains a sample "Hello World" program. +2. A valid csproj project file. + +After this, the project is ready to be compiled and/or edited further. + +## Options + +`-h|--help` + +Prints out a short help for the command. + +`-l|--lang ` + +Language of the project. Defaults to `C#`. Other valid values are `csharp`, `fsharp`, `cs` and `fs`. + +`-t|--type` + +Type of the project. Valid values for C# are `console`, `web`, `lib` and `xunittest` and for F# only `console` is valid. + +## Examples + +Create a C# console application 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` \ No newline at end of file diff --git a/docs/cli-preview3/tools/dotnet-nuget-delete.md b/docs/core/preview3/tools/dotnet-nuget-delete.md similarity index 97% rename from docs/cli-preview3/tools/dotnet-nuget-delete.md rename to docs/core/preview3/tools/dotnet-nuget-delete.md index 116c06ed491ac..6e6b431433dc4 100644 --- a/docs/cli-preview3/tools/dotnet-nuget-delete.md +++ b/docs/core/preview3/tools/dotnet-nuget-delete.md @@ -15,7 +15,7 @@ ms.assetid: 6ddffde4-c789-4e90-990e-d35f6a6565d4 #dotnet-nuget-delete -[!INCLUDE[preview-warning](../../includes/warning.md)] +[!INCLUDE[preview-warning](../../../includes/warning.md)] ## Name `dotnet-nuget-delete` - Deletes or unlists a package from the server. diff --git a/docs/cli-preview3/tools/dotnet-nuget-locals.md b/docs/core/preview3/tools/dotnet-nuget-locals.md similarity index 97% rename from docs/cli-preview3/tools/dotnet-nuget-locals.md rename to docs/core/preview3/tools/dotnet-nuget-locals.md index cbce2fcfd92a0..d4416881319de 100644 --- a/docs/cli-preview3/tools/dotnet-nuget-locals.md +++ b/docs/core/preview3/tools/dotnet-nuget-locals.md @@ -15,7 +15,7 @@ ms.assetid: 8440229e-317e-4dc1-9463-cba5fdb12c3b #dotnet-nuget-locals -[!INCLUDE[preview-warning](../../includes/warning.md)] +[!INCLUDE[preview-warning](../../../includes/warning.md)] ## Name `dotnet-nuget-locals` - Clears or lists local NuGet resources such as http-request cache, temporary cache, or machine-wide global packages folder. @@ -91,4 +91,4 @@ Clears all the files in local temporary cache directory: ## Troubleshooting -For information about the most commonly faced problems and errors while using the `dotnet-nuget-locals` command, see [Managing the NuGet cache](https://docs.nuget.org/ndocs/consume-packages/managing-the-nuget-cache). \ No newline at end of file +For information about the most commonly faced problems and errors while using the `dotnet-nuget-locals` command, see [Managing the NuGet cache](https://docs.nuget.org/ndocs/consume-packages/managing-the-nuget-cache). diff --git a/docs/cli-preview3/tools/dotnet-nuget-push.md b/docs/core/preview3/tools/dotnet-nuget-push.md similarity index 97% rename from docs/cli-preview3/tools/dotnet-nuget-push.md rename to docs/core/preview3/tools/dotnet-nuget-push.md index d1d7c7f4ca31e..428d54ea78c8c 100644 --- a/docs/cli-preview3/tools/dotnet-nuget-push.md +++ b/docs/core/preview3/tools/dotnet-nuget-push.md @@ -15,7 +15,7 @@ ms.assetid: f54d9adf-94f8-41cc-bb52-42f7ca3be6ff #dotnet-nuget-push -[!INCLUDE[preview-warning](../../includes/warning.md)] +[!INCLUDE[preview-warning](../../../includes/warning.md)] ## Name `dotnet-nuget-push` - Pushes a package to the server and publishes it. @@ -114,4 +114,4 @@ Pushes all .nupkg files in current directory to default push source, specifying Push all .nupkg files in current directory to default push source, with maximum verbosity: -`dotnet nuget push *.nupkg --verbosity detailed` \ No newline at end of file +`dotnet nuget push *.nupkg --verbosity detailed` diff --git a/docs/core/preview3/tools/dotnet-pack.md b/docs/core/preview3/tools/dotnet-pack.md new file mode 100644 index 0000000000000..0cdd73e02a5cb --- /dev/null +++ b/docs/core/preview3/tools/dotnet-pack.md @@ -0,0 +1,94 @@ +--- +title: dotnet-pack command | .NET Core SDK +description: The dotnet-pack command creates NuGet packages for your .NET Core project. +keywords: dotnet-pack, CLI, CLI command, .NET Core +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: 8b4b8cef-f56c-4a10-aa01-fde8bfaae53e +--- + +#dotnet-pack + +## Name + +`dotnet-pack` - Packs the code into a NuGet package + +## Synopsis + +`dotnet pack [--help] [--output] + [--no-build] [--include-symbols] + [--include-source] [--servicable] + [--configuration] [--version-suffix] + [project]` + +## Description + +The `dotnet pack` command builds the project and creates NuGet packages. The result of this command is a nuget package. If the `--include-symbols` +option is present, another package containing the debug symbols will be created. + +NuGet dependencies of the project being packed are added to the nuspec file, so they are able to be resolved when the package is installed. +Project-to-project references are not packaged inside the project. Currently, you need to have a package per project if you have project-to-project dependencies. + +`dotnet pack` by default first builds the project. If you wish to avoid this, pass the `--no-build` option. This can be useful in Continuous Integration (CI) build scenarios in which you know the code was just previously built, for example. + +## Options + +`-h|--help` + +Prints out a short help for the command. + +`[project]` + +The project to pack. It can be either a path to a [csproj file](csproj.md) or to a directory. If omitted, it will +default to the current directory. + +`-o|--output ` + +Places the built packages in the directory specified. + +`--no-build` + +Does not build the project before packing. + +`--include-source` + +Includes the source files into the nuget package. The sources files are included in the `src` folder within the nupkg. + +`--include-symbols` + +Generate the symbols nupkg. + +`-c|--configuration ` + +Configuration to use when building the project. If not specified, will default to `Debug`. + +`--version-suffix` + +Updates the star in `-*` package version suffix with a specified string. + +## Examples + +Pack the project in the current directory: + +`dotnet pack` + +Pack the app1 project: + +`dotnet pack ~/projects/app1/project.csproj` + +Pack the project in the current directory and place the resulting packages into the specified folder: + +`dotnet pack --output nupkgs` + +Pack the project in the current directory into the specified folder and skip the build step: + +`dotnet pack --no-build --output nupkgs` + +Pack the current project and updates the resulting packages version with the given suffix. For example, version `1.0.0-*` will be updated to `1.0.0-ci-1234`. + +`dotnet pack --version-suffix "ci-1234"` diff --git a/docs/core/preview3/tools/dotnet-publish.md b/docs/core/preview3/tools/dotnet-publish.md new file mode 100644 index 0000000000000..524abbe994679 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-publish.md @@ -0,0 +1,91 @@ +--- +title: dotnet-publish command | .NET Core SDK +description: The dotnet-publish command publishes your .NET Core project into a directory. +keywords: dotnet-publish, CLI, CLI command, .NET Core +author: mairaw +manager: wpickett +ms.date: 10/07/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 8a7e1c52-5c57-4bf5-abad-727450ebeefd +--- + +#dotnet-publish + +## Name + +`dotnet-publish` - Packs the application and all of its dependencies into a folder getting it ready for publishing + +## Synopsis + +`dotnet publish [project] + [--help] [--framework] + [--runtime] [--output] + [--version-suffix] [--configuration]` + +## Description + +`dotnet publish` compiles the application, reads through its dependencies specified in the project file and publishes the resulting set of files to a directory. + +Depending on the type of portable app, the resulting directory will contain the following: + +1. *Framework-dependent deployment* - application's intermediate language (IL) code and all of application's managed dependencies. +2. *Self-contained deployment* - same as above plus the entire runtime for the targeted platform. + +For more information, see the [.NET Core Application Deployment](../deploying/index.md) topic. + +## Options + +`[project]` + +The project to publish, which defaults to the current directory if `[project]` is not specified. + +`-h|--help` + +Prints out a short help for the command. + +`-f|--framework ` + +Publishes the application for a given framework identifier (FID). + +`-r|--runtime ` + +Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs) you can use, see the [RID catalog](../../rid-catalog.md). + +`-o|--output ` + +Specify the path where to place the directory. If not specified, it will default to *_./bin/[configuration]/[framework]/_* +for portable applications or *_./bin/[configuration]/[framework]/[runtime]_* for self-contained deployments. + +`--version-suffix [VERSION_SUFFIX]` + +Defines what `*` should be replaced with in the version field in the project file. + +`-c|--configuration [Debug|Release]` + +Configuration to use when publishing. The default value is `Debug`. + +## Examples + +Publish an application. + +`dotnet publish` + +Publish the application using the specified project file + +`dotnet publish ~/projects/app1/app1.csproj` + +Publish the current application using the `netcoreapp1.0` framework: + +`dotnet publish --framework netcoreapp1.0` + +Publish the current application using the `netcoreapp1.0` framework and runtime for `OS X 10.10` (this RID has to +exist in the project file). + +`dotnet publish --framework netcoreapp1.0 --runtime osx.10.11-x64` + +## See also +* [Frameworks](../../../standard/frameworks.md) +* [Runtime IDentifier (RID) catalog](../../rid-catalog.md) diff --git a/docs/core/preview3/tools/dotnet-restore.md b/docs/core/preview3/tools/dotnet-restore.md new file mode 100644 index 0000000000000..80127359cb9ea --- /dev/null +++ b/docs/core/preview3/tools/dotnet-restore.md @@ -0,0 +1,103 @@ +--- +title: dotnet-restore command | .NET Core SDK +description: Learn how to restore dependencies and project-specific tools with the dotnet restore command +keywords: dotnet-restore, CLI, CLI command, .NET Core +author: mairaw +manager: wpickett +ms.date: 10/07/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 60489b25-38de-47e6-bed1-59d9f42e2d46 +--- + +#dotnet-restore + +## Name + +`dotnet-restore` - Restores the dependencies and tools of a project + +## Synopsis + +`dotnet restore [root] [--help] [--source] + [--packages] [--disable-parallel] [--configfile] + [--no-cache] [--ignore-failed-sources] [--no-dependencies]` + +## Description + +The `dotnet restore` command uses NuGet to restore dependencies as well as project-specific tools that are specified in the project file. +By default, the restoration of dependencies and tools are done in parallel. + +In order to restore the dependencies, NuGet needs the feeds where the packages are located. +Feeds are usually provided via the NuGet.config configuration file; a default one is present when the CLI tools are installed. +You can specify more feeds by creating your own NuGet.config file in the project directory. +Feeds can also be specified per invocation on the command prompt. + +For dependencies, you can specify where the restored packages are placed during the restore operation using the +`--packages` argument. +If not specified, the default NuGet package cache is used. +It is found in the `.nuget/packages` directory in the user's home directory on all operating systems (for example, */home/user1* on Linux or *C:\Users\user1* on Windows). + +For project-specific tooling, `dotnet restore` first restores the package in which the tool is packed, and then +proceeds to restore the tool's dependencies as specified in its project file. + +## Options + +`[root]` + +Optional path to the project file to restore. + +`-h|--help` + +Prints out a short help for the command. + +`-s|--source ` + +Specifies a NuGet package source to use during the restore operation. This overrides all of the sources specified in the NuGet.config file(s). Multiple sources can be provided by specifying this option multiple times. + +`--packages ` + +The NuGet configuration file (NuGet.config) to use for the restore operation. + +`--no-cache` + +Specifies to not cache packages and HTTP requests. + +` --ignore-failed-sources` + +Only warn about failed sources if there are packages meeting version requirement. + +`--no-dependencies` + +When restoring a project with P2P references, do not restore the references, just the root project. + +## Examples + +Restore dependencies and tools for the project in the current directory: + +`dotnet restore` + +Restore dependencies and tools for the `app1` project found in the given path: + +`dotnet restore ~/projects/app1/app1.csproj`` + +Restore the dependencies and tools for the project in the current directory using the file path provided as the fallback source: + +`dotnet restore -f c:\packages\mypackages` + +Restore the dependencies and tools for the project in the current directory using the two file paths provided as the fallback sources: + +`dotnet restore -f c:\packages\mypackages -f c:\packages\myotherpackages` + +Restore dependencies and tools for the project in the current directory and shows only errors in the output: + +`dotnet restore --verbosity Error` diff --git a/docs/core/preview3/tools/dotnet-run.md b/docs/core/preview3/tools/dotnet-run.md new file mode 100644 index 0000000000000..2d0f2fba89ca9 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-run.md @@ -0,0 +1,83 @@ +--- +title: dotnet-run command | .NET Core SDK +description: The dotnet-run command provides a convenient option to run your application from the source code. +keywords: dotnet-run, CLI, CLI command, .NET Core +author: mairaw +manager: wpickett +ms.date: 10/07/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 495ff50b-cb30-4d30-8f20-beb3d5e7c31f +--- + +#dotnet-run + +## Name + +dotnet-run -- Runs source code 'in-place' without any explicit compile or launch commands + +## Synopsis + +`dotnet run [--help] [--framework] [--configuration] + [--project] [[--] [application arguments]]` + +## Description +The `dotnet run` command provides a convenient option to run your application from the source code with one command. +It compiles source code, generates an output program and then runs that program. +This command is useful for fast iterative development and can also be used to run a source-distributed program (for example, a website). + +This command relies on [dotnet build](dotnet-build.md) to build source inputs to a .NET assembly, before launching the program. +The requirements for this command and the handling of source inputs are all inherited from the build command. +The documentation for the build command provides more information on those requirements. + +Output files are written to the child *bin* folder, which will be created if it doesn't exist. +Files will be overwritten as needed. +Temporary files are written to the child *obj* folder. + +In case of a project with multiple specified frameworks, `dotnet run` will first select the .NET Core frameworks. If those do not exist, it will error out. To specify other frameworks, use the `--framework` argument. + +The `dotnet run` command must be used in the context of projects, not built assemblies. If you're trying to run a portable application DLL instead, you should use [dotnet](dotnet.md) without any command like in the following example: + +`dotnet myapp.dll` + +For more information about the `dotnet` driver, see the [.NET Core Command Line Tools (CLI)](index.md) topic. + +## Options + +`--` + +Delimits arguments to `dotnet run` from arguments for the application being run. +All arguments after this one will be passed to the application being run. + +`-h|--help` + +Prints out a short help for the command. + +`-f`, `--framework ` + +Runs the application for a given framework identifier (FID). + +`-c`, `--configuration ` + +Configuration to use when publishing. The default value is `Debug`. + +`-p`, `--project [PATH]` + +Specifies which project to run. +It can be a path to a [csproj](csproj.md) file or to a directory containing a [csproj](csproj.md) file. It defaults to +current directory if not specified. + +## Examples + +Run the project in the current directory: +`dotnet run` + +Run the specified project: + +`dotnet run --project /projects/proj1/proj1.csproj` + +Run the project in the current directory (the `--help` argument in this example is passed to the application being run, since the `--` argument was used): + +`dotnet run --configuration Release -- --help` \ No newline at end of file diff --git a/docs/core/preview3/tools/dotnet-test.md b/docs/core/preview3/tools/dotnet-test.md new file mode 100644 index 0000000000000..bb537e85d7d67 --- /dev/null +++ b/docs/core/preview3/tools/dotnet-test.md @@ -0,0 +1,142 @@ +--- +title: dotnet-test command | .NET Core SDK +description: The `dotnet test` command is used to execute unit tests in a given project. +keywords: dotnet-test, CLI, CLI command, .NET Core +author: mairaw +manager: wpickett +ms.date: 10/07/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 3a0fa917-eb0a-4d7e-9217-d06e65455675 +--- + +#dotnet-test + +## Name + +`dotnet-test` - .NET test driver + +## Synopsis + +`dotnet test [project] [--help] + [--settings] [--listTests] [--testCaseFilter] + [--testAdapterPath] [--logger] + [--configuration] [--output] [--framework] [--diag] + [--noBuild]` + +## Description + +The `dotnet test` command is used to execute unit tests in a given project. Unit tests are class library +projects that have dependencies on the unit test framework (for example, NUnit or xUnit) and the +dotnet test runner for that unit testing framework. +These are packaged as NuGet packages and are restored as ordinary dependencies for the project. + +Test projects also need to specify the test runner. This is specified using an ordinary `` element, as +seen in the following sample project file: + +```xml + + + + + Exe + netcoreapp1.0 + + + + + + + + + + 1.0.1 + + + 1.0.0-alpha-20161104-2 + All + + + 15.0.0-preview-20161024-02 + + + 2.2.0-beta3-build3402 + + + 2.2.0-beta4-build1188 + + + + + +``` + +## Options + +`[project]` + +Specifies a path to the test project. If omitted, it defaults to current directory. + +`-h|--help` + +Prints out a short help for the command. + +`-s | --settings ` + +Settings to use when running tests. + +`-lt | --listTests` + +List all of the discovered tests in the current project. + +`-tcf | --testCaseFilter ` + +Filter out tests in the current project using the given expression. + +`-tap | --testAdapterPath ` + +Use the custom test adapters from the specified path in this test run. + +`--logger ` + +Specify a logger for test results. + +`-c|--configuration ` + +Configuration under which to build. The default value is `Release`. + +`-o|--output [OUTPUT_DIRECTORY]` + +Directory in which to find the binaries to run. + +Looks for test binaries for a specific framework. + +`-r|--runtime [RUNTIME_IDENTIFIER]` + +Look for test binaries for a for the specified runtime. + +`--noBuild` + +Does not build the test project prior to running it. + +`-d | --diag ` + +Enable diagnostic mode for the test platform and write diagnostic messages to the specified file. + +## Examples + +Run the tests in the project in the current directory: + +`dotnet test` + +Run the tests in the test1 project: + +`dotnet test /projects/test1/test1.csproj` + +## See also + +[Frameworks](../../../standard/frameworks.md) + +[Runtime IDentifier (RID) catalog](../../rid-catalog.md) diff --git a/docs/core/preview3/tools/dotnet.md b/docs/core/preview3/tools/dotnet.md new file mode 100644 index 0000000000000..a804074c2c821 --- /dev/null +++ b/docs/core/preview3/tools/dotnet.md @@ -0,0 +1,103 @@ +--- +title: dotnet command | .NET Core SDK +description: Learn about the dotnet command (the generic driver for the .NET Core CLI tools) and its usage. +keywords: dotnet, CLI, CLI commands, .NET Core +author: mairaw +manager: wpickett +ms.date: 10/07/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 93015521-2127-4fe9-8fce-ca79bcc4ff49 +--- + +#dotnet command + +## Name + +dotnet -- General driver for running the command-line commands + +## Synopsis + +`dotnet [--version] [--verbose] [--info] [command] [arguments] [--help]` + +## Description +`dotnet` is a generic driver for the Command Line Interface (CLI) toolchain. Invoked on its own, it will give out brief usage instructions. + +Each specific feature is implemented as a command. In order to use the feature, the command is specified after `dotnet`, such as [`dotnet build`](dotnet-build.md). All of the arguments following the command are its own arguments. + +The only time `dotnet` is used as a command on its own is to run portable apps. Just specify a portable application DLL after the `dotnet` verb to execute the application. + +## Options + +`-v|--verbose` + +Enables verbose output. + +`--version` + +Prints out the version of the CLI tooling. + +`--info` + +Prints out more detailed information about the CLI tooling, such as the current operating system, commit SHA for the version, etc. + +`-h|--help` + +Prints out a short help for the command. If using with `dotnet` only, it also prints a list of the available commands. + +## dotnet commands + +The following commands exist for dotnet: + +* [dotnet-new](dotnet-new.md) + * Initializes a C# or F# console application project. +* [dotnet-restore](dotnet-restore.md) + * Restores the dependencies for a given application. +* [dotnet-build](dotnet-build.md) + * Builds a .NET Core application. +* [dotnet-publish](dotnet-publish.md) + * Publishes a .NET portable or self-contained application. +* [dotnet-run](dotnet-run.md) + * Runs the application from source. +* [dotnet-test](dotnet-test.md) + * Runs tests using a test runner specified in the project.json. +* [dotnet-pack](dotnet-pack.md) + * Creates a NuGet package of your code. +* [dotnet-migrate](dotnet-migrate.md) + * Migrates a valid Preview 2 project to a Preview 3 project +* [dotnet-msbuild](dotnet-msbuild.md) + * Provides access to MSBuild command line + +## Examples + +Initialize a sample .NET Core console application that can be compiled and run: + +`dotnet new` + +Restore dependencies for a given application: + +`dotnet restore` + +Build a project and its dependencies in a given directory: + +`dotnet build` + +Run a portable app named `myapp.dll`: +`dotnet myapp.dll` + +## Environment + +`DOTNET_PACKAGES` + +The primary package cache. If not set, it defaults to $HOME/.nuget/packages on Unix or %HOME%\NuGet\Packages on Windows. + +`DOTNET_SERVICING` + +Specifies the location of the servicing index to use by the shared host when loading the runtime. + +`DOTNET_CLI_TELEMETRY_OPTOUT` + +Specifies whether data about the .NET Core tools usage is collected and sent to Microsoft. `true` to opt-out of the telemetry feature (values true, 1 or yes accepted); otherwise, `false` (values false, 0 or no accepted). If not set, it defaults to `false`, that is, the telemetry feature is on. + diff --git a/docs/core/preview3/tools/extensibility.md b/docs/core/preview3/tools/extensibility.md new file mode 100644 index 0000000000000..c634257cdeb89 --- /dev/null +++ b/docs/core/preview3/tools/extensibility.md @@ -0,0 +1,238 @@ +--- +title: .NET Core CLI extensibility model +description: .NET Core CLI extensibility model +keywords: CLI, extensibility, custom commands, .NET Core +author: mairaw +manager: wpickett +ms.date: 11/13/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 1bebd25a-120f-48d3-8c25-c89965afcbcd +--- + +# .NET Core CLI extensibility model + +## Overview +This document will cover the main ways how to extend the CLI tools and explain the scenarios that drive each of them. +It will the outline how to consume the tools as well as provide short notes on how to build both types of tools. + +## How to extend CLI tools +The Preview 3 CLI tools can be extended in three main ways: + +1. Via NuGet packages on a per-project basis +2. Via NuGet packages with custom targets +3. Via the system's PATH + +The three extensibility mechanisms outlined above are not exclusive; you can use all or just one or combine them. Which one to pick +depends largely on what is the goal you are trying to achieve with your extension. + +## Per-project based extensibility +Per-project tools are [framework-dependented deployments](../deploying/index.md) that are distributed as NuGet packages. Tools are +only available in the context of the project that references them and for which they are restored; invocation outside +of the context of the project (for example, outside of the directory that contains the project) will fail as the command will +not be able to be found. + +These tools are perfect for build servers, since nothing outside of the project file is needed. The build process +runs restore for the project it builds and tools will be available. Language projects, such as F#, are also in this +category; after all, each project can only be written in one specific language. + +Finally, this extensibility model provides support for creation of tools that need access to the built output of the +project. For instance, various Razor view tools in [ASP.NET](https://www.asp.net/) MVC applications fall into this +category. + +### Consuming per-project tools +Consuming these tools requires you to add a `` element for each tool you want to use to your project file. Inside the `` element, you reference the package in which the tool resides and you specify the version you need. After running `dotnet restore`, the tool and its dependencies are restored. + +For tools that need to load the build output of the project for execution, there is usually another dependency which is +listed under the regular dependencies in the project file. Since the Preview 3 version of the CLI uses MSBuild as its build engine, it is recommended that these parts of the tool be written as custom MSBuild targets and tasks since that way they can take part in the overall build process. Also, they can get any and all data easily that is produced via the build, for example the location of the output files, the current configuration being built etc. All of this information in Preview 3 becomes a set of MSBuild properties that can be read from any target. We will see how to add a custom target using NuGet later in this document. + +Let's review an example of adding a simple tools-only tool to a simple project. Given an example command called +`dotnet-api-search` that allows you to search through the NuGet packages for the specified +API, here is a console application's project file that uses that tool: + + +```xml + + + + Exe + netcoreapp1.1/TargetFramework> + 1.0.0 + + + + + + + + 1.1.0 + + + 1.0.0-alpha-20161102-2 + All + + + + + + + + + + + + +``` + +The `` element is structured in a similar way as the `` element. It needs the package ID of the package containing the tool and its version at the very least. + +### Building tools +As mentioned, tools are just portable console applications. You would build one as you would build any console application. +After you build it, you would use [`dotnet pack`](dotnet-pack.md) command to create a NuGet package (nupkg) that contains +your code, information about its dependencies and so on. The package name can be whatever the author wants, but the +application inside, the actual tool binary, has to conform to the convention of `dotnet-` in order for `dotnet` +to be able to invoke it. + +In Preview 3 bits, the `dotnet pack` command will not pack the `runtimeconfig.json` file that is needed to run the tool. In order to package the this file, you have two options: + +1. Create a `nuspec` file and use `dotnet nuget pack` command newly available to Preview 3 CLI to include the file +2. Use the new `` element in an `` in your project file to include the file manually + +Working with nuspec files is beyond the scope of this article, however you can find a lot of good information in the [official NuGet docs](https://docs.nuget.org/ndocs/create-packages/creating-a-package#the-role-and-structure-of-the--nuspec-file). If you decide on the second approach, you can see the example `csproj` file and how it is configured below: + +```xml + + + true + lib\$(TargetFramework) + + +``` + +This `` instructs the `dotnet pack` command to pack any `runtimeconfig.json` files in the build output directory (designated by the `$(OutputPath)` variable) and place it into the `lib` folder for the built target framework. The built target framework is designated similarly to the output path by using a MSBuild property. After this is set, the resulting tool nupkg file will contain all that is needed for running the tool. + +Since tools are portable applications, the user consuming the tool has to have the version of the .NET Core libraries +that the tool was built against in order to run the tool. Any other dependency that the tool uses and that is not +contained within the .NET Core libraries is restored and placed in the NuGet cache. The entire tool is, therefore, run +using the assemblies from the .NET Core libraries as well as assemblies from the NuGet cache. + +These kind of tools have a dependency graph that is completely separate from the dependency graph of the project that +uses them. The restore process will first restore the project's dependencies, and will then restore each of the tools and +their dependencies. + +You can find richer examples and different combinations of this in the [.NET Core CLI repo](https://github.com/dotnet/cli/tree/rel/1.0.0-preview2/TestAssets/TestProjects). +You can also see the [implementation of tools used](https://github.com/dotnet/cli/tree/rel/1.0.0-preview2/TestAssets/TestPackages) in the same repo. + +### Custom targets +NuGet has had the capability to package custom MSBuild target and props files for a while now and you can find the official documentation on this on the [NuGet documentation site](https://docs.nuget.org/ndocs/create-packages/creating-a-package#including-msbuild-props-and-targets-in-a-package). With the move in the CLI to using MSBuild, the same mechanism of extensibility applies to .NET Core projects. You would use this type of extensiblity when you want to extend the build process or when you want to access any of the artifacts in the build process, such as generated files or inspect the configuration under which the build is invoked etc. + +The sample target's project file is included below for reference. It shows how to use the new `csproj` syntax for instructing `dotnet pack` command what to package to place the targets files as well as assemblies into the `build` folder inside the package. Take note of the `` below that has the `Label` property set to "dotnet pack instructions". + +```xml + + + + Sample Packer + 0.1.0-preview + netstandard1.3 + portable + SampleTargets.PackerTarget + + + + + + + + + + + + true + build\ + + + + + 1.0.0-alpha-20161029-1 + All + + + 1.0.1-beta-000933 + + + 0.1.0-preview-00028-160627 + + + 0.1.0-preview-00028-160627 + + + 9.0.1 + + + + + 1.6.0 + + + + + $(DefineConstants);NETSTANDARD1_3 + + + $(DefineConstants);RELEASE + + + +``` + +Consuming custom targets is done by providing a `` that points to the package and its version inside the project that is being extended. Unlike the tools, the custom targets package does get included into the consuming project's dependency closure. + +Using the custom target depends solely on how you configure it. Since it is the usual MSBuild target, it can depend on a given target, run after another target and can also be manually invoked using the `dotnet msbuild /t:` command. + +However, if you wish to provide a better user experience to your users, you can combine per-project tools and custom targets. In this scenario, the per-project tool would essentially just accept whatever needed parameters and would translate that into the required `dotnet msbuild` invocation that would execute the target. You can see a sample of this kind of sinergy on the [MVP Summit 2016 Hackathon samples](https://github.com/dotnet/MVPSummitHackathon2016) repo in the [`dotnet-packer`](https://github.com/dotnet/MVPSummitHackathon2016/tree/master/dotnet-packer) project. + +### PATH-based extensibility +PATH-based extensibility is usually used for development machines where you need a tool that conceptually covers more +than a single project. The main drawback of this extensions mechanism is that it is tied to the machine where the +tool exists. If you need it on another machine, you would have to deploy it. + +This pattern of CLI toolset extensibility is very simple. As covered in the [.NET Core CLI overview](index.md), `dotnet` driver +can run any command that is named after the `dotnet-` convention. The default resolution logic will first +probe several locations and will finally fall to the system PATH. If the requested command exists in the system PATH +and is a binary that can be invoked, `dotnet` driver will invoke it. + +The binary can be pretty much anything that the operating system can execute. On Unix systems, this means anything that +has the execute bit set via `chmod +x`. On Windows it means anything that Windows knows how to run. + +As an example, let's take a look at a very simple implementation of a `dotnet clean` command. We will use `bash` to +implement this command. The command will simply delete the `bin/` and `obj/` directories in the current directory. If +the `--lock` argument is passed to it, it will also delete `project.lock.json` file. The entirety of the command is +given below. + +```bash +#!/bin/bash + +# Delete the bin and obj dirs +rm -rf bin/ obj/ + +LOCK_FILE=$1 +if [[ "$LOCK_FILE" = "--lock" ]]; then + rm project.lock.json +fi + + +echo "Cleaning complete..." +``` + +On macOS, we can save this script as `dotnet-clean` and set its executable bit with `chmod +x dotnet-clean`. We can then +create a symbolic link to it in `/usr/local/bin` using the command `ln -s dotnet-clean /usr/local/bin/`. This will make +it possible to invoke the clean command using the `dotnet clean` syntax. You can test this by creating an app, running +`dotnet build` on it and then running `dotnet clean`. + +## Conclusion +The .NET Core CLI tools allow three main extensibility points. The per-project tools are contained within the project's +context, but they allow easy installation through restoration. Custom targets allow you to easily extend the build process with custom tasks. PATH-based tools are good for general, cross-project tools that are usable on a single machine. + diff --git a/docs/core/preview3/tools/global-json.md b/docs/core/preview3/tools/global-json.md new file mode 100644 index 0000000000000..136347e60721f --- /dev/null +++ b/docs/core/preview3/tools/global-json.md @@ -0,0 +1,41 @@ +--- +title: global.json reference | .NET Core +description: global.json reference +keywords: .NET, .NET Core +author: aL3891 +ms.author: mairaw +manager: wpickett +ms.date: 11/02/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: e1ac9659-425f-4486-a376-c12ca942ead8 +--- + +# global.json reference + +The global.json file is still present in the .NET Core Command Line Preview 3. However, its main purpose is not to define +solution metadata as in previous releases, but to allow selection of the CLI version being used through the `sdk` property. + +This reference reflects the above fact. + +## sdk +Type: Object + +Specifies information about the SDK. + +### version +Type: String + +The version of the SDK to use. + +For example: + +```json +{ + "sdk": { + "version": "1.0.0-preview2-003121" + } +} +``` diff --git a/docs/core/preview3/tools/index.md b/docs/core/preview3/tools/index.md new file mode 100644 index 0000000000000..042a6df3b2239 --- /dev/null +++ b/docs/core/preview3/tools/index.md @@ -0,0 +1,129 @@ +--- +title: .NET Core Command-Line Interface (CLI) Tools +description: An overview of what the Command-Line Interface (CLI) is and its main features +keywords: CLI, CLI tools, .NET, .NET Core +author: blackdwarf +ms.author: mairaw +manager: wpickett +ms.date: 10/06/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: b70e9ac0-c8be-49f7-9332-95ab93e0e7bc +--- + +# .NET Core command-line interface tools + +The .NET Core command-line interface (CLI) is a new foundational cross-platform toolchain for developing +.NET Core applications. It is "foundational" because it is the primary layer on which other, +higher-level tools, such as Integrated Development Environments (IDEs), editors and +build orchestrators can build on. + +It is also cross-platform by default and has the same surface area on each of the supported platforms. This means that +when you learn how to use the tooling, you can use it the same way from any of the supported platforms. + +## Installation +As with any tooling, the first thing is to get the tools to your machine. Depending on your scenario, you can either +use the native installers to install the CLI or use the installation shell script. + +The native installers are primarily meant for developer's machines. The CLI is distributed using each supported platform's +native install mechanism, for instance DEB packages on Ubuntu or MSI bundles on Windows. These installers will install +and set up the environment as needed for the user to use the CLI immediately after the install. However, they also +require administrative privileges on the machine. You can view the installation instructions on the +[.NET Core getting started page](https://aka.ms/dotnetcoregs). + +Install scripts, on the other hand, do not require administrative privileges. However, they will also not install any +prerequisites on the machine; you need to install all of the prerequisites manually. The scripts are meant mostly for +setting up build servers or when you wish to install the tools without administrative privileges (do note the prerequisites +caveat above). You can find more information on the [install script reference topic](dotnet-install-script.md). If you are +interested in how to set up CLI on your continuous integration (CI) build server you can take a look at the +[CLI with CI servers](using-ci-with-cli.md) topic. + +By default, the CLI will install in a side-by-side (SxS) manner. This means that multiple versions of the CLI tools +can coexist at any given time on a single machine. How the correct version gets used is explained in more detail in +the [driver](#driver) section. + +### What commands come in the box? +The following commands are installed by default: + +* [new](dotnet-new.md) +* [restore](dotnet-restore.md) +* [run](dotnet-run.md) +* [build](dotnet-build.md) +* [test](dotnet-test.md) +* [publish](dotnet-publish.md) +* [pack](dotnet-pack.md) + +There is also a way to import more commands on a per-project basis as well as to add your own commands. This is +explained in greater detail in the [extensibility section](#extensibility). + +## Working with the CLI + +Before we go into any more details, let's see how working with the CLI looks like from a 10,000-foot view. +The following example utilizes several commands from the CLI standard install to initialize a new simple console application, +restore the dependencies, build the application and then run it. + +```console +dotnet new +dotnet restore +dotnet build --output /stuff +dotnet /stuff/new.dll +``` + +As you can see in the previous example, there is a pattern in the way you use the CLI tools. Within that pattern, we can +identify three main pieces of each command: + +1. [The driver ("dotnet")](#driver) +2. [The command, or "verb"](#the-verb) +3. [Command arguments](#the-arguments) + +### Driver +The driver is named [dotnet](dotnet.md). It is the first part of what you invoke. The driver has two responsibilities: + +1. Running portable apps +2. Executing the verb + +What it does depends on what is specified on the command line. In the first case, you would +specify a portable app DLL that `dotnet` would run similar to this: `dotnet /path/to/your.dll`. + +In the second case, the driver attempts to invoke the specified command. This starts the CLI command execution +process. First, the driver determines the version of the tooling that you want. You can specify the version in the +[global.json](global-json.md) file using the `version` property. If that is not available, the driver finds the latest version +of the tools that is installed on disk and uses that version. Once the version is determined, it executes the +command. + +### The "verb" +The verb is simply a command that performs an action. `dotnet build` builds your code. `dotnet publish` publishes +your code. The verb is implemented as a console application that is named per convention: `dotnet-{verb}`. All of the +logic is implemented in the console application that represents the verb. + +### The arguments +The arguments that you pass on the command-line are the arguments to the actual verb/command being invoked. +For example, when you type `dotnet publish --output publishedapp`, the `--output` argument is passed to the +`publish` command. + +## Types of application portability +CLI enables applications to be portable in two main ways: + +1. Completely portable applications that can run anywhere .NET Core is installed +2. Self-contained deployments + +You can learn more about both of these in the [.NET Core application deployment](../deploying/index.md) topic. + +## Migration from Preview 3/project.json +If you used Preview 2 tooling and project.json projects, you can consult the [dotnet migrate](dotnet-migrate.md) command docs +to get acquainted with the command and how to migrate your project. + +> **Note:** the `dotnet migrate` command currently does not migrate pre-preview 2 project.json files. + +## Extensibility +Of course, not every tool that you could use in your workflow will be part of the core CLI tools. However, .NET Core +CLI has an extensibility model that allows you to specify additional tools for your projects. You can find out more +in the [.NET Core CLI extensibility model](extensibility.md) topic. + +## Summary +This was a short overview of the most important features of the CLI. You can find out more by using the reference and +conceptual topics on this site. There are also other resources you can use: +* [dotnet/CLI](https://github.com/dotnet/cli/) GitHub repo +* [Getting started instructions](https://aka.ms/dotnetcoregs/) diff --git a/docs/core/preview3/tools/layering.md b/docs/core/preview3/tools/layering.md new file mode 100644 index 0000000000000..a8d7be75c9ffe --- /dev/null +++ b/docs/core/preview3/tools/layering.md @@ -0,0 +1,78 @@ +--- +title: .NET Core Command Line Tools Preview 3 Architecture +description: Preview 3 brings about certain changes to the way the overall .NET Core tools are layered. +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 +--- + +High level overview of changes in CLI Preview 3 +----------------------------------------------- + +# Overview +This document will describe in high-level the changes that moving from `project.json` to MSBuild and `csproj` project system bring. It will outline the new way the tooling is layered all-up and which new pieces are available and what is their place in the overall picture. After reading this article, you should have a better understanding of all of the pieces that make up .NET Core tooling after moving to MSBuild and `csproj`. + +> **Note:** this article is **not required** to use the Preview 3 .NET Core Command Line tools. you can continue using the tools as you are +> used to. This article is here to complete the picture of how the move to MSBuild changes the overall "layering" and the architecture of +> the command line tools. + +# Moving away from project.json +The biggest change in the Preview 3 tooling for .NET Core is certainly the [move away from project.json to csproj](https://blogs.msdn.microsoft.com/dotnet/2016/05/23/changes-to-project-json/) as the project system. Preview 3 version of the command line tools is the first release of .NET Core command line tooling that does not contain any support for project.json. That means that it cannot be used to build, run or publish project.json based applications and libraries. In order to use this version of the tools, you will need to migrate your existing projects or start new ones. + +As part of this move, the custom build engine that was developed to build project.json projects was replaced with a mature and fully capable build engine called [MSBuild](https://github.com/Microsoft/msbuild). MSBuild is a well-known engine in the .NET community, since it has been a key technology since the platform's first release. Of course, because it needs to build .NET Core applications, MSBuild has been ported to .NET Core and can be used on any platform that .NET Core runs on. One of the main promises of .NET Core is that of a cross-platform development stack, and we have made sure that this move does not break that promise. + +> **Note:** if you are new to MSBuild and would like to learn more about it, you can start by reading +> the [existing documentation](https://msdn.microsoft.com/en-us/library/dd637714.aspx). + +# The tooling layers +With the move away from the existing project system as well as with building engine switches, the question that naturally follows is do any of these changes change the overall "layering" of the whole .NET Core tooling ecosystem? Are there new bits and components? + +Let's start with a quick refresher on Preview 2 layering as shown in the following picture: + +![Preview 2 tools high-level architecture](media/p2-arch.png) + +The layering of the tools is quite simple. At the bottom we have the .NET Core Command Line tools as a foundation. All other, higher-level tools such as Visual Studio or VS Code, depend and rely on the CLI to build projects, restore dependencies and so on. This meant that, for example, if Visual Studio wanted to perform a restore operation, it would call into `dotnet restore` command in the CLI. + +With the move to the new project system, the previous diagram changes: + +![Preview 3 tools high-level architecture](media/p3-arch.png) + +The main difference is that the CLI is not the foundational layer anymore; this role is now filled by the "shared SDK component". This shared SDK component is a set of targets and associated tasks that are responsible for compiling your code, publishing it, packing nuget packages etc. The SDK itself is open-source and is available on GitHub on the [SDK repo](https://github.com/dotnet/sdk). + +> **Note:** a "target" is an MSBuild term that indicates a named operation that MSBuild can invoke. It is usually coupled with one or more tasks that execute some logic that the target is supposed to do. MSBuild supports many ready-made targets such as `Copy` or `Execute`; it also allows users to write their own tasks using managed code and define targets to execute those tasks. You can read more about MSBuild tasks on [MSDN](https://msdn.microsoft.com/en-us/library/ms171466.aspx). + +All the toolsets now consume the shared SDK component and its targets, CLI included. For example, the next version of Visual Studio will not call into `dotnet restore` command to restore dependencies for .NET Core projects, it will use the "Restore" target directly. Since these are MSBuild targets, you can also use raw MSBuild to execute them using the [dotnet msbuild](dotnet-msbuild.md) command. + +## Preview 3 CLI commands +The shared SDK component means that the majority of existing CLI commands have been re-implemented as MSBuild tasks and targets. What does this mean for the CLI commands and your usage of the toolset? + +From an usage perspective, it doesn't change the way you use the CLI. The CLI still has the core commands that exist in Preview 2 release: + +* `new` +* `restore` +* `run` +* `build` +* `publish` +* `test` +* `pack` + +These commands still do what you expect them to do (new up a project, build it, publish it, pack it and so on). Majority of the options are not changed, and are still there, and you can consult either the commands' help screens (using `dotent --help`) or Preview 3 documentation on this site to get familiar with any changes. + +From an execution perspective, the CLI commands will take their parameters and construct a call to "raw" MSBuild that will set the needed properties and run the desired target. To better illustrate this, consider the following command: + + `dotnet publish -o pub -c Release`. + +This command is publishing an application into a `pub` folder using the "Release" configuration. Internally, this command gets translated into the following MSBuild invocation: + + `dotnet msbuild /t:Publish /p:OutputPath=pub /p:Configuration` + +The notable exception to this rule are `new` and `run` commands, as they have not been implemented as MSBuild targets. + +# Conclusion +This document outlined at a high-level the changes that are happening to the overall CLI tooling architecture and functioning that are coming with Preview 3. It has introduced the notion of the shared SDK component as well as explained how the CLI commands function, from a technical perspective, in Preview 3. + diff --git a/docs/core/preview3/tools/media/p2-arch.png b/docs/core/preview3/tools/media/p2-arch.png new file mode 100644 index 0000000000000..76128ebb8907c Binary files /dev/null and b/docs/core/preview3/tools/media/p2-arch.png differ diff --git a/docs/core/preview3/tools/media/p3-arch.png b/docs/core/preview3/tools/media/p3-arch.png new file mode 100644 index 0000000000000..d47a01e9ccc7a Binary files /dev/null and b/docs/core/preview3/tools/media/p3-arch.png differ diff --git a/docs/core/preview3/tools/media/test-protocol/dotnet-test-discover.png b/docs/core/preview3/tools/media/test-protocol/dotnet-test-discover.png new file mode 100644 index 0000000000000..76b332f933e32 Binary files /dev/null and b/docs/core/preview3/tools/media/test-protocol/dotnet-test-discover.png differ diff --git a/docs/core/preview3/tools/media/test-protocol/dotnet-test-execute.png b/docs/core/preview3/tools/media/test-protocol/dotnet-test-execute.png new file mode 100644 index 0000000000000..ca786410e55c6 Binary files /dev/null and b/docs/core/preview3/tools/media/test-protocol/dotnet-test-execute.png differ diff --git a/docs/core/preview3/tools/telemetry.md b/docs/core/preview3/tools/telemetry.md new file mode 100644 index 0000000000000..fc6187ee6e09e --- /dev/null +++ b/docs/core/preview3/tools/telemetry.md @@ -0,0 +1,100 @@ +--- +title: .NET Core Tools Telemetry +description: .NET Core +keywords: .NET, .NET Core +author: richlander +manager: wpickett +ms.date: 07/06/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: f2b312bb-f80b-4b0d-9101-93908f06a6fa +--- + +# .NET Core Tools Telemetry + +The .NET Core Tools include a [telemetry feature](https://github.com/dotnet/cli/pull/2145) that collects usage information. It’s important that the .NET Team understands how the tools are being used so that we can improve them. + +The data collected is anonymous and will be published in an aggregated form for use by both Microsoft and community engineers under the [Creative Commons Attribution License](https://creativecommons.org/licenses/by/4.0/). + +## Scope + +The `dotnet` command is used to launch both apps and the .NET Core Tools. The `dotnet` command itself does not collect telemetry. It is the .NET Core Tools that are run via the `dotnet` command that collect telemetry. + +.NET Core commands (telemetry is not enabled): + +- `dotnet` +- `dotnet [path-to-app]` + +.NET Core Tools [commands](index.md) (telemetry is enabled), such as: + +- `dotnet build` +- `dotnet pack` +- `dotnet restore` +- `dotnet run` + +##Behavior + +The .NET Core Tools telemetry feature is enabled by default. You can opt-out of the telemetry feature by setting an environment variable DOTNET_CLI_TELEMETRY_OPTOUT (for example, `export` on macOS/Linux, `set` on Windows) to true (for example, “true”, 1). + +##Data Points + +The feature collects the following pieces of data: + +- The command being used (for example, “build”, “restore”) +- The ExitCode of the command +- For test projects, the test runner being used +- The timestamp of invocation +- The framework used +- Whether runtime IDs are present in the “runtimes” node +- The CLI version being used + +The feature will not collect any personal data, such as usernames or emails. It will not scan your code and not extract any project-level data that can be considered sensitive, such as name, repo or author (if you set those in your project.json). We want to know how the tools are used, not what you are building with the tools. If you find sensitive data being collected, that’s a bug. Please [file an issue](https://github.com/dotnet/cli/issues) and it will be fixed. + +##License + +The Microsoft distribution of .NET Core is licensed with the [MICROSOFT .NET LIBRARY EULA](https://aka.ms/dotnet-core-eula). This includes the “DATA” section re-printed below, to enable telemetry. + +[.NET NuGet packages](https://www.nuget.org/profiles/dotnetframework) use this same license but do not enable telemetry (see [Scope](#scope) above). + +```text +2. DATA. The software may collect information about you and your use of +the software, and send that to Microsoft. Microsoft may use this information +to improve our products and services. You can learn more about data collection +and use in the help documentation and the privacy statement at +http://go.microsoft.com/fwlink/?LinkId=528096 . Your use of the software +operates as your consent to these practices. +``` + +## Disclosure + +The .NET Core Tools display the following text when you first run one of the commands (for example, `dotnet restore`). This "first run" experience is how Microsoft notifies you about data collection. This same experience also initially populates your NuGet cache with the libraries in the .NET Core SDK, avoiding requests to NuGet.org (or other NuGet feed) for these libraries. + +```text +Welcome to .NET Core! +--------------------- + +Learn more about .NET Core @ https://aka.ms/dotnet-docs. Use dotnet --help to +see available commands or go to https://aka.ms/dotnet-cli-docs. + +Telemetry +--------- + +The .NET Core tools collect usage data in order to improve your experience. +The data is anonymous and does not include commandline arguments. The data is +collected by Microsoft and shared with the community. + +You can opt out of telemetry by setting a DOTNET_CLI_TELEMETRY_OPTOUT +environment variable to 1 using your favorite shell. + +You can read more about .NET Core tools telemetry @ https://aka.ms/dotnet-cli- +telemetry. + +Configuring... +-------------- + +A command is running to initially populate your local package cache, to +improve restore speed and enable offline access. This command will take up to +a minute to complete and will only happen once. +``` diff --git a/docs/core/preview3/tools/using-ci-with-cli.md b/docs/core/preview3/tools/using-ci-with-cli.md new file mode 100644 index 0000000000000..464fdf4987502 --- /dev/null +++ b/docs/core/preview3/tools/using-ci-with-cli.md @@ -0,0 +1,109 @@ +--- +title: Using .NET Core SDK and tools in Continuous Integration (CI) +description: Using .NET Core SDK and tools in Continuous Integration (CI) +keywords: .NET, .NET Core +author: mairaw +manager: wpickett +ms.date: 06/20/2016 +ms.topic: article +ms.prod: .net-core +ms.technology: .net-core-technologies +ms.devlang: dotnet +ms.assetid: 5fb15297-a276-417f-8c4f-267281357769 +--- + +# Using .NET Core SDK and tools in Continuous Integration (CI) + +## Overview +This document outlines the usage of .NET Core SDK and its tools on the build server. In general, on a CI build server, +you want to automate the installation in some way. The automation, ideally, should not require administrative +privileges if at all possible. + +For SaaS CI solutions, there are several options. This document will cover two very popular ones, [TravisCI](https://travis-ci.org/) and +[AppVeyor](https://www.appveyor.com/). There are, of course, many other services out there, but the installation and +usage mechanisms should be similar. + +## Installation options for CI build servers + +## Using the native installers +If using installers that require administrative privileges is not something that presents a problem, native installers for +each platform can be used to set up the build server. This approach, especially in the case of Linux build servers, has +one advantage which is automatic installing of dependencies needed for the SDK to run. The native installers will also +install a system-wide version of the SDK, which may be desired; if it's not, you should look into the +[installer script usage](#using-the-installer-script) outlined below. + +Using this approach is simple. For Linux, there is a choice of using a feed-based package manager, such as `apt-get` for +Ubuntu or `yum` for CentOS, or using the packages themselves (that is, DEB or RPM). The former would require setting up the +feed that contains the packages. + +For Windows platforms, you can use the MSI. + +All of the binaries can be found on the [.NET Core getting started page](https://aka.ms/dotnetcoregs) which points to the +latest stable releases. If you wish to use newer (and potentially unstable) releases or the latest, you can use the +links from the [CLI repo](https://github.com/dotnet/cli). + +## Using the installer script +Using the installer script allows for non-administrative installation on your build server. It also allows a very easy +automation. The script itself will download the ZIP/tarball files needed and will unpack them; it will also add the +install location on the local machine to the PATH so that the tools become available for invocation immediately +post-install. + +The installer script can easily be automated at the start of the build to fetch and install the needed version of the SDK. +The "needed version" is whatever version application being built requires. You can choose the installation path so you +can install the SDK locally and then clean up after the build completes. This brings additional encapsulation and +atomicity to the build process. + +The installation script reference can be found in the [dotnet-install](dotnet-install-script.md) document. + +### Dealing with the dependencies +Using the installer script means that the native dependencies are not installed automatically and that you have to +install them if the operating system you are installing on already doesn't have them. You can see the list of prerequisites +in the [CLI repo](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md). + +## CI services setup examples +The below sections show examples of configurations using the mentioned CI SaaS offerings. + +### TravisCI + +The [travis-ci](https://travis-ci.org/) can be configured to install the .NET Core SDK using the `csharp` language and the `dotnet` key. + +Just use: + +```yaml +dotnet: 1.0.0-preview2-003121 +``` + +Travis can run both `osx` (OS X 10.11) and `linux` ( Ubuntu 14.04 ) job in a build matrix, see [example .travis.yml](https://github.com/dotnet/docs/blob/master/.travis.yml) +for more information. + +### AppVeyor + +The [appveyor.com ci](https://www.appveyor.com/) has .NET Core SDK preview2 already installed +in the build worker image `Visual Studio 2015`. + +Just use: + +```yaml +os: Visual Studio 2015 +``` + +It's possible to install a specific version of .NET Core SDK, see [example appveyor.yml](https://github.com/dotnet/docs/blob/master/appveyor.yml) +for more info. + +In the example, the .NET Core SDK binaries are downloaded, unzipped in a subdirectory and added to `PATH` env var. + +A build matrix can be added to run integration tests with multiple version of +the .NET Core SDK. + +```yaml +environment: + matrix: + - CLI_VERSION: 1.0.0-preview2-003121 + - CLI_VERSION: Latest + +install: + # .NET Core SDK binaries + - ps: $url = "https://dotnetcli.blob.core.windows.net/dotnet/preview/Binaries/$($env:CLI_VERSION)/dotnet-dev-win-x64.$($env:CLI_VERSION.ToLower()).zip" + # follow normal installation from binaries +``` + diff --git a/docs/toc.md b/docs/toc.md index 96d02aeecc4a8..4530c5aa55106 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -167,6 +167,27 @@ ### [dotnet-install-script](core/tools/dotnet-install-script.md) ### [project.json](core/tools/project-json.md) ### [global.json](core/tools/global-json.md) +## [.NET Core Tools Preview 3](core/preview3/tools/index.md) +### [High level overview of changes in CLI Preview 3](core/preview3/tools/layering.md) +### [Dependency management with .NET Core Tools Preview 3](core/preview3/tools/dependencies.md) +### [Deploying applications with .NET Core Tools Preview 3](core/preview3/deploying/index.md) +### [Telemetry](core/preview3/tools/telemetry.md) +### [Extensibility Model](core/preview3/tools/extensibility.md) +### [dotnet](core/preview3/tools/dotnet.md) +### [dotnet-new](core/preview3/tools/dotnet-new.md) +### [dotnet-migrate](core/preview3/tools/dotnet-migrate.md) +### [dotnet-restore](core/preview3/tools/dotnet-restore.md) +### [dotnet-run](core/preview3/tools/dotnet-run.md) +### [dotnet-build](core/preview3/tools/dotnet-build.md) +### [dotnet-test](core/preview3/tools/dotnet-test.md) +### [dotnet-pack](core/preview3/tools/dotnet-pack.md) +### [dotnet-publish](core/preview3/tools/dotnet-publish.md) +### [dotnet-install-script](core/preview3/tools/dotnet-install-script.md) +### [dotnet-msbuild](core/preview3/tools/dotnet-msbuild.md) +### [dotnet-nuget-delete](core/preview3/tools/dotnet-nuget-delete.md) +### [dotnet-nuget-push](core/preview3/tools/dotnet-nuget-delete.md) +### [dotnet-nuget-locals](core/preview3/tools/dotnet-nuget-locals.md) +### [global.json](core/preview3/tools/global-json.md) ## [Porting from .NET Framework](core/porting/index.md) ### [Organizing projects for .NET Core](core/porting/project-structure.md) ### [Analyzing third-party dependencies](core/porting/third-party-deps.md)