32 KiB
title | author | description | monikerRange | ms.author | ms.custom | ms.date | no-loc | uid | zone_pivot_groups | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Tooling for ASP.NET Core Blazor | guardrex | Learn about the tooling available to build Blazor apps. | >= aspnetcore-3.1 | riande | mvc | 09/24/2021 |
|
blazor/tooling | operating-systems |
Tooling for ASP.NET Core Blazor
::: moniker range=">= aspnetcore-6.0"
::: zone pivot="windows"
-
Install the latest version of Visual Studio 2022 with the ASP.NET and web development workload.
-
Create a new project.
-
For a Blazor WebAssembly experience, choose the Blazor WebAssembly App template. For a Blazor Server experience, choose the Blazor Server App template. Select Next.
-
Provide a Project name and confirm that the Location is correct. Select Next.
-
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 xref:blazor/hosting-models.
-
Press Ctrl+F5 to run the app.
When running a hosted Blazor WebAssembly solution in Visual Studio, the startup project of the solution is the
Server
project.
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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
::: zone pivot="linux"
-
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 in a command shell:
dotnet --version
-
Install the latest version of Visual Studio Code.
-
Install the latest C# for Visual Studio Code extension.
-
For a Blazor WebAssembly experience, execute the following command in a command shell:
dotnet new blazorwasm -o WebApplication1
For a hosted Blazor WebAssembly experience, add the hosted option (
-ho
or--hosted
) option to the command:dotnet new blazorwasm -o WebApplication1 -ho
For a Blazor Server experience, execute the following command in a command shell:
dotnet new blazorserver -o WebApplication1
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Open the
WebApplication1
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):{ "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" } ] }
The project's
Properties/launchSettings.json
file includes theinspectUri
property for the debugging proxy for any profiles in theprofiles
section of the file:"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
Hosted Blazor WebAssembly launch and task configuration
For hosted Blazor WebAssembly solutions, add (or move) the
.vscode
folder withlaunch.json
andtasks.json
files to the solution's parent folder, which is the folder that contains the typical project folders:Client
,Server
, andShared
. Update or confirm that the configuration in thelaunch.json
andtasks.json
files execute a hosted Blazor WebAssembly app from theServer
project.Examine the
Properties/launchSettings.json
file and determine the URL of the app from theapplicationUrl
property (for example,https://localhost:7268
). Note this value for use in thelaunch.json
file.In the launch configuration of the
.vscode/launch.json
file:- Set the current working directory (
cwd
) to theServer
project folder. - Indicate the app's URL with the
url
property. Use the value recorded earlier from theProperties/launchSettings.json
file.
"cwd": "${workspaceFolder}/{SERVER APP FOLDER}", "url": "{URL}"
In the preceding configuration:
- The
{SERVER APP FOLDER}
placeholder is theServer
project's folder, typicallyServer
. - The
{URL}
placeholder is the app's URL, which is specified in the app'sProperties/launchSettings.json
file in theapplicationUrl
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 follow example
.vscode/launch.json
file:- Sets the current working directory to the
Server
folder. - Sets the URL for the app to
https://localhost:7268
. - Changes the default browser from Google Chrome, which is the default browser, to Microsoft Edge.
"cwd": "${workspaceFolder}/Server", "url": "https://localhost:7268", "browser": "edge"
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": "https://localhost:7268", "browser": "edge" } ] }
In
.vscode/tasks.json
, add abuild
argument that specifies the path to theServer
app's project file:"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",
In the preceding argument:
- The
{SERVER APP FOLDER}
placeholder is theServer
project's folder, typicallyServer
. - 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 aServer
project namedBlazorHosted
in theServer
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" } ] }
- Set the current working directory (
-
Press Ctrl+F5 to run the app.
[!NOTE] Only browser debugging is supported at this time.
You can't automatically rebuild the backend
Server
app of a hosted Blazor WebAssembly solution during debugging, for example by running the app withdotnet watch run
.
Trust a development certificate
There's no centralized way to trust a certificate on Linux. Typically, one of the following approaches is adopted:
- Exclude the app's URL in browser's exclude list.
- Trust all self-signed certificates for
localhost
. - Add the certificate to the list of trusted certificates in the browser.
For more information, see the guidance provided by your browser manufacturer and Linux distribution.
::: zone-end
::: zone pivot="macos"
-
Install Visual Studio for Mac.
-
Select File > New Solution or create a New project from the Start Window.
-
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 Next.
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Confirm that Authentication is set to No Authentication. Select Next.
-
For a hosted Blazor WebAssembly experience, select the ASP.NET Core hosted checkbox.
-
In the Project Name field, name the app
WebApplication1
. Select Create. -
Select Run > Start Without Debugging to run the app without the debugger. Run the app with Run > 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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
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.
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 Server project template:
blazorserver
- Blazor WebAssembly project template:
blazorwasm
For more information on Blazor's hosting models, see xref:blazor/hosting-models. For more information on Blazor project templates, see xref:blazor/project-structure.
For more information on template options, see the following resources:
- .NET default templates for dotnet new article in the .NET Core documentation:
- Passing the help option (
-h
or--help
) to thedotnet new
CLI command in a command shell:dotnet new blazorserver -h
dotnet new blazorwasm -h
.NET Hot reload
.NET Hot Reload applies code changes, including changes to stylesheets, to a running app without restarting the app and without losing app state.
Hot Reload is activated using the dotnet watch
command:
dotnet watch
To force the app to rebuild and restart, use the keyboard combination Ctrl+R in the command shell.
When an unsupported code edit is made, called a rude edit, dotnet watch
asks you if you want to restart the app:
- Yes: Restarts the app.
- No: Doesn't restart the app and leaves the app running without the changes applied.
- Always: Restarts the app as needed when rude edits occur.
- Never: Doesn't restart the app and avoids future prompts.
To disable support for Hot Reload, pass the --no-hot-reload
option to the dotnet watch
command:
dotnet watch --no-hot-reload
For Blazor WebAssembly apps, only method body replacement is currently supported. Additional features will be added in upcoming releases of ASP.NET Core. For more information on supported scenarios, see Supported code changes (C# and Visual Basic).
Additional resources
::: moniker-end
::: moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"
::: zone pivot="windows"
-
Install the latest version of Visual Studio 2022 with the ASP.NET and web development workload.
-
Create a new project.
-
For a Blazor WebAssembly experience, choose the Blazor WebAssembly App template. For a Blazor Server experience, choose the Blazor Server App template. Select Next.
-
Provide a Project name and confirm that the Location is correct. Select Next.
-
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 xref:blazor/hosting-models.
-
Press Ctrl+F5 to run the app.
When running a hosted Blazor WebAssembly solution in Visual Studio, the startup project of the solution is the
Server
project.
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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
::: zone pivot="linux"
-
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 in a command shell:
dotnet --version
-
Install the latest version of Visual Studio Code.
-
Install the latest C# for Visual Studio Code extension.
-
For a Blazor WebAssembly experience, execute the following command in a command shell:
dotnet new blazorwasm -o WebApplication1
For a hosted Blazor WebAssembly experience, add the hosted option (
-ho
or--hosted
) option to the command:dotnet new blazorwasm -o WebApplication1 -ho
For a Blazor Server experience, execute the following command in a command shell:
dotnet new blazorserver -o WebApplication1
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Open the
WebApplication1
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):{ // 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" } ] }
Hosted Blazor WebAssembly launch and task configuration
For hosted Blazor WebAssembly solutions, add (or move) the
.vscode
folder withlaunch.json
andtasks.json
files to the solution's parent folder, which is the folder that contains the typical project folders:Client
,Server
, andShared
. Update or confirm that the configuration in thelaunch.json
andtasks.json
files execute a hosted Blazor WebAssembly app from theServer
project..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 theServer
project's folder, typically "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
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 theServer
project's folder, typically "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
Server
and a project name ofBlazorWebAssemblySignalRApp.Server
:... "args": [ "build", "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj", ... ], ...
- The
-
Press Ctrl+F5 to run the app.
Trust a development certificate
There's no centralized way to trust a certificate on Linux. Typically, one of the following approaches is adopted:
- Exclude the app's URL in browser's exclude list.
- Trust all self-signed certificates for
localhost
. - Add the certificate to the list of trusted certificates in the browser.
For more information, see the guidance provided by your browser manufacturer and Linux distribution.
::: zone-end
::: zone pivot="macos"
-
Install Visual Studio for Mac.
-
Select File > New Solution or create a New project from the Start Window.
-
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 Next.
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Confirm that Authentication is set to No Authentication. Select Next.
-
For a hosted Blazor WebAssembly experience, select the ASP.NET Core hosted checkbox.
-
In the Project Name field, name the app
WebApplication1
. Select Create. -
Select Run > Start Without Debugging to run the app without the debugger. Run the app with Run > 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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
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.
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 xref:blazor/hosting-models. For more information on Blazor project templates, see xref:blazor/project-structure.
Template options are available by passing the help option (-h
or --help
) to the dotnet new
CLI command in a command shell:
dotnet new blazorwasm -h
dotnet new blazorserver -h
Additional resources
::: moniker-end
::: moniker range="< aspnetcore-5.0"
::: zone pivot="windows"
-
Install the latest version of Visual Studio 2022 with the ASP.NET and web development workload.
-
Create a new project.
-
For a Blazor WebAssembly experience, choose the Blazor WebAssembly App template. For a Blazor Server experience, choose the Blazor Server App template. Select Next.
-
Provide a Project name and confirm that the Location is correct. Select Next.
-
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 xref:blazor/hosting-models.
-
Press Ctrl+F5 to run the app.
When running a hosted Blazor WebAssembly solution in Visual Studio, the startup project of the solution is the
Server
project.
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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
::: zone pivot="linux"
-
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 in a command shell:
dotnet --version
-
Install the latest version of Visual Studio Code.
-
Install the latest C# for Visual Studio Code extension.
-
For a Blazor WebAssembly experience, execute the following command in a command shell:
dotnet new blazorwasm -o WebApplication1
For a hosted Blazor WebAssembly experience, add the hosted option (
-ho
or--hosted
) option to the command:dotnet new blazorwasm -o WebApplication1 -ho
For a Blazor Server experience, execute the following command in a command shell:
dotnet new blazorserver -o WebApplication1
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Open the
WebApplication1
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):{ // 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" } ] }
Hosted Blazor WebAssembly launch and task configuration
For hosted Blazor WebAssembly solutions, add (or move) the
.vscode
folder withlaunch.json
andtasks.json
files to the solution's parent folder, which is the folder that contains the typical project folders:Client
,Server
, andShared
. Update or confirm that the configuration in thelaunch.json
andtasks.json
files execute a hosted Blazor WebAssembly app from theServer
project..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 theServer
project's folder, typically "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
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 theServer
project's folder, typically "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
Server
and a project name ofBlazorWebAssemblySignalRApp.Server
:... "args": [ "build", "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj", ... ], ...
- The
-
Press Ctrl+F5 to run the app.
Trust a development certificate
There's no centralized way to trust a certificate on Linux. Typically, one of the following approaches is adopted:
- Exclude the app's URL in browser's exclude list.
- Trust all self-signed certificates for
localhost
. - Add the certificate to the list of trusted certificates in the browser.
For more information, see the guidance provided by your browser manufacturer and Linux distribution.
::: zone-end
::: zone pivot="macos"
-
Install Visual Studio for Mac.
-
Select File > New Solution or create a New project from the Start Window.
-
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 Next.
For information on the two Blazor hosting models, Blazor WebAssembly (standalone and hosted) and Blazor Server, see xref:blazor/hosting-models.
-
Confirm that Authentication is set to No Authentication. Select Next.
-
For a hosted Blazor WebAssembly experience, select the ASP.NET Core hosted checkbox.
-
In the Project Name field, name the app
WebApplication1
. Select Create. -
Select Run > Start Without Debugging to run the app without the debugger. Run the app with Run > 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.
When executing a hosted Blazor WebAssembly app, run the app from the solution's Server
project.
::: zone-end
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.
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 xref:blazor/hosting-models. For more information on Blazor project templates, see xref:blazor/project-structure.
Template options are available by passing the help option (-h
or --help
) to the dotnet new
CLI command in a command shell:
dotnet new blazorwasm -h
dotnet new blazorserver -h
Additional resources
::: moniker-end