Skip to content

Latest commit

 

History

History
776 lines (528 loc) · 29.6 KB

tooling.md

File metadata and controls

776 lines (528 loc) · 29.6 KB
title author description monikerRange ms.author ms.custom ms.date uid zone_pivot_groups
Tooling for ASP.NET Core Blazor
guardrex
Learn about the tools available to build Blazor apps on various platforms.
>= aspnetcore-3.1
riande
mvc
11/08/2022
blazor/tooling
operating-systems

Tooling for ASP.NET Core Blazor

[!INCLUDE]

This article describes tools for building Blazor apps on various platforms. Select your platform at the top of this article.

:::zone pivot="windows"

To create a Blazor app on Windows, use the following guidance:

  • Install the latest version of Visual Studio with the ASP.NET and web development workload.

:::moniker range=">= aspnetcore-8.0"

  • Create a new project:
    • For a Blazor Web App experience (recommended), choose the Blazor Web App template. 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. Select Next.

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

  • Create a new project:
    • For a Blazor Server experience, choose the Blazor Server App template, which includes demonstration code and Bootstrap, 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. Select Next.

:::moniker-end

:::moniker range="< aspnetcore-7.0"

  • Create a new project:
    • For a Blazor Server experience, choose the Blazor Server App template. Select Next.
    • For a Blazor WebAssembly experience, choose the Blazor WebAssembly App template. Select Next.

:::moniker-end

:::moniker range=">= aspnetcore-8.0"

  • Provide a Project name and confirm that the Location is correct. To enable interactivity with server-side rendering (SSR), select the Use interactive server components checkbox. Select Next.

:::moniker-end

:::moniker range="< aspnetcore-8.0"

  • Provide a Project name and confirm that the Location is correct. Select Next.

  • For a hosted Blazor WebAssembly app, select the ASP.NET Core Hosted checkbox in the Additional information dialog.

:::moniker-end

  • Select Create.

  • Press Ctrl+F5 (Windows) or +F5 (macOS) to run the app.

:::moniker range="< aspnetcore-8.0"

When running a hosted Blazor WebAssembly solution in Visual Studio, the startup project of the solution is the :::no-loc text="Server"::: project.

:::moniker-end

For more information on trusting the ASP.NET Core HTTPS development certificate, see xref:security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos.

:::moniker range="< aspnetcore-8.0"

Important

When executing a hosted Blazor WebAssembly app, run the app from the solution's :::no-loc text="Server"::: project.

When the app is launched, only the Properties/launchSettings.json file in the :::no-loc text="Server"::: project is used.

:::moniker-end

:::zone-end

:::zone pivot="linux"

To create a Blazor app on Linux, use the following guidance:

Use the .NET command-line interface (CLI) to execute commands in a Linux command shell.

Install the latest version of the .NET Core SDK. If you previously installed the SDK, you can determine your installed version by executing the following command:

dotnet --version

Install the latest version of Visual Studio Code.

Install the latest C# for Visual Studio Code extension.

:::moniker range=">= aspnetcore-8.0"

Create a new project:

  • For a Blazor Web App experience (recommended), execute the following command:

    dotnet new blazor -o BlazorApp
    

    To enable interactivity with server-side rendering (SSR), add the --use-server option to the command:

    dotnet new blazor -o BlazorApp --use-server
    
  • For a Blazor WebAssembly experience with demonstration code and Bootstrap, execute the following command:

    dotnet new blazorwasm -o BlazorApp
    
  • Alternatively, create a Blazor WebAssembly app without demonstration code and Bootstrap using the blazorwasm-empty project template:

    dotnet new blazorwasm-empty -o BlazorApp
    

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

Create a new project:

  • For a Blazor Server experience with demonstration code and Bootstrap, execute the following command:

    dotnet new blazorserver -o BlazorApp
    
  • Alternatively, create a Blazor Server app without demonstration code and Bootstrap using the blazorserver-empty project template:

    dotnet new blazorserver-empty -o BlazorApp
    
  • For a Blazor WebAssembly experience with demonstration code and Bootstrap, execute the following command:

    dotnet new blazorwasm -o BlazorApp
    
  • Alternatively, create a Blazor WebAssembly app without demonstration code and Bootstrap using the blazorwasm-empty project template:

    dotnet new blazorwasm-empty -o BlazorApp
    
  • For a hosted Blazor WebAssembly experience with demonstration code and Bootstrap, add the hosted option (-ho/--hosted) to the command:

    dotnet new blazorwasm -o BlazorApp -ho
    
  • Alternatively, create a hosted Blazor WebAssembly app without demonstration code and Bootstrap using the blazorwasm-empty template with the hosted option:

    dotnet new blazorwasm-empty -o BlazorApp -ho
    

:::moniker-end

:::moniker range="< aspnetcore-7.0"

Create a new project:

  • For a Blazor WebAssembly experience, execute the following command:

    dotnet new blazorwasm -o BlazorApp
    
  • For a hosted Blazor WebAssembly experience, add the hosted option (-ho or --hosted) option to the command:

    dotnet new blazorwasm -o BlazorApp -ho
    
  • For a Blazor Server experience, execute the following command:

    dotnet new blazorserver -o BlazorApp
    

