diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 2cb451e6c6909..573b0fbb043b1 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -333,7 +333,7 @@ }, { "source_path": "docs/core/preview3/tutorials/using-with-xplat-cli-msbuild.md", - "redirect_url": "/dotnet/core/tutorials/using-with-xplat-cli", + "redirect_url": "/dotnet/core/tutorials/cli-create-console-app", "redirect_document_id": true }, { @@ -377,6 +377,10 @@ "source_path": "docs/core/tutorials/using-on-windows-full-solution.md", "redirect_url": "/dotnet/core/tutorials/with-visual-studio" }, + { + "source_path": "docs/core/tutorials/using-with-xplat-cli.md", + "redirect_url": "/dotnet/core/tutorials/cli-create-console-app" + }, { "source_path": "docs/core/versions/install-management.md", "redirect_url": "/dotnet/core/versions/remove-runtime-sdk-versions" diff --git a/docs/core/get-started.md b/docs/core/get-started.md index 300942e5bdfc1..a28996968f1e7 100644 --- a/docs/core/get-started.md +++ b/docs/core/get-started.md @@ -45,7 +45,7 @@ You can get started developing .NET Core applications by following these step-by - [Build a class library with Visual Basic and .NET Core in Visual Studio 2017.](./tutorials/vb-library-with-visual-studio.md) - Watch a video on [how to install and use Visual Studio Code and .NET Core](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-using-CSharp-and-NET-Core/). - Watch a video on [how to install and use Visual Studio 2017 and .NET Core](https://channel9.msdn.com/Blogs/dotnet/Get-Started-NET-Core-Visual-Studio-2017/). -- [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md) +- [Getting started with .NET Core using the command-line.](tutorials/cli-create-console-app.md) See the [.NET Core dependencies and requirements](install/dependencies.md?tabs=netcore30&pivots=os-windows) article for a list of the supported Windows versions. @@ -53,7 +53,7 @@ See the [.NET Core dependencies and requirements](install/dependencies.md?tabs=n You can get started developing .NET Core application by following these step-by-step tutorials: -- [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md) +- [Getting started with .NET Core using the command-line.](tutorials/cli-create-console-app.md) - Watch a video on [getting started with Visual Studio Code using C# and .NET Core on Ubuntu](https://channel9.msdn.com/Blogs/dotnet/Get-started-with-VS-Code-Csharp-dotnet-Core-Ubuntu). See the [.NET Core dependencies and requirements](install/dependencies.md?tabs=netcore30&pivots=os-linux) article for a list of the supported Linux distros and versions. @@ -64,7 +64,7 @@ You can get started developing .NET Core application by following these step-by- - Watch a video on [Getting started with Visual Studio Code using C# and .NET Core on macOS](https://channel9.msdn.com/Blogs/dotnet/Get-started-VSCode-NET-Core-Mac). - [Getting started with .NET Core on macOS, using Visual Studio Code.](tutorials/using-on-macos.md) -- [Getting started with .NET Core using the command-line.](tutorials/using-with-xplat-cli.md) +- [Getting started with .NET Core using the command-line.](tutorials/cli-create-console-app.md) - [Getting started with .NET Core on macOS using Visual Studio for Mac.](tutorials/using-on-mac-vs.md) - [Build a complete .NET Core solution on macOS using Visual Studio for Mac.](tutorials/using-on-mac-vs-full-solution.md) diff --git a/docs/core/toc.yml b/docs/core/toc.yml index e3e46623c3458..b178b57b9acba 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -96,7 +96,7 @@ - name: Build a complete .NET Core solution on macOS href: tutorials/using-on-mac-vs-full-solution.md - name: Get started with .NET Core using the CLI tools - href: tutorials/using-with-xplat-cli.md + href: tutorials/cli-create-console-app.md - name: Organize and test projects with the .NET Core CLI href: tutorials/testing-with-cli.md - name: Develop libraries with cross-platform tools diff --git a/docs/core/tutorials/cli-create-console-app.md b/docs/core/tutorials/cli-create-console-app.md new file mode 100644 index 0000000000000..11f3927948684 --- /dev/null +++ b/docs/core/tutorials/cli-create-console-app.md @@ -0,0 +1,193 @@ +--- +title: Get started with .NET Core using the CLI - .NET Core CLI +description: A step-by-step tutorial showing how to get started with .NET Core on Windows, Linux, or macOS using the .NET Core command-line interface (CLI). +author: thraka +ms.author: adegeo +ms.date: 12/05/2019 +ms.technology: dotnet-cli +ms.custom: "seodec18,updateeachrelease" +--- +# Get started with .NET Core on Windows/Linux/macOS using the command line + +This article will show you how to start developing cross-platforms apps in your machine using the .NET Core CLI tools. + +If you're unfamiliar with the .NET Core CLI toolset, read the [.NET Core SDK overview](../tools/index.md). + +## Prerequisites + +- [.NET Core SDK 3.1](https://dotnet.microsoft.com/download) or later versions. +- A text editor or code editor of your choice. + +## Hello, Console App! + +You can [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/console-apps/HelloMsBuild) from the dotnet/samples GitHub repository. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#viewing-and-downloading-samples). + +Open a command prompt and create a folder named *Hello*. Navigate to the folder you created and type the following: + +```dotnetcli +dotnet new console +dotnet run +``` + +Let's do a quick walkthrough: + +01. `dotnet new console` + + [dotnet new](../tools/dotnet-new.md) creates an up-to-date *Hello.csproj* project file with the dependencies necessary to build a console app. It also creates a *Program.cs*, a basic file containing the entry point for the application. + + *Hello.csproj*: + + [!code-xml[Hello.csproj](~/samples/core/console-apps/HelloMsBuild/Hello.csproj)] + + The project file specifies everything that's needed to restore dependencies and build the program. + + - The `` element specifies that we're building an executable, in other words a console application. + - The `` element specifies what .NET implementation we're targeting. In an advanced scenario, you can specify multiple target frameworks and build to all those in a single operation. In this tutorial, we'll stick to building only for .NET Core 3.1. + + *Program.cs*: + + [!code-csharp[Program.cs](~/samples/core/console-apps/HelloMsBuild/Program.cs)] + + The program starts by `using System`, which means "bring everything in the `System` namespace into scope for this file". The `System` namespace includes the `Console` class. + + We then define a namespace called `Hello`. You can change this to anything you want. A class named `Program` is defined within that namespace, with a `Main` method that takes an array of strings named `args`. This array contains the list of arguments passed in when the program is run. As it is, this array is not used and the program simply writes the text "Hello World!" to the console. Later, we'll make changes to the code that will make use of this argument. + + `dotnet new` calls [dotnet restore](../tools/dotnet-restore.md) implicitly. `dotnet restore` calls into [NuGet](https://www.nuget.org/) (.NET package manager) to restore the tree of dependencies. NuGet analyzes the *Hello.csproj* file, downloads the dependencies defined in the file (or grabs them from a cache on your machine), and writes the *obj/project.assets.json* file, which is necessary to compile and run the sample. + +02. `dotnet run` + + [dotnet run](../tools/dotnet-run.md) calls [dotnet build](../tools/dotnet-build.md) to ensure that the build targets have been built, and then calls `dotnet ` to run the target application. + + ```console + dotnet run + + Hello World! + ``` + + Alternatively, you can also run `dotnet build` to compile the code without running the build console applications. This results in a compiled application, as a DLL file, based on the name of the project. In this case, the file created is named *Hello.dll*. This app can be run with `dotnet bin\Debug\netcoreapp3.1\Hello.dll` on Windows (use `/` for non-Windows systems). + + ```console + dotnet bin\Debug\netcoreapp3.1\Hello.dll + + Hello World! + ``` + + When the app is compiled, an operating system-specific executable was created along with the `Hello.dll`. On Windows, this would be `Hello.exe`; on Linux or macOS, this would be `hello`. With the example above, the file is named with `Hello.exe` or `Hello`. You can run that executable directly. + + ```console + .\bin\Debug\netcoreapp3.1\Hello.exe + + Hello World! + ``` + +## Modify the program + +Let's change the program a bit. Fibonacci numbers are fun, so let's add that and also to use the argument to greet the person running the app. + +01. Replace the contents of your *Program.cs* file with the following code: + + [!code-csharp[Fibonacci](~/samples/core/console-apps/fibonacci-msbuild/Program.cs)] + +02. Run [dotnet build](../tools/dotnet-build.md) to compile the changes. + +03. Run the program passing a parameter to the app. When you use the `dotnet` command to run an app, add `--` to the end. Anything to the right of `--` will be passed as a parameter to the app. In the following example, the value `John` is passed to the app. + + ```console + $ dotnet run -- John + Hello John! + Fibonacci Numbers 1-15: + 1: 0 + 2: 1 + 3: 1 + 4: 2 + 5: 3 + 6: 5 + 7: 8 + 8: 13 + 9: 21 + 10: 34 + 11: 55 + 12: 89 + 13: 144 + 14: 233 + 15: 377 + ``` + +And that's it! You can modify *Program.cs* any way you like. + +## Working with multiple files + +Single files are fine for simple one-off programs, but if you're building a more complex app, you're probably going to have multiple code files on your project. Let's build off of the previous Fibonacci example by caching some Fibonacci values and add some recursive features. + +01. Add a new file inside the *Hello* directory named *FibonacciGenerator.cs* with the following code: + + [!code-csharp[Fibonacci Generator](~/samples/core/console-apps/FibonacciBetterMsBuild/FibonacciGenerator.cs)] + +02. Change the `Main` method in your *Program.cs* file to instantiate the new class and call its method as in the following example: + + [!code-csharp[New Program.cs](~/samples/core/console-apps/FibonacciBetterMsBuild/Program.cs)] + +03. Run [dotnet build](../tools/dotnet-build.md) to compile the changes. + +04. Run your app by executing [dotnet run](../tools/dotnet-run.md). The following shows the program output: + + ```console + $ dotnet run + 0 + 1 + 1 + 2 + 3 + 5 + 8 + 13 + 21 + 34 + 55 + 89 + 144 + 233 + 377 + ``` + +## Publish your app + +Once you're ready to distribute your app, use the [dotnet publish](../tools/dotnet-publish.md) command to generate the _publish_ folder at _bin\\debug\\netcoreapp3.1\\publish\\_ (use `/` for non-Windows systems). You can distribute the contents of the _publish_ folder to other platforms as long as they've already installed the dotnet runtime. + +```console +dotnet publish +Microsoft (R) Build Engine version 16.4.0+e901037fe for .NET Core +Copyright (C) Microsoft Corporation. All rights reserved. + + Restore completed in 20 ms for C:\Code\Temp\Hello\Hello.csproj. + Hello -> C:\Code\Temp\Hello\bin\Debug\netcoreapp3.1\Hello.dll + Hello -> C:\Code\Temp\Hello\bin\Debug\netcoreapp3.1\publish\ +``` + +The output above may differ based on your current folder and operating system, but the output should be similar. + +You can run your published app with the [dotnet](../tools/dotnet.md) command: + +```console +dotnet bin\Debug\netcoreapp3.1\publish\Hello.dll + +Hello World! +``` + +As mentioned at the start of this article, an operating system-specific executable was created along with the `Hello.dll`. On Windows, this would be `Hello.exe`; on Linux or macOS, this would be `hello`. With the example above, the file is named with `Hello.exe` or `Hello`. You can run this published executable directly. + +```console +.\bin\Debug\netcoreapp3.1\Hello.exe + +Hello World! +``` + +## Conclusion + +And that's it! Now, you can start using the basic concepts learned here to create your own programs. + +## See also + +- [Organizing and testing projects with the .NET Core CLI tools](testing-with-cli.md) +- [Publish .NET Core apps with the CLI](../deploying/deploy-with-cli.md) +- [Learn more about app deployment](../deploying/index.md) diff --git a/docs/core/tutorials/index.md b/docs/core/tutorials/index.md index 26635e2de231d..495f4949e8dbb 100644 --- a/docs/core/tutorials/index.md +++ b/docs/core/tutorials/index.md @@ -33,7 +33,7 @@ The following tutorials are available for learning about .NET Core. ## Building applications with the .NET Core CLI tools -- [Get started with .NET Core on Windows/Linux/macOS using the .NET Core CLI tools](using-with-xplat-cli.md) +- [Get started with .NET Core on Windows/Linux/macOS using the .NET Core CLI tools](cli-create-console-app.md) - [Organizing and testing projects with the .NET Core CLI tools](testing-with-cli.md) - [Get started with F#](../../fsharp/get-started/get-started-command-line.md) diff --git a/docs/core/tutorials/testing-with-cli.md b/docs/core/tutorials/testing-with-cli.md index 55737276745f2..7b3916855e73f 100644 --- a/docs/core/tutorials/testing-with-cli.md +++ b/docs/core/tutorials/testing-with-cli.md @@ -8,7 +8,7 @@ ms.custom: "seodec18" # Organizing and testing projects with the .NET Core command line -This tutorial follows [Get started with .NET Core on Windows/Linux/macOS using the command line](using-with-xplat-cli.md), taking you beyond the creation of a simple console app to develop advanced and well-organized applications. After showing you how to use folders to organize your code, this tutorial shows you how to extend a console application with the [xUnit](https://xunit.github.io/) testing framework. +This tutorial follows [Get started with .NET Core on Windows/Linux/macOS using the command line](cli-create-console-app.md), taking you beyond the creation of a simple console app to develop advanced and well-organized applications. After showing you how to use folders to organize your code, this tutorial shows you how to extend a console application with the [xUnit](https://xunit.github.io/) testing framework. ## Using folders to organize code diff --git a/docs/core/tutorials/using-with-xplat-cli.md b/docs/core/tutorials/using-with-xplat-cli.md deleted file mode 100644 index a9d05302d4cfc..0000000000000 --- a/docs/core/tutorials/using-with-xplat-cli.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Get started with .NET Core using the CLI -description: A step-by-step tutorial showing how to get started with .NET Core on Windows, Linux, or macOS using the .NET Core command-line interface (CLI). -author: thraka -ms.author: adegeo -ms.date: 08/07/2019 -ms.technology: dotnet-cli -ms.custom: "seodec18" ---- -# Get started with .NET Core on Windows/Linux/macOS using the command line - -This topic will show you how to start developing cross-platforms apps in your machine using the .NET Core CLI tools. - -If you're unfamiliar with the .NET Core CLI toolset, read the [.NET Core SDK overview](../tools/index.md). - -## Prerequisites - -- [.NET Core SDK 2.1](https://dotnet.microsoft.com/download) or later versions. -- A text editor or code editor of your choice. - -## Hello, Console App! - -You can [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/console-apps/HelloMsBuild) from the dotnet/samples GitHub repository. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#viewing-and-downloading-samples). - -Open a command prompt and create a folder named *Hello*. Navigate to the folder you created and type the following: - -```dotnetcli -dotnet new console -dotnet run -``` - -Let's do a quick walkthrough: - -1. `dotnet new console` - - [`dotnet new`](../tools/dotnet-new.md) creates an up-to-date *Hello.csproj* project file with the dependencies necessary to build a console app. It also creates a *Program.cs*, a basic file containing the entry point for the application. - - *Hello.csproj*: - - [!code-xml[Hello.csproj](~/samples/core/console-apps/HelloMsBuild/Hello.csproj)] - - The project file specifies everything that's needed to restore dependencies and build the program. - - - The `OutputType` tag specifies that we're building an executable, in other words a console application. - - The `TargetFramework` tag specifies what .NET implementation we're targeting. In an advanced scenario, you can specify multiple target frameworks and build to all those in a single operation. In this tutorial, we'll stick to building only for .NET Core 2.1. - - *Program.cs*: - - [!code-csharp[Program.cs](~/samples/core/console-apps/HelloMsBuild/Program.cs)] - - The program starts by `using System`, which means "bring everything in the `System` namespace into scope for this file". The `System` namespace includes the `Console` class. - - We then define a namespace called `Hello`. You can change this to anything you want. A class named `Program` is defined within that namespace, with a `Main` method that takes an array of strings as its argument. This array contains the list of arguments passed in when the compiled program is called. As it is, this array is not used: all the program is doing is to write "Hello World!" to the console. Later, we'll make changes to the code that will make use of this argument. - - [!INCLUDE[DotNet Restore Note](~/includes/dotnet-restore-note.md)] - - `dotnet new` calls [`dotnet restore`](../tools/dotnet-restore.md) implicitly. `dotnet restore` calls into [NuGet](https://www.nuget.org/) (.NET package manager) to restore the tree of dependencies. NuGet analyzes the *Hello.csproj* file, downloads the dependencies defined in the file (or grabs them from a cache on your machine), and writes the *obj/project.assets.json* file, which is necessary to compile and run the sample. - - > [!IMPORTANT] - > If you're using a .NET Core 1.x version of the SDK, you'll have to call `dotnet restore` yourself after calling `dotnet new`. - -2. `dotnet run` - - [`dotnet run`](../tools/dotnet-run.md) calls [`dotnet build`](../tools/dotnet-build.md) to ensure that the build targets have been built, and then calls `dotnet ` to run the target application. - - ```console - $ dotnet run - Hello World! - ``` - - Alternatively, you can also execute [`dotnet build`](../tools/dotnet-build.md) to compile the code without running the build console applications. This results in a compiled application as a DLL file that can be run with `dotnet bin\Debug\netcoreapp2.1\Hello.dll` on Windows (use `/` for non-Windows systems). You may also specify arguments to the application as you'll see later on the topic. - - ```console - $ dotnet bin\Debug\netcoreapp2.1\Hello.dll - Hello World! - ``` - - As an advanced scenario, it's possible to build the application as a self-contained set of platform-specific files that can be deployed and run to a machine that doesn't necessarily have .NET Core installed. See [.NET Core Application Deployment](../deploying/index.md) for details. - -### Augmenting the program - -Let's change the program a bit. Fibonacci numbers are fun, so let's add that in addition to use the argument to greet the person running the app. - -1. Replace the contents of your *Program.cs* file with the following code: - - [!code-csharp[Fibonacci](../../../samples/core/console-apps/fibonacci-msbuild/Program.cs)] - -2. Execute [`dotnet build`](../tools/dotnet-build.md) to compile the changes. - -3. Run the program passing a parameter to the app: - - ```console - $ dotnet run -- John - Hello John! - Fibonacci Numbers 1-15: - 1: 0 - 2: 1 - 3: 1 - 4: 2 - 5: 3 - 6: 5 - 7: 8 - 8: 13 - 9: 21 - 10: 34 - 11: 55 - 12: 89 - 13: 144 - 14: 233 - 15: 377 - ``` - -And that's it! You can augment *Program.cs* any way you like. - -## Working with multiple files - -Single files are fine for simple one-off programs, but if you're building a more complex app, you're probably going to have multiple source files on your project. -Let's build off of the previous Fibonacci example by caching some Fibonacci values and add some recursive features. - -1. Add a new file inside the *Hello* directory named *FibonacciGenerator.cs* with the following code: - - [!code-csharp[Fibonacci Generator](~/samples/core/console-apps/FibonacciBetterMsBuild/FibonacciGenerator.cs)] - -2. Change the `Main` method in your *Program.cs* file to instantiate the new class and call its method as in the following example: - - [!code-csharp[New Program.cs](~/samples/core/console-apps/FibonacciBetterMsBuild/Program.cs)] - -3. Execute [`dotnet build`](../tools/dotnet-build.md) to compile the changes. - -4. Run your app by executing [`dotnet run`](../tools/dotnet-run.md). The following shows the program output: - - ```console - $ dotnet run - 0 - 1 - 1 - 2 - 3 - 5 - 8 - 13 - 21 - 34 - 55 - 89 - 144 - 233 - 377 - ``` - -## Publish your app - -Once you're ready to distribute your app, use the [`dotnet publish`](../tools/dotnet-publish.md) command to generate the _publish_ folder at _bin\\debug\\netcoreapp2.1\\publish\\_ (use `/` for non-Windows systems). You can distribute the contents of the _publish_ folder to other platforms as long as they've already installed the dotnet runtime. - -You can run your published app with the [dotnet](../tools/dotnet.md) command: - -```console -$ dotnet bin\Debug\netcoreapp2.1\publish\Hello.dll -Hello World! -``` - -## Conclusion - -And that's it! Now, you can start using the basic concepts learned here to create your own programs. - -## See also - -- [Organizing and testing projects with the .NET Core CLI tools](testing-with-cli.md) -- [Publish .NET Core apps with the CLI](../deploying/deploy-with-cli.md) -- [Learn more about app deployment](../deploying/index.md) diff --git a/docs/csharp/programming-guide/main-and-command-args/main-return-values.md b/docs/csharp/programming-guide/main-and-command-args/main-return-values.md index e9b40244a7715..2f760322c538e 100644 --- a/docs/csharp/programming-guide/main-and-command-args/main-return-values.md +++ b/docs/csharp/programming-guide/main-and-command-args/main-return-values.md @@ -21,7 +21,7 @@ If the return value from `Main` is not used, returning `void` allows for slightl ## Example -This example uses [.NET Core](../../../core/index.md) command line tools. If you are unfamiliar with .NET Core command line tools, you can learn about them in this [Get started topic](../../../core/tutorials/using-with-xplat-cli.md). +This example uses [.NET Core](../../../core/index.md) command line tools. If you are unfamiliar with .NET Core command line tools, you can learn about them in this [Get started topic](../../../core/tutorials/cli-create-console-app.md). Modify the `Main` method in *program.cs* as follows: diff --git a/docs/csharp/tour-of-csharp/program-structure.md b/docs/csharp/tour-of-csharp/program-structure.md index 4f4648442b266..ecdfaf199b97f 100644 --- a/docs/csharp/tour-of-csharp/program-structure.md +++ b/docs/csharp/tour-of-csharp/program-structure.md @@ -22,7 +22,7 @@ csc /t:library acme.cs compiles the example as a library (code without a `Main` entry point) and produces an assembly named `acme.dll`. > [!IMPORTANT] -> The examples above use `csc` as the command line C# compiler. This compiler is a Windows executable. To use C# across other platforms, you should use the tools for .NET Core. The .NET Core ecosystem uses the `dotnet` CLI to manage command line builds. This includes managing dependencies, and invoking the C# compiler. See [this tutorial](../../core/tutorials/using-with-xplat-cli.md) for a full description of those tools on the platforms supported by .NET Core. +> The examples above use `csc` as the command line C# compiler. This compiler is a Windows executable. To use C# across other platforms, you should use the tools for .NET Core. The .NET Core ecosystem uses the `dotnet` CLI to manage command line builds. This includes managing dependencies, and invoking the C# compiler. See [this tutorial](../../core/tutorials/cli-create-console-app.md) for a full description of those tools on the platforms supported by .NET Core. Assemblies contain executable code in the form of Intermediate Language (IL) instructions, and symbolic information in the form of metadata. Before it is executed, the IL code in an assembly is automatically converted to processor-specific code by the Just-In-Time (JIT) compiler of .NET Common Language Runtime. diff --git a/docs/samples-and-tutorials/index.md b/docs/samples-and-tutorials/index.md index 31dd462868018..14bfb68fc39e6 100644 --- a/docs/samples-and-tutorials/index.md +++ b/docs/samples-and-tutorials/index.md @@ -20,7 +20,7 @@ This guide shows you how to create an ASP.NET Core web app and associated unit t ### Tutorials -**[Writing .NET Core console apps using the CLI tools: A step-by-step guide](../core/tutorials/using-with-xplat-cli.md)** +**[Writing .NET Core console apps using the CLI tools: A step-by-step guide](../core/tutorials/cli-create-console-app.md)** This guide shows you how to use the .NET Core CLI tooling to build cross-platform console apps. It starts with a basic console app and eventually spans multiple projects, including testing. You add features step-by-step, building your knowledge as you go. The [completed sample](https://github.com/dotnet/samples/tree/master/core/console-apps) is available in the dotnet/samples repository on GitHub.