diff --git a/docs/core/tools/cli-msbuild-architecture.md b/docs/core/tools/cli-msbuild-architecture.md index f7da18bfa5ab3..59a9303f65ab0 100644 --- a/docs/core/tools/cli-msbuild-architecture.md +++ b/docs/core/tools/cli-msbuild-architecture.md @@ -24,7 +24,7 @@ Let's start with a quick refresher on Preview 2 layering as shown in the followi ![Preview 2 tools high-level architecture](media/cli-msbuild-architecture/p2-arch.png) -The layering of the tools in Preview 2 is straightforward. At the bottom, the foundation is the .NET Core CLI. All other, higher-level tools, such as Visual Studio or Visual Studio Code, depend and rely on the CLI to build projects, restore dependencies, and so on. For example, if Visual Studio wanted to perform a restore operation, it would call into the `dotnet restore` ([see note](#dotnet-restore-note)) command in the CLI. +The layering of the tools in Preview 2 is straightforward. At the bottom, the foundation is the .NET Core CLI. All other, higher-level tools, such as Visual Studio or Visual Studio Code, depend and rely on the CLI to build projects, restore dependencies, and so on. For example, if Visual Studio wanted to perform a restore operation, it would call into the `dotnet restore` command in the CLI. With the move to the new project system, the previous diagram changes: @@ -35,7 +35,7 @@ The main difference is that the CLI is not the foundational layer anymore; this > [!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. For more information, see [MSBuild tasks](/visualstudio/msbuild/msbuild-tasks). -All the toolsets now consume the shared SDK component and its targets, CLI included. For example, Visual Studio 2019 doesn't call into the `dotnet restore` ([see note](#dotnet-restore-note)) command to restore dependencies for .NET Core projects. Instead, it uses 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. +All the toolsets now consume the shared SDK component and its targets, CLI included. For example, Visual Studio 2019 doesn't call into the `dotnet restore` command to restore dependencies for .NET Core projects. Instead, it uses 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. ### CLI commands @@ -67,5 +67,6 @@ This command publishes an application into a `pub` folder using the "Release" co Notable exceptions to this rule are the `new` and `run` commands. They have not been implemented as MSBuild targets. - +### Implicit restore + [!INCLUDE[DotNet Restore Note](~/includes/dotnet-restore-note.md)] diff --git a/docs/core/tools/dotnet-add-package.md b/docs/core/tools/dotnet-add-package.md index f0caf1d718378..9be98b720a038 100644 --- a/docs/core/tools/dotnet-add-package.md +++ b/docs/core/tools/dotnet-add-package.md @@ -26,8 +26,6 @@ dotnet add package -h|--help The `dotnet add package` command provides a convenient option to add a package reference to a project file. After running the command, there's a compatibility check to ensure the package is compatible with the frameworks in the project. If the check passes, a `` element is added to the project file and [dotnet restore](dotnet-restore.md) is run. -[!INCLUDE[DotNet Restore Note](../../../includes/dotnet-restore-note.md)] - For example, adding `Newtonsoft.Json` to *ToDo.csproj* produces output similar to the following example: ```console @@ -49,6 +47,10 @@ The *ToDo.csproj* file now contains a [``](/nuget/consume-pack ``` +### Implicit restore + +[!INCLUDE[DotNet Restore Note](../../../includes/dotnet-restore-note.md)] + ## Arguments - **`PROJECT`** diff --git a/docs/core/tools/dotnet-build.md b/docs/core/tools/dotnet-build.md index cf14dba6af760..9666af5455d5d 100644 --- a/docs/core/tools/dotnet-build.md +++ b/docs/core/tools/dotnet-build.md @@ -37,10 +37,14 @@ For executable projects targeting versions earlier than .NET Core 3.0, library d For executable projects targeting .NET Core 3.0 and later, library dependencies are copied to the output folder. This means that if there isn't any other publish-specific logic (such as Web projects have), the build output should be deployable. -Building requires the *project.assets.json* file, which lists the dependencies of your application. The file is created when [`dotnet restore`](dotnet-restore.md) is executed. Without the assets file in place, the tooling can't resolve reference assemblies, which results in errors. With .NET Core 1.x SDK, you needed to explicitly run `dotnet restore` before running `dotnet build`. Starting with .NET Core 2.0 SDK, `dotnet restore` runs implicitly when you run `dotnet build`. If you want to disable implicit restore when running the build command, you can pass the `--no-restore` option. +### Implicit restore + +Building requires the *project.assets.json* file, which lists the dependencies of your application. The file is created when [`dotnet restore`](dotnet-restore.md) is executed. Without the assets file in place, the tooling can't resolve reference assemblies, which results in errors. [!INCLUDE[dotnet restore note + options](~/includes/dotnet-restore-note-options.md)] +### Executable or library output + Whether the project is executable or not is determined by the `` property in the project file. The following example shows a project that produces executable code: ```xml diff --git a/docs/core/tools/dotnet-new.md b/docs/core/tools/dotnet-new.md index 991bbf4bb48a7..4b471cef1ed11 100644 --- a/docs/core/tools/dotnet-new.md +++ b/docs/core/tools/dotnet-new.md @@ -30,6 +30,10 @@ The `dotnet new` command creates a .NET Core project or other artifacts based on The command calls the [template engine](https://github.com/dotnet/templating) to create the artifacts on disk based on the specified template and options. +### Implicit restore + +[!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)] + ## Arguments - **`TEMPLATE`** diff --git a/docs/core/tools/dotnet-pack.md b/docs/core/tools/dotnet-pack.md index 89145ebd01bc6..5caf643651ad6 100644 --- a/docs/core/tools/dotnet-pack.md +++ b/docs/core/tools/dotnet-pack.md @@ -50,6 +50,8 @@ Web projects aren't packable by default. To override the default behavior, add t ``` +### Implicit restore + [!INCLUDE[dotnet restore note + options](~/includes/dotnet-restore-note-options.md)] ## Arguments diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index d33c84e58a70f..dc16038602256 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -37,6 +37,10 @@ dotnet publish -h|--help The `dotnet publish` command's output is ready for deployment to a hosting system (for example, a server, PC, Mac, laptop) for execution. It's the only officially supported way to prepare the application for deployment. Depending on the type of deployment that the project specifies, the hosting system may or may not have the .NET Core shared runtime installed on it. For more information, see [Publish .NET Core apps with the .NET Core CLI](../deploying/deploy-with-cli.md). +### Implicit restore + +[!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)] + ### MSBuild The `dotnet publish` command calls MSBuild, which invokes the `Publish` target. Any parameters passed to `dotnet publish` are passed to MSBuild. The `-c` and `-o` parameters map to MSBuild's `Configuration` and `OutputPath` properties, respectively. diff --git a/docs/core/tools/dotnet-restore.md b/docs/core/tools/dotnet-restore.md index 1326a8ce2441b..258dac14cfde5 100644 --- a/docs/core/tools/dotnet-restore.md +++ b/docs/core/tools/dotnet-restore.md @@ -28,10 +28,23 @@ dotnet restore -h|--help 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 executed in parallel. -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 configuration file is provided when the .NET Core SDK is installed. You specify additional feeds by creating your own *nuget.config* file in the project directory. You can override the *nuget.config* feeds with the - `-s` option. +### Specify feeds + +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 configuration file is provided when the .NET Core SDK is installed. To specify additional feeds, do one of the following: + +- Create your own *nuget.config* file in the project directory. For more information, see [Common NuGet configurations](/nuget/consume-packages/configuring-nuget-behavior) and [nuget.config differences](#nugetconfig-differences) later in this article. +- Use `dotnet nuget` commands such as [`dotnet nuget add source`](dotnet-nuget-add-source.md). + +You can override the *nuget.config* feeds with the `-s` option. + +For information about how to use authenticated feeds, see [Consuming packages from authenticated feeds](/nuget/consume-packages/consuming-packages-authenticated-feeds). + +### Package cache For dependencies, you 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, which 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. +### Project-specific tooling + 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. ### nuget.config differences diff --git a/docs/core/tools/dotnet-run.md b/docs/core/tools/dotnet-run.md index 6ffe5bd9d9d90..0ae5f1be724e4 100644 --- a/docs/core/tools/dotnet-run.md +++ b/docs/core/tools/dotnet-run.md @@ -41,6 +41,8 @@ For more information on the `dotnet` driver, see the [.NET Core Command Line Too To run the application, the `dotnet run` command resolves the dependencies of the application that are outside of the shared runtime from the NuGet cache. Because it uses cached dependencies, it's not recommended to use `dotnet run` to run applications in production. Instead, [create a deployment](../deploying/index.md) using the [`dotnet publish`](dotnet-publish.md) command and deploy the published output. +### Implicit restore + [!INCLUDE[dotnet restore note + options](~/includes/dotnet-restore-note-options.md)] ## Options diff --git a/docs/core/tools/dotnet-test.md b/docs/core/tools/dotnet-test.md index cb07341841db4..3d7c70b19115d 100644 --- a/docs/core/tools/dotnet-test.md +++ b/docs/core/tools/dotnet-test.md @@ -37,6 +37,10 @@ Test projects specify the test runner using an ordinary `` ele [!code-xml[XUnit Basic Template](../../../samples/snippets/csharp/xunit-test/xunit-test.csproj)] +### Implicit restore + +[!INCLUDE[dotnet restore note](~/includes/dotnet-restore-note.md)] + ## Arguments - **`PROJECT | SOLUTION`** diff --git a/includes/dotnet-restore-note-options.md b/includes/dotnet-restore-note-options.md index 9511e1668857c..ef0a6e55b19c4 100644 --- a/includes/dotnet-restore-note-options.md +++ b/includes/dotnet-restore-note-options.md @@ -1,4 +1,7 @@ -> [!NOTE] -> Starting with .NET Core 2.0, you don't have to run [`dotnet restore`](~/docs/core/tools/dotnet-restore.md) because it's run implicitly by all commands that require a restore to occur, such as `dotnet build` and `dotnet run`. It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as [continuous integration builds in Azure DevOps Services](/azure/devops/build-release/apps/aspnet/build-aspnet-core) or in build systems that need to explicitly control the time at which the restore occurs. -> -> This command also supports the `dotnet restore` options when passed in the long form (for example, `--source`). Short form options, such as `-s`, are not supported. +You don't have to run [`dotnet restore`](~/docs/core/tools/dotnet-restore.md) because it's run implicitly by all commands that require a restore to occur, such as `dotnet new`, `dotnet build`, `dotnet run`, `dotnet test`, `dotnet publish`, and `dotnet pack`. To disable implicit restore, use the `--no-restore` option. + +The `dotnet restore` command is still useful in certain scenarios where explicitly restoring makes sense, such as [continuous integration builds in Azure DevOps Services](https://docs.microsoft.com/azure/devops/build-release/apps/aspnet/build-aspnet-core) or in build systems that need to explicitly control when the restore occurs. + +For information about how to manage NuGet feeds, see the [`dotnet restore` documentation](../docs/core/tools/dotnet-restore.md). + +This command supports the `dotnet restore` options when passed in the long form (for example, `--source`). Short form options, such as `-s`, are not supported. diff --git a/includes/dotnet-restore-note.md b/includes/dotnet-restore-note.md index 7fc5b7ff18c02..643eba7aa92eb 100644 --- a/includes/dotnet-restore-note.md +++ b/includes/dotnet-restore-note.md @@ -1,3 +1,5 @@ -> [!NOTE] -> Starting with .NET Core 2.0 SDK, you don't have to run [`dotnet restore`](~/docs/core/tools/dotnet-restore.md) because it's run implicitly by all commands that require a restore to occur, such as `dotnet new`, `dotnet build` and `dotnet run`. -> It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as [continuous integration builds in Azure DevOps Services](https://docs.microsoft.com/azure/devops/build-release/apps/aspnet/build-aspnet-core) or in build systems that need to explicitly control the time at which the restore occurs. +You don't have to run [`dotnet restore`](~/docs/core/tools/dotnet-restore.md) because it's run implicitly by all commands that require a restore to occur, such as `dotnet new`, `dotnet build`, `dotnet run`, `dotnet test`, `dotnet publish`, and `dotnet pack`. To disable implicit restore, use the `--no-restore` option. + +The `dotnet restore` command is still useful in certain scenarios where explicitly restoring makes sense, such as [continuous integration builds in Azure DevOps Services](https://docs.microsoft.com/azure/devops/build-release/apps/aspnet/build-aspnet-core) or in build systems that need to explicitly control when the restore occurs. + +For information about how to manage NuGet feeds, see the [`dotnet restore` documentation](../docs/core/tools/dotnet-restore.md).