:::moniker-end

Open the BlazorApp folder in Visual Studio Code.

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):

:::moniker range=">= aspnetcore-6.0"

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "blazorwasm",
      "name": "Launch and Debug Blazor WebAssembly Application",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "browser": "edge"
    }
  ]
}

.vscode/tasks.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"
    }
  ]
}

:::moniker-end

:::moniker range="< aspnetcore-6.0"

{
  // 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:

{
  // 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:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",

:::moniker-end

:::moniker range="< aspnetcore-8.0"

Hosted Blazor WebAssembly launch and task configuration

For hosted Blazor WebAssembly solutions, 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.

When the app is launched, only the Properties/launchSettings.json file in the :::no-loc text="Server"::: project is used.

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-8.0"

Examine the Properties/launchSettings.json file and determine the URL of the app from the applicationUrl property. Depending on the framework version, the URL protocol is either secure (HTTPS) https://localhost:{PORT} or insecure (HTTP) http://localhost:{PORT}, where the {PORT} placeholder is an assigned port. Note the URL 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.
"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 Google Chrome is preferred over Microsoft Edge, update or add an additional property of "browser": "chrome" 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 http://localhost:7268.
  • Changes the default browser from Microsoft Edge to Google Chrome.
"cwd": "${workspaceFolder}/Server",
"url": "http://localhost:7268",
"browser": "chrome"

The complete .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "blazorwasm",
      "name": "Launch and Debug Blazor WebAssembly Application",
      "request": "launch",
      "cwd": "${workspaceFolder}/Server",
      "url": "http://localhost:7268",
      "browser": "chrome"
    }
  ]
}

In .vscode/tasks.json, add a build argument that specifies the path to the :::no-loc text="Server"::: app's project file:

"${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:

{
  "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"
    }
  ]
}

Press Ctrl+F5 (Windows) or +F5 (macOS) to run the app.

Note

Only browser debugging 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.

:::moniker-end

:::moniker range="< aspnetcore-6.0"

.vscode/launch.json (launch configuration):

...
"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:

...
"cwd": "${workspaceFolder}/Server",
"browser": "edge"
...

.vscode/tasks.json (dotnet command arguments):

...
"${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.

The following example from the tutorial for using SignalR with a Blazor WebAssembly app uses a project folder name of :::no-loc text="Server"::: and a project name of BlazorWebAssemblySignalRApp.Server:

...
"args": [
  "build",
    "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj",
    ...
],
...

Press Ctrl+F5 (Windows) or +F5 (macOS) to run the app.

:::moniker-end

Trust a development certificate

For more information, see xref:security/enforcing-ssl#trust-https-certificate-on-linux-using-edge-or-chrome.

:::zone-end

:::zone pivot="macos"

To create a Blazor app on macOS, use the following guidance:

  • Install Visual Studio for Mac. When the installer requests the workloads to install, select .NET.

  • Select New Project from the File menu or create a New project from the Start Window.

:::moniker range=">= aspnetcore-8.0"

  • For a Blazor Web Apps experience (recommended), Visual Studio for Mac can't create a Blazor Web App in its UI at this time.

    Install the .NET 8.0 Preview SDK using the correct macOS installer for your platform architecture (Arm64 or x64). For more information on trusting the ASP.NET Core HTTPS development certificate, see xref:security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos.

    Open a command shell with Apple's Terminal utility application in macOS's Applications/Utilities folder. Change the directory to the location where you want to create the app with the ls command. For example, use the ls Desktop command to change the directory to the desktop. Execute the following command in the command shell:

    dotnet new blazor -o BlazorApp
    

    To enable interactivity with server-side rendering (SSR), add the --use-serveroption to the command:

    dotnet new blazor -o BlazorApp --use-server
    

    After the app is created, open the project file (BlazorApp.csproj) with Visual Studio for Mac.

    [!NOTE] Visual Studio for Mac will be able to create Blazor Web Apps in an upcoming release.

  • 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 < aspnetcore-8.0"

  • In the sidebar, select Web and Console > App.

  • Create the app:

    • For a Blazor Server experience, choose the Blazor Server App template, which includes demonstration code and Bootstrap, or the Blazor Server App Empty template without demonstration code and Bootstrap. Select Continue.
    • 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. Select Continue.

:::moniker-end

:::moniker range="< aspnetcore-7.0"

  • In the sidebar, select Web and Console > App.

  • Create the app:

    • For a Blazor Server experience, choose the Blazor Server App template. Select Continue.
    • For a Blazor WebAssembly experience, choose the Blazor WebAssembly App template. Select Continue.

:::moniker-end

  • Confirm that Authentication is set to No Authentication. Select Continue.

:::moniker range="< aspnetcore-8.0"

  • For a hosted Blazor WebAssembly experience, select the ASP.NET Core Hosted checkbox.
  • In the Project name field, name the app BlazorApp. Select Create.

  • 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 xref:security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos.

:::moniker-end

:::moniker range="< aspnetcore-8.0"

Important

When executing a hosted Blazor WebAssembly app, run the app from the solution's :::no-loc text="Server"::: project.

When the app is launched, only the Properties/launchSettings.json file in the :::no-loc text="Server"::: project is used.

:::moniker-end

:::zone-end

Visual Studio solution file (.sln)

A solution is a container to organize one or more related code projects. Visual Studio and Visual Studio for 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 can create solution files and list/modify the projects in solution files via the dotnet sln command. Other .NET CLI commands use the path of the solution file for various publishing, testing, and packaging commands.
  • Visual Studio Code 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.

:::moniker range="< aspnetcore-8.0"

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.

:::moniker-end

For more information, see the following resources in the Visual Studio documentation:

:::zone pivot="windows"

Use Visual Studio Code for cross-platform Blazor development

Visual Studio Code is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the .NET CLI to create a new Blazor app for development with Visual Studio Code. For more information, see the Linux version of this article.

:::zone-end

:::zone pivot="macos"

Use Visual Studio Code for cross-platform Blazor development

Visual Studio Code is an open source, cross-platform Integrated Development Environment (IDE) that can be used to develop Blazor apps. Use the .NET CLI to create a new Blazor app for development with Visual Studio Code. For more information, see the Linux version of this article.

:::zone-end

Blazor template options

The Blazor framework provides templates for creating new apps. 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)):

:::moniker range=">= aspnetcore-8.0"

  • Blazor Web App project template (recommended): blazor
  • Blazor WebAssembly project templates: blazorwasm, blazorwasm-empty

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.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 project templates, see xref:blazor/project-structure.

For more information on template options, see the following resources:

:::moniker range=">= aspnetcore-8.0"

  • The .NET default templates for dotnet new article in the .NET Core documentation:
  • Passing the help option (-h or --help) to the dotnet new CLI command in a command shell:
    • dotnet new blazor -h
    • dotnet new blazorwasm -h
    • dotnet new blazorwasm-empty -h

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

  • The .NET default templates for dotnet new article in the .NET Core documentation:
  • Passing the help option (-h or --help) to the dotnet new CLI command in a command shell:
    • dotnet new blazorserver -h
    • dotnet new blazorserver-empty -h
    • dotnet new blazorwasm -h
    • dotnet new blazorwasm-empty -h

:::moniker-end

:::moniker range="< aspnetcore-7.0"

  • The .NET default templates for dotnet new article in the .NET Core documentation:
  • Passing the help option (-h or --help) to the dotnet new CLI command in a command shell:
    • dotnet new blazorserver -h
    • dotnet new blazorwasm -h

:::moniker-end

:::moniker range=">= aspnetcore-6.0"

.NET WebAssembly build tools

:::moniker-end

:::moniker range=">= aspnetcore-7.0"

The .NET WebAssembly build tools are based on Emscripten, 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.
  • Execute dotnet workload install wasm-tools in an administrative command shell.

:::moniker-end

:::moniker range=">= aspnetcore-8.0"

When ahead-of-time (AOT) compilation is used, WebAssembly Single Instruction, Multiple Data (SIMD) is enabled by default for all major browsers. SIMD can improve the throughput of vectorized computations by performing an operation on multiple pieces of data in parallel using a single instruction.

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

:::moniker-end

:::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0"

When ahead-of-time (AOT) compilation is used, WebAssembly Single Instruction, Multiple Data (SIMD) is supported for all major browsers. SIMD can improve the throughput of vectorized computations by performing an operation on multiple pieces of data in parallel using a single instruction. Use the <WasmEnableSIMD> property in the app's project file (.csproj) with a value of true:

<PropertyGroup>
  <WasmEnableSIMD>true</WasmEnableSIMD>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

:::moniker-end

:::moniker range=">= aspnetcore-7.0"

To enable WebAssembly exception handling, use the <WasmEnableExceptionHandling> property in the app's project file (.csproj) with a value of true:

<PropertyGroup>
  <WasmEnableExceptionHandling>true</WasmEnableExceptionHandling>
</PropertyGroup>

Note

.NET WebAssembly build tools for .NET 6 projects

The wasm-tools workload installs the build tools for .NET 7 projects. However, the .NET 7 version of the build tools are incompatible with existing projects built with .NET 6. Projects using the build tools that must support both .NET 6 and .NET 7 must use multi-targeting.

Use the wasm-tools-net6 workload for .NET 6 projects when developing apps with the .NET 7 SDK. To install the wasm-tools-net6 workload, execute the following command from an administrative command shell:

dotnet workload install wasm-tools-net6

For more information, see the following resources:

  • Ahead-of-time (AOT) compilation
  • Runtime relinking
  • xref:blazor/webassembly-native-dependencies

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0"

The .NET WebAssembly build tools are based on Emscripten, 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.
  • Run dotnet workload install wasm-tools in a command shell.

For more information, see the following resources:

  • Ahead-of-time (AOT) compilation
  • Runtime relinking
  • xref:blazor/webassembly-native-dependencies

:::moniker-end

Additional resources

:::moniker range=">= aspnetcore-6.0"

:::moniker-end

:::moniker range="< aspnetcore-6.0"

:::moniker-end