From ac27d93d1aa751d9a6a7c6b9e25acf40b89bf8c5 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Mon, 6 Feb 2023 16:25:05 -0500 Subject: [PATCH] Tooling article versioning (#28314) --- aspnetcore/blazor/tooling.md | 1001 +++++++--------------------------- 1 file changed, 188 insertions(+), 813 deletions(-) diff --git a/aspnetcore/blazor/tooling.md b/aspnetcore/blazor/tooling.md index e860dd67b3..53af8c8727 100644 --- a/aspnetcore/blazor/tooling.md +++ b/aspnetcore/blazor/tooling.md @@ -13,18 +13,26 @@ zone_pivot_groups: operating-systems This article describes tools for building Blazor apps on various platforms. -:::moniker range=">= aspnetcore-7.0" - :::zone pivot="windows" -1. Install the latest version of [Visual Studio 2022](https://visualstudio.microsoft.com) with the **ASP.NET and web development** workload. +1. Install the latest version of [Visual Studio](https://visualstudio.microsoft.com) with the **ASP.NET and web development** workload. 1. Create a new project. +:::moniker range=">= aspnetcore-7.0" + 1. For a Blazor Server experience, choose the **Blazor Server App** template, which includes demonstration code and [Bootstrap](https://getbootstrap.com/), or the **Blazor Server App Empty** template without demonstration code and Bootstrap. Select **Next**. For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template, which includes demonstration code and Bootstrap, or the **Blazor WebAssembly App Empty** template without demonstration code and Bootstrap. +:::moniker-end + +:::moniker range="< aspnetcore-7.0" + +1. For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Next**. + +:::moniker-end + 1. Provide a **Project name** and confirm that the **Location** is correct. Select **Next**. 1. In the **Additional information** dialog, select the **ASP.NET Core Hosted** checkbox for a hosted Blazor WebAssembly app. Select **Create**. @@ -56,6 +64,8 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm 1. Install the latest [C# for Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp). +:::moniker range=">= aspnetcore-7.0" + 1. For a Blazor Server experience with demonstration code and [Bootstrap](https://getbootstrap.com/), execute the following command: ```dotnetcli @@ -94,6 +104,32 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . +:::moniker-end + +:::moniker range="< aspnetcore-7.0" + +1. For a Blazor WebAssembly experience, execute the following command: + + ```dotnetcli + dotnet new blazorwasm -o WebApplication1 + ``` + + For a hosted Blazor WebAssembly experience, add the hosted option (`-ho` or `--hosted`) option to the command: + + ```dotnetcli + dotnet new blazorwasm -o WebApplication1 -ho + ``` + + For a Blazor Server experience, execute the following command: + + ```dotnetcli + dotnet new blazorserver -o WebApplication1 + ``` + + For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . + +:::moniker-end + 1. Open the `WebApplication1` folder in Visual Studio Code. 1. The IDE requests that you add assets to build and debug the project. Select **Yes**. @@ -102,6 +138,9 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm `.vscode/launch.json` (configured for launch and debug of a Blazor WebAssembly app): + +:::moniker range=">= aspnetcore-6.0" + ```json { "version": "0.2.0", @@ -142,12 +181,69 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm } ``` +:::moniker-end + +:::moniker range="< aspnetcore-6.0" + + ```json + { + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "type": "blazorwasm", + "name": "Launch and Debug Blazor WebAssembly Application", + "request": "launch", + "cwd": "${workspaceFolder}", + "browser": "edge" + } + ] + } + ``` + + `.vscode/tasks.json`: + + ```json + { + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "dotnet", + "type": "shell", + "args": [ + "build", + // Ask dotnet build to generate full paths for file names. + "/property:GenerateFullPaths=true", + // Do not generate summary otherwise it leads to duplicate errors in Problems panel + "/consoleloggerparameters:NoSummary", + ], + "group": "build", + "presentation": { + "reveal": "silent" + }, + "problemMatcher": "$msCompile" + } + ] + } + ``` + +:::moniker-end + +:::moniker range=">= aspnetcore-6.0" + The project's `Properties/launchSettings.json` file includes the `inspectUri` property for the debugging proxy for any profiles in the `profiles` section of the file: ```json "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}", ``` +:::moniker-end + **Hosted Blazor WebAssembly launch and task configuration** For hosted Blazor WebAssembly [solutions](#visual-studio-solution-file-sln), add (or move) the `.vscode` folder with `launch.json` and `tasks.json` files to the solution's parent folder, which is the folder that contains the typical project folders: :::no-loc text="Client":::, :::no-loc text="Server":::, and `Shared`. Update or confirm that the configuration in the `launch.json` and `tasks.json` files execute a hosted Blazor WebAssembly app from the **:::no-loc text="Server":::** project. @@ -155,6 +251,8 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm > [!IMPORTANT] > When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. +:::moniker range=">= aspnetcore-6.0" + Examine the `Properties/launchSettings.json` file and determine the URL of the app from the `applicationUrl` property (for example, `https://localhost:7268`). Note this value for use in the `launch.json` file. In the launch configuration of the `.vscode/launch.json` file: @@ -248,6 +346,60 @@ Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute comm > > You can't automatically rebuild the backend **:::no-loc text="Server":::** app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with [`dotnet watch run`](xref:tutorials/dotnet-watch). +:::moniker-end + +:::moniker range="< aspnetcore-6.0" + + **`.vscode/launch.json`** (`launch` configuration): + + ```json + ... + "cwd": "${workspaceFolder}/{SERVER APP FOLDER}", + ... + ``` + + In the preceding configuration for the current working directory (`cwd`), the `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". + + If Microsoft Edge is used and Google Chrome isn't installed on the system, add an additional property of `"browser": "edge"` to the configuration. + + Example for a project folder of :::no-loc text="Server"::: and that spawns Microsoft Edge as the browser for debug runs instead of the default browser Google Chrome: + + ```json + ... + "cwd": "${workspaceFolder}/Server", + "browser": "edge" + ... + ``` + + **`.vscode/tasks.json`** ([`dotnet` command](/dotnet/core/tools/dotnet) arguments): + + ```json + ... + "${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj", + ... + ``` + + In the preceding argument: + + * The `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". + * The `{PROJECT NAME}` placeholder is the app's name, typically based on the solution's name followed by "`.Server`" in an app generated from the [Blazor project template](xref:blazor/project-structure). + + The following example from the [tutorial for using SignalR with a Blazor WebAssembly app](xref:blazor/tutorials/signalr-blazor) uses a project folder name of :::no-loc text="Server"::: and a project name of `BlazorWebAssemblySignalRApp.Server`: + + ```json + ... + "args": [ + "build", + "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj", + ... + ], + ... + ``` + +1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. + +:::moniker-end + ## Trust a development certificate For more information, see . @@ -260,6 +412,8 @@ For more information, see **App**. For a Blazor Server experience, choose the **Blazor Server App** template, which includes demonstration code and [Bootstrap](https://getbootstrap.com/), or the **Blazor Server App Empty** template without demonstration code and Bootstrap. Select **Continue**. @@ -268,6 +422,18 @@ For more information, see . +:::moniker-end + +:::moniker range="< aspnetcore-7.0" + +1. In the sidebar, select **Web and Console** > **App**. + + For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Continue**. + + For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . + +:::moniker-end + 1. Confirm that **Authentication** is set to **No Authentication**. Select **Continue**. 1. For a hosted Blazor WebAssembly experience, select the **ASP.NET Core Hosted** checkbox. @@ -319,9 +485,20 @@ For more information, see the following resources in the Visual Studio documenta The Blazor framework provides templates for creating new apps for each of the two Blazor hosting models. The templates are used to create new Blazor projects and solutions regardless of the tooling that you select for Blazor development (Visual Studio, Visual Studio for Mac, Visual Studio Code, or the [.NET command-line interface (CLI)](/dotnet/core/tools/)): +:::moniker range=">= aspnetcore-7.0" + * Blazor Server project templates: `blazorserver`, `blazorserver-empty` * Blazor WebAssembly project templates: `blazorwasm`, `blazorwasm-empty` +:::moniker-end + +:::moniker range="< aspnetcore-7.0" + +* Blazor Server project template: `blazorserver` +* Blazor WebAssembly project template: `blazorwasm` + +:::moniker-end + For more information on Blazor's hosting models, see . For more information on Blazor project templates, see . For more information on template options, see the following resources: @@ -335,6 +512,8 @@ For more information on template options, see the following resources: ## .NET WebAssembly build tools +:::moniker range=">= aspnetcore-7.0" + The .NET WebAssembly build tools are based on [Emscripten](https://emscripten.org/), a compiler toolchain for the web platform. To install the build tools, use ***either*** of the following approaches: * For the **ASP.NET and web development** workload in the Visual Studio installer, select the **.NET WebAssembly build tools** option from the list of optional components. @@ -374,316 +553,10 @@ For more information, see the following resources: * [Runtime relinking](xref:blazor/host-and-deploy/webassembly#runtime-relinking) * -## Additional resources - -* [.NET command-line interface (CLI)](/dotnet/core/tools/) -* -* -* -* - :::moniker-end :::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0" -:::zone pivot="windows" - -1. Install the latest version of [Visual Studio 2022](https://visualstudio.microsoft.com) with the **ASP.NET and web development** workload. - -1. Create a new project. - -1. For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Next**. - -1. Provide a **Project name** and confirm that the **Location** is correct. Select **Next**. - -1. In the **Additional information** dialog, select the **ASP.NET Core Hosted** checkbox for a hosted Blazor WebAssembly app. Select **Create**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - - When running a hosted Blazor WebAssembly [solution](#visual-studio-solution-file-sln) in Visual Studio, the startup project of the solution is the **:::no-loc text="Server":::** project. - -For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -> [!IMPORTANT] -> When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -:::zone pivot="linux" - -Use the [.NET command-line interface (CLI)](/dotnet/core/tools/) to execute commands in a Linux command shell. - -1. Install the latest version of the [.NET Core SDK](https://dotnet.microsoft.com/download). If you previously installed the SDK, you can determine your installed version by executing the following command: - - ```dotnetcli - dotnet --version - ``` - -1. Install the latest version of [Visual Studio Code](https://code.visualstudio.com). - -1. Install the latest [C# for Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp). - -1. For a Blazor WebAssembly experience, execute the following command: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 - ``` - - For a hosted Blazor WebAssembly experience, add the hosted option (`-ho` or `--hosted`) option to the command: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 -ho - ``` - - For a Blazor Server experience, execute the following command: - - ```dotnetcli - dotnet new blazorserver -o WebApplication1 - ``` - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Open the `WebApplication1` folder in Visual Studio Code. - -1. The IDE requests that you add assets to build and debug the project. Select **Yes**. - - If Visual Studio Code doesn't offer to create the assets automatically, use the following files: - - `.vscode/launch.json` (configured for launch and debug of a Blazor WebAssembly app): - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "type": "blazorwasm", - "name": "Launch and Debug Blazor WebAssembly Application", - "request": "launch", - "cwd": "${workspaceFolder}", - "browser": "edge" - } - ] - } - ``` - - `.vscode/tasks.json`: - - ```json - { - "version": "2.0.0", - "tasks": [ - { - "label": "build", - "command": "dotnet", - "type": "shell", - "args": [ - "build", - "/property:GenerateFullPaths=true", - "/consoleloggerparameters:NoSummary", - ], - "group": "build", - "presentation": { - "reveal": "silent" - }, - "problemMatcher": "$msCompile" - } - ] - } - ``` - - The project's `Properties/launchSettings.json` file includes the `inspectUri` property for the debugging proxy for any profiles in the `profiles` section of the file: - - ```json - "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}", - ``` - - **Hosted Blazor WebAssembly launch and task configuration** - - For hosted Blazor WebAssembly [solutions](#visual-studio-solution-file-sln), add (or move) the `.vscode` folder with `launch.json` and `tasks.json` files to the solution's parent folder, which is the folder that contains the typical project folders: :::no-loc text="Client":::, :::no-loc text="Server":::, and `Shared`. Update or confirm that the configuration in the `launch.json` and `tasks.json` files execute a hosted Blazor WebAssembly app from the **:::no-loc text="Server":::** project. - - > [!IMPORTANT] - > When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - - Examine the `Properties/launchSettings.json` file and determine the URL of the app from the `applicationUrl` property (for example, `https://localhost:7268`). Note this value for use in the `launch.json` file. - - In the launch configuration of the `.vscode/launch.json` file: - - * Set the current working directory (`cwd`) to the **:::no-loc text="Server":::** project folder. - * Indicate the app's URL with the `url` property. Use the value recorded earlier from the `Properties/launchSettings.json` file. - - ```json - "cwd": "${workspaceFolder}/{SERVER APP FOLDER}", - "url": "{URL}" - ``` - - In the preceding configuration: - - * The `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically :::no-loc text="Server":::. - * The `{URL}` placeholder is the app's URL, which is specified in the app's `Properties/launchSettings.json` file in the `applicationUrl` property. - - If Microsoft Edge is used and Google Chrome isn't installed on the system, add an additional property of `"browser": "edge"` to the configuration. - - The following example `.vscode/launch.json` file: - - * Sets the current working directory to the :::no-loc text="Server"::: folder. - * Sets the URL for the app to `https://localhost:7268`. - * Changes the default browser from Google Chrome to Microsoft Edge. - - ```json - "cwd": "${workspaceFolder}/Server", - "url": "https://localhost:7268", - "browser": "edge" - ``` - - The complete `.vscode/launch.json` file: - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "type": "blazorwasm", - "name": "Launch and Debug Blazor WebAssembly Application", - "request": "launch", - "cwd": "${workspaceFolder}/Server", - "url": "https://localhost:7268", - "browser": "edge" - } - ] - } - ``` - - In `.vscode/tasks.json`, add a `build` argument that specifies the path to the **:::no-loc text="Server":::** app's project file: - - ```json - "${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj", - ``` - - In the preceding argument: - - * The `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically :::no-loc text="Server":::. - * The `{PROJECT NAME}` placeholder is the app's name, typically based on the solution's name followed by `.Server` in an app generated from the Blazor WebAssembly project template. - - An example `.vscode/tasks.json` file with a **:::no-loc text="Server":::** project named `BlazorHosted` in the :::no-loc text="Server"::: folder of the solution: - - ```json - { - "version": "2.0.0", - "tasks": [ - { - "label": "build", - "command": "dotnet", - "type": "process", - "args": [ - "build", - "${workspaceFolder}/Server/BlazorHosted.Server.csproj", - "/property:GenerateFullPaths=true", - "/consoleloggerparameters:NoSummary", - ], - "group": "build", - "presentation": { - "reveal": "silent" - }, - "problemMatcher": "$msCompile" - } - ] - } - ``` - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - -> [!NOTE] -> Only [browser debugging](xref:blazor/debug#debug-in-the-browser) is supported at this time. -> -> You can't automatically rebuild the backend **:::no-loc text="Server":::** app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with [`dotnet watch run`](xref:tutorials/dotnet-watch). - -## Trust a development certificate - -For more information, see . - -:::zone-end - -:::zone pivot="macos" - -1. Install [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). When the installer requests the workloads to install, select **.NET**. - -1. Select **New Project** from the **File** menu or create a **New** project from the **Start Window**. - -1. In the sidebar, select **Web and Console** > **App**. - - For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Continue**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Confirm that **Authentication** is set to **No Authentication**. Select **Continue**. - -1. For a hosted Blazor WebAssembly experience, select the **ASP.NET Core Hosted** checkbox. - -1. In the **Project name** field, name the app `WebApplication1`. Select **Create**. - -1. Select the **Start Without Debugging** command from the **Debug** menu to run the app *without the debugger*. Run the app with **Debug** > **Start Debugging** or the Run (▶) button to run the app *with the debugger*. - -If a prompt appears to trust the development certificate, trust the certificate and continue. The user and keychain passwords are required to trust the certificate. For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -> [!IMPORTANT] -> When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -## Visual Studio solution file (`.sln`) - -A *solution* is a container to organize one or more related code projects. [Visual Studio](https://visualstudio.microsoft.com/vs/) and [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) use a solution file (`.sln`) to store settings for a solution. Solution files use a unique format and aren't intended to be edited directly. - -Tooling outside of Visual Studio and Visual Studio for Mac can interact with solution files: - -* The [.NET CLI](/dotnet/core/tools/) can create solution files and list/modify the projects in solution files via the [`dotnet sln` command](/dotnet/core/tools/dotnet-sln). Other .NET CLI commands use the path of the solution file for various publishing, testing, and packaging commands. -* [Visual Studio Code](https://code.visualstudio.com) can execute the `dotnet sln` command and other .NET CLI commands through its integrated terminal but doesn't use the settings in a solution file directly. - -Throughout the Blazor documentation, *solution* is used to describe apps created from the Blazor WebAssembly project template with the **ASP.NET Core Hosted** option enabled or from a Blazor Hybrid project template. Apps produced from these project templates include a solution file (`.sln`) by default. For hosted Blazor WebAssembly apps where the developer isn't using Visual Studio or Visual Studio for Mac, the solution file can be ignored or deleted if it isn't used with .NET CLI commands. - -For more information, see the following resources in the Visual Studio documentation: - -* [Introduction to projects and solutions](/visualstudio/get-started/tutorial-projects-solutions) -* [What are solutions and projects in Visual Studio?](/visualstudio/ide/solutions-and-projects-in-visual-studio) - -:::zone pivot="windows" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -:::zone pivot="macos" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -## Blazor template options - -The Blazor framework provides templates for creating new apps for each of the two Blazor hosting models. The templates are used to create new Blazor projects and solutions regardless of the tooling that you select for Blazor development (Visual Studio, Visual Studio for Mac, Visual Studio Code, or the [.NET command-line interface (CLI)](/dotnet/core/tools/)): - -* Blazor Server project template: `blazorserver` -* Blazor WebAssembly project template: `blazorwasm` - -For more information on Blazor's hosting models, see . For more information on Blazor project templates, see . - -For more information on template options, see the following resources: - -* *.NET default templates for dotnet new* article in the .NET Core documentation: - * [`blazorserver`](/dotnet/core/tools/dotnet-new-sdk-templates#blazorserver) - * [`blazorwasm`](/dotnet/core/tools/dotnet-new-sdk-templates#blazorwasm) -* Passing the help option (`-h` or `--help`) to the [`dotnet new`](/dotnet/core/tools/dotnet-new) CLI command in a command shell: - * `dotnet new blazorserver -h` - * `dotnet new blazorwasm -h` - -## .NET WebAssembly build tools - The .NET WebAssembly build tools are based on [Emscripten](https://emscripten.org/), a compiler toolchain for the web platform. To install the build tools, use ***either*** of the following approaches: * For the **ASP.NET and web development** workload in the Visual Studio installer, select the **.NET WebAssembly build tools** option from the list of optional components. @@ -695,8 +568,12 @@ For more information, see the following resources: * [Runtime relinking](xref:blazor/host-and-deploy/webassembly#runtime-relinking) * +:::moniker-end + ## Additional resources +:::moniker range=">= aspnetcore-6.0" + * [.NET command-line interface (CLI)](/dotnet/core/tools/) * * @@ -705,511 +582,9 @@ For more information, see the following resources: :::moniker-end -:::moniker range=">= aspnetcore-5.0 < aspnetcore-6.0" - -:::zone pivot="windows" - -1. Install the latest version of [Visual Studio 2022](https://visualstudio.microsoft.com) with the **ASP.NET and web development** workload. - -1. Create a new project. - -1. For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Next**. - -1. Provide a **Project name** and confirm that the **Location** is correct. Select **Next**. - -1. In the **Additional information** dialog, select the **ASP.NET Core Hosted** checkbox for a hosted Blazor WebAssembly app. Select **Create**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - - When running a hosted Blazor WebAssembly [solution](#visual-studio-solution-file-sln) in Visual Studio, the startup project of the solution is the **:::no-loc text="Server":::** project. - -For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -> [!IMPORTANT] -> When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -:::zone pivot="linux" - -1. Install the latest version of the [.NET Core SDK](https://dotnet.microsoft.com/download). If you previously installed the SDK, you can determine your installed version by executing the following command in a command shell: - - ```dotnetcli - dotnet --version - ``` - -1. Install the latest version of [Visual Studio Code](https://code.visualstudio.com). - -1. Install the latest [C# for Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp). - -1. For a Blazor WebAssembly experience, execute the following command in a command shell: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 - ``` - - For a hosted Blazor WebAssembly experience, add the hosted option (`-ho` or `--hosted`) option to the command: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 -ho - ``` - - For a Blazor Server experience, execute the following command in a command shell: - - ```dotnetcli - dotnet new blazorserver -o WebApplication1 - ``` - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Open the `WebApplication1` folder in Visual Studio Code. - -1. The IDE requests that you add assets to build and debug the project. Select **Yes**. - - If Visual Studio Code doesn't offer to create the assets automatically, use the following files: - - `.vscode/launch.json` (configured for launch and debug of a Blazor WebAssembly app): - - ```json - { - // Use IntelliSense to learn about possible attributes. - // Hover to view descriptions of existing attributes. - // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 - "version": "0.2.0", - "configurations": [ - { - "type": "blazorwasm", - "name": "Launch and Debug Blazor WebAssembly Application", - "request": "launch", - "cwd": "${workspaceFolder}", - "browser": "edge" - } - ] - } - ``` - - `.vscode/tasks.json`: - - ```json - { - // See https://go.microsoft.com/fwlink/?LinkId=733558 - // for the documentation about the tasks.json format - "version": "2.0.0", - "tasks": [ - { - "label": "build", - "command": "dotnet", - "type": "shell", - "args": [ - "build", - // Ask dotnet build to generate full paths for file names. - "/property:GenerateFullPaths=true", - // Do not generate summary otherwise it leads to duplicate errors in Problems panel - "/consoleloggerparameters:NoSummary", - ], - "group": "build", - "presentation": { - "reveal": "silent" - }, - "problemMatcher": "$msCompile" - } - ] - } - ``` - - **Hosted Blazor WebAssembly launch and task configuration** - - For hosted Blazor WebAssembly [solutions](#visual-studio-solution-file-sln), add (or move) the `.vscode` folder with `launch.json` and `tasks.json` files to the solution's parent folder, which is the folder that contains the typical project folders: :::no-loc text="Client":::, :::no-loc text="Server":::, and `Shared`. Update or confirm that the configuration in the `launch.json` and `tasks.json` files execute a hosted Blazor WebAssembly app from the **:::no-loc text="Server":::** project. - - > [!IMPORTANT] - > When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - - **`.vscode/launch.json`** (`launch` configuration): - - ```json - ... - "cwd": "${workspaceFolder}/{SERVER APP FOLDER}", - ... - ``` - - In the preceding configuration for the current working directory (`cwd`), the `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". - - If Microsoft Edge is used and Google Chrome isn't installed on the system, add an additional property of `"browser": "edge"` to the configuration. - - Example for a project folder of :::no-loc text="Server"::: and that spawns Microsoft Edge as the browser for debug runs instead of the default browser Google Chrome: - - ```json - ... - "cwd": "${workspaceFolder}/Server", - "browser": "edge" - ... - ``` - - **`.vscode/tasks.json`** ([`dotnet` command](/dotnet/core/tools/dotnet) arguments): - - ```json - ... - "${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj", - ... - ``` - - In the preceding argument: - - * The `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". - * The `{PROJECT NAME}` placeholder is the app's name, typically based on the solution's name followed by "`.Server`" in an app generated from the [Blazor project template](xref:blazor/project-structure). - - The following example from the [tutorial for using SignalR with a Blazor WebAssembly app](xref:blazor/tutorials/signalr-blazor) uses a project folder name of :::no-loc text="Server"::: and a project name of `BlazorWebAssemblySignalRApp.Server`: - - ```json - ... - "args": [ - "build", - "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj", - ... - ], - ... - ``` - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - -## Trust a development certificate - -For more information, see . - -:::zone-end - -:::zone pivot="macos" - -1. Install [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). When the installer requests the workloads to install, select **.NET**. - -1. Select **New Project** from the **File** menu or create a **New** project from the **Start Window**. - -1. In the sidebar, select **Web and Console** > **App**. - - For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Continue**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Confirm that **Authentication** is set to **No Authentication**. Select **Continue**. - -1. For a hosted Blazor WebAssembly experience, select the **ASP.NET Core Hosted** checkbox. - -1. In the **Project name** field, name the app `WebApplication1`. Select **Create**. - -1. Select the **Start Without Debugging** command from the **Debug** menu to run the app *without the debugger*. Run the app with **Debug** > **Start Debugging** or the Run (▶) button to run the app *with the debugger*. - -If a prompt appears to trust the development certificate, trust the certificate and continue. The user and keychain passwords are required to trust the certificate. For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -> [!IMPORTANT] -> When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -## Visual Studio solution file (`.sln`) - -A *solution* is a container to organize one or more related code projects. [Visual Studio](https://visualstudio.microsoft.com/vs/) and [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) use a solution file (`.sln`) to store settings for a solution. Solution files use a unique format and aren't intended to be edited directly. - -Tooling outside of Visual Studio and Visual Studio for Mac can interact with solution files: - -* The [.NET CLI](/dotnet/core/tools/) can create solution files and list/modify the projects in solution files via the [`dotnet sln` command](/dotnet/core/tools/dotnet-sln). Other .NET CLI commands use the path of the solution file for various publishing, testing, and packaging commands. -* [Visual Studio Code](https://code.visualstudio.com) can execute the `dotnet sln` command and other .NET CLI commands through its integrated terminal but doesn't use the settings in a solution file directly. - -Throughout the Blazor documentation, *solution* is used to describe apps created from the Blazor WebAssembly project template with the **ASP.NET Core Hosted** option enabled or from a Blazor Hybrid project template. Apps produced from these project templates include a solution file (`.sln`) by default. For hosted Blazor WebAssembly apps where the developer isn't using Visual Studio or Visual Studio for Mac, the solution file can be ignored or deleted if it isn't used with .NET CLI commands. - -For more information, see the following resources in the Visual Studio documentation: - -* [Introduction to projects and solutions](/visualstudio/get-started/tutorial-projects-solutions) -* [What are solutions and projects in Visual Studio?](/visualstudio/ide/solutions-and-projects-in-visual-studio) - -:::zone pivot="windows" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -:::zone pivot="macos" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -## Blazor template options - -The Blazor framework provides templates for creating new apps for each of the two Blazor hosting models. The templates are used to create new Blazor projects and solutions regardless of the tooling that you select for Blazor development (Visual Studio, Visual Studio for Mac, Visual Studio Code, or the .NET CLI): - -* Blazor WebAssembly project template: `blazorwasm` -* Blazor Server project template: `blazorserver` - -For more information on Blazor's hosting models, see . For more information on Blazor project templates, see . - -Template options are available by passing the help option (`-h` or `--help`) to the [`dotnet new`](/dotnet/core/tools/dotnet-new) CLI command in a command shell: - -```dotnetcli -dotnet new blazorwasm -h -dotnet new blazorserver -h -``` - -## Additional resources - -* -* - -:::moniker-end - -:::moniker range="< aspnetcore-5.0" - -:::zone pivot="windows" - -1. Install the latest version of [Visual Studio 2022](https://visualstudio.microsoft.com) with the **ASP.NET and web development** workload. - -1. Create a new project. - -1. For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Next**. - -1. Provide a **Project name** and confirm that the **Location** is correct. Select **Next**. - -1. In the **Additional information** dialog, select the **ASP.NET Core Hosted** checkbox for a hosted Blazor WebAssembly app. Select **Create**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - - When running a hosted Blazor WebAssembly [solution](#visual-studio-solution-file-sln) in Visual Studio, the startup project of the solution is the **:::no-loc text="Server":::** project. - -For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -:::zone pivot="linux" - -1. Install the latest version of the [.NET Core SDK](https://dotnet.microsoft.com/download). If you previously installed the SDK, you can determine your installed version by executing the following command in a command shell: - - ```dotnetcli - dotnet --version - ``` - -1. Install the latest version of [Visual Studio Code](https://code.visualstudio.com). - -1. Install the latest [C# for Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp). - -1. For a Blazor WebAssembly experience, execute the following command in a command shell: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 - ``` - - For a hosted Blazor WebAssembly experience, add the hosted option (`-ho` or `--hosted`) option to the command: - - ```dotnetcli - dotnet new blazorwasm -o WebApplication1 -ho - ``` - - For a Blazor Server experience, execute the following command in a command shell: - - ```dotnetcli - dotnet new blazorserver -o WebApplication1 - ``` - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Open the `WebApplication1` folder in Visual Studio Code. - -1. The IDE requests that you add assets to build and debug the project. Select **Yes**. - - If Visual Studio Code doesn't offer to create the assets automatically, use the following files: - - `.vscode/launch.json` (configured for launch and debug of a Blazor WebAssembly app): - - ```json - { - // Use IntelliSense to learn about possible attributes. - // Hover to view descriptions of existing attributes. - // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 - "version": "0.2.0", - "configurations": [ - { - "type": "blazorwasm", - "name": "Launch and Debug Blazor WebAssembly Application", - "request": "launch", - "cwd": "${workspaceFolder}", - "browser": "edge" - } - ] - } - ``` - - `.vscode/tasks.json`: - - ```json - { - // See https://go.microsoft.com/fwlink/?LinkId=733558 - // for the documentation about the tasks.json format - "version": "2.0.0", - "tasks": [ - { - "label": "build", - "command": "dotnet", - "type": "shell", - "args": [ - "build", - // Ask dotnet build to generate full paths for file names. - "/property:GenerateFullPaths=true", - // Do not generate summary otherwise it leads to duplicate errors in Problems panel - "/consoleloggerparameters:NoSummary", - ], - "group": "build", - "presentation": { - "reveal": "silent" - }, - "problemMatcher": "$msCompile" - } - ] - } - ``` - - **Hosted Blazor WebAssembly launch and task configuration** - - For hosted Blazor WebAssembly [solutions](#visual-studio-solution-file-sln), add (or move) the `.vscode` folder with `launch.json` and `tasks.json` files to the solution's parent folder, which is the folder that contains the typical project folders: :::no-loc text="Client":::, :::no-loc text="Server":::, and `Shared`. Update or confirm that the configuration in the `launch.json` and `tasks.json` files execute a hosted Blazor WebAssembly app from the **:::no-loc text="Server":::** project. - - **`.vscode/launch.json`** (`launch` configuration): - - ```json - ... - "cwd": "${workspaceFolder}/{SERVER APP FOLDER}", - ... - ``` - - In the preceding configuration for the current working directory (`cwd`), the `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". - - If Microsoft Edge is used and Google Chrome isn't installed on the system, add an additional property of `"browser": "edge"` to the configuration. - - Example for a project folder of :::no-loc text="Server"::: and that spawns Microsoft Edge as the browser for debug runs instead of the default browser Google Chrome: - - ```json - ... - "cwd": "${workspaceFolder}/Server", - "browser": "edge" - ... - ``` - - **`.vscode/tasks.json`** ([`dotnet` command](/dotnet/core/tools/dotnet) arguments): - - ```json - ... - "${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj", - ... - ``` - - In the preceding argument: - - * The `{SERVER APP FOLDER}` placeholder is the **:::no-loc text="Server":::** project's folder, typically ":::no-loc text="Server":::". - * The `{PROJECT NAME}` placeholder is the app's name, typically based on the solution's name followed by "`.Server`" in an app generated from the [Blazor project template](xref:blazor/project-structure). - - The following example from the [tutorial for using SignalR with a Blazor WebAssembly app](xref:blazor/tutorials/signalr-blazor) uses a project folder name of :::no-loc text="Server"::: and a project name of `BlazorWebAssemblySignalRApp.Server`: - - ```json - ... - "args": [ - "build", - "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj", - ... - ], - ... - ``` - -1. Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to run the app. - -## Trust a development certificate - -For more information, see . - -:::zone-end - -:::zone pivot="macos" - -1. Install [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). When the installer requests the workloads to install, select **.NET**. - -1. Select **New Project** from the **File** menu or create a **New** project from the **Start Window**. - -1. In the sidebar, select **Web and Console** > **App**. - - For a Blazor WebAssembly experience, choose the **Blazor WebAssembly App** template. For a Blazor Server experience, choose the **Blazor Server App** template. Select **Continue**. - - For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see . - -1. Confirm that **Authentication** is set to **No Authentication**. Select **Continue**. - -1. For a hosted Blazor WebAssembly experience, select the **ASP.NET Core Hosted** checkbox. - -1. In the **Project name** field, name the app `WebApplication1`. Select **Create**. - -1. Select the **Start Without Debugging** command from the **Debug** menu to run the app *without the debugger*. Run the app with **Debug** > **Start Debugging** or the Run (▶) button to run the app *with the debugger*. - -If a prompt appears to trust the development certificate, trust the certificate and continue. The user and keychain passwords are required to trust the certificate. For more information on trusting the ASP.NET Core HTTPS development certificate, see . - -> [!IMPORTANT] -> When executing a hosted Blazor WebAssembly app, run the app from the solution's **:::no-loc text="Server":::** project. - -:::zone-end - -## Visual Studio solution file (`.sln`) - -A *solution* is a container to organize one or more related code projects. [Visual Studio](https://visualstudio.microsoft.com/vs/) and [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) use a solution file (`.sln`) to store settings for a solution. Solution files use a unique format and aren't intended to be edited directly. - -Tooling outside of Visual Studio and Visual Studio for Mac can interact with solution files: - -* The [.NET CLI](/dotnet/core/tools/) can create solution files and list/modify the projects in solution files via the [`dotnet sln` command](/dotnet/core/tools/dotnet-sln). Other .NET CLI commands use the path of the solution file for various publishing, testing, and packaging commands. -* [Visual Studio Code](https://code.visualstudio.com) can execute the `dotnet sln` command and other .NET CLI commands through its integrated terminal but doesn't use the settings in a solution file directly. - -Throughout the Blazor documentation, *solution* is used to describe apps created from the Blazor WebAssembly project template with the **ASP.NET Core Hosted** option enabled or from a Blazor Hybrid project template. Apps produced from these project templates include a solution file (`.sln`) by default. For hosted Blazor WebAssembly apps where the developer isn't using Visual Studio or Visual Studio for Mac, the solution file can be ignored or deleted if it isn't used with .NET CLI commands. - -For more information, see the following resources in the Visual Studio documentation: - -* [Introduction to projects and solutions](/visualstudio/get-started/tutorial-projects-solutions) -* [What are solutions and projects in Visual Studio?](/visualstudio/ide/solutions-and-projects-in-visual-studio) - -:::zone pivot="windows" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -:::zone pivot="macos" - -## Use Visual Studio Code for cross-platform Blazor development - -[Visual Studio Code](https://code.visualstudio.com/) is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the [.NET CLI](/dotnet/core/tools/) to create a new Blazor app for development with Visual Studio Code. For more information, see the [Linux version of this article](?pivots=linux). - -:::zone-end - -## Blazor template options - -The Blazor framework provides templates for creating new apps for each of the two Blazor hosting models. The templates are used to create new Blazor projects and solutions regardless of the tooling that you select for Blazor development (Visual Studio, Visual Studio for Mac, Visual Studio Code, or the .NET CLI): - -* Blazor WebAssembly project template: `blazorwasm` -* Blazor Server project template: `blazorserver` - -For more information on Blazor's hosting models, see . For more information on Blazor project templates, see . - -Template options are available by passing the help option (`-h` or `--help`) to the [`dotnet new`](/dotnet/core/tools/dotnet-new) CLI command in a command shell: - -```dotnetcli -dotnet new blazorwasm -h -dotnet new blazorserver -h -``` - -## Additional resources +:::moniker range="< aspnetcore-6.0" +* [.NET command-line interface (CLI)](/dotnet/core/tools/) * *