Skip to content

Blazor empty templates #26575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 4 commits into from
Jul 28, 2022
+362 −5
Merged

Blazor empty templates #26575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2c08fb2
Blazor empty project templates
guardrex Jul 28, 2022
1b761ee
Updates
guardrex Jul 28, 2022
8c3a1b7
Updates
guardrex Jul 28, 2022
83a9c27
Updates
guardrex Jul 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions aspnetcore/blazor/project-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,9 +312,16 @@ To create an app that can run as either a Blazor Server app or a Blazor WebAssem

## Blazor Server

Blazor Server project template: `blazorserver`
Blazor Server project templates: `blazorserver`, `blazorserver-empty`

The Blazor Server template creates the initial files and directory structure for a Blazor Server app. The app is populated with demonstration code for a `FetchData` component that loads data from a registered service, `WeatherForecastService`, and user interaction with a `Counter` component.
The Blazor Server templates create the initial files and directory structure for a Blazor Server app:

* If the `blazorserver` template is used, the app is populated with the following:
* Demonstration code for a `FetchData` component that loads data from a weather forecast service (`WeatherForecastService`) and user interaction with a `Counter` component.
* [Bootstrap](https://getbootstrap.com/) frontend toolkit.
* If the `blazorserver-empty` template is used, the app is created without demonstration code and Bootstrap.

Project structure:

* `Data` folder: Contains the `WeatherForecast` class and implementation of the `WeatherForecastService` that provides example weather data to the app's `FetchData` component.

Expand Down Expand Up @@ -355,9 +362,16 @@ Additional files and folders may appear in an app produced from a Blazor Server

## Blazor WebAssembly

Blazor WebAssembly project template: `blazorwasm`
Blazor WebAssembly project templates: `blazorwasm`, `blazorwasm-empty`

The Blazor WebAssembly template creates the initial files and directory structure for a Blazor WebAssembly app. The app is populated with demonstration code for a `FetchData` component that loads data from a static asset, `weather.json`, and user interaction with a `Counter` component.
The Blazor WebAssembly templates create the initial files and directory structure for a Blazor WebAssembly app:

* If the `blazorwasm` template is used, the app is populated with the following:
* Demonstration code for a `FetchData` component that loads data from a static asset (`weather.json`) and user interaction with a `Counter` component.
* [Bootstrap](https://getbootstrap.com/) frontend toolkit.
* If the `blazorwasm-empty` template is used, the app is created without demonstration code and Bootstrap.

Project structure:

* `Pages` folder: Contains the routable components/pages (`.razor`) that make up the Blazor app. The route for each page is specified using the [`@page`](xref:mvc/views/razor#page) directive. The template includes the following components:
* `Counter` component (`Counter.razor`): Implements the Counter page.
Expand Down
345 changes: 344 additions & 1 deletion aspnetcore/blazor/tooling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ zone_pivot_groups: operating-systems

This article describes tools for building Blazor apps on various platforms.

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

:::zone pivot="windows"

Expand Down Expand Up @@ -842,3 +842,346 @@ dotnet new blazorserver -h
* <xref:blazor/project-structure>

:::moniker-end

:::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. Create a new project.

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.

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 <xref:blazor/hosting-models>.

1. Press <kbd>Ctrl</kbd>+<kbd>F5</kbd> (Windows) or <kbd>⌘</kbd>+<kbd>F5</kbd> (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 **`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>.

> [!IMPORTANT]
> When executing a hosted Blazor WebAssembly app, run the app from the solution's **`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 Server experience with demonstration code and [Bootstrap](https://getbootstrap.com/), execute the following command:

```dotnetcli
dotnet new blazorserver -o WebApplication1
```

Alternatively, create an app without demonstration code and Bootstrap using the `blazorserver-empty` project template:

```dotnetcli
dotnet new blazorserver-empty -o WebApplication1
```

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

```dotnetcli
dotnet new blazorwasm -o WebApplication1
```

Alternatively, create an app without demonstration code and Bootstrap using the `blazorwasm-empty` project template:

```dotnetcli
dotnet new blazorwasm-empty -o WebApplication1
```

For a hosted Blazor WebAssembly experience with demonstration code and Bootstrap, add the hosted option (`-ho`/`--hosted`) to the command:

```dotnetcli
dotnet new blazorwasm -o WebApplication1 -ho
```

Alternatively, create a hosted Blazor WebAssembly app without demonstration code and Bootstrap using the `blazorwasm-empty` template with the hosted option:

```dotnetcli
dotnet new blazorwasm-empty -o WebApplication1 -ho
```

For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see <xref:blazor/hosting-models>.

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: `Client`, `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 **`Server`** project.

> [!IMPORTANT]
> When executing a hosted Blazor WebAssembly app, run the app from the solution's **`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 **`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 **`Server`** project's folder, typically `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 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.

```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 **`Server`** app's project file:

```json
"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",
```

In the preceding argument:

* The `{SERVER APP FOLDER}` placeholder is the **`Server`** 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 WebAssembly project template.

An example `.vscode/tasks.json` file with a **`Server`** project named `BlazorHosted` in the `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 <kbd>Ctrl</kbd>+<kbd>F5</kbd> (Windows) or <kbd>⌘</kbd>+<kbd>F5</kbd> (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 **`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 <xref:security/enforcing-ssl#trust-https-certificate-on-linux-using-edge-or-chrome>.

:::zone-end

:::zone pivot="macos"

1. Install [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/).

1. Select **File** > **New Solution** or create a **New** project from the **Start Window**.

1. In the sidebar, select **Web and Console** > **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 **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.

For information on the two Blazor hosting models, *Blazor WebAssembly* (standalone and hosted) and *Blazor Server*, see <xref:blazor/hosting-models>.

1. Confirm that **Authentication** is set to **No Authentication**. Select **Next**.

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 **Run** > **Start Without Debugging** to run the app *without the debugger*. Run the app with **Run** > **Start Debugging** or the Run (&#9654;) 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>.

> [!IMPORTANT]
> When executing a hosted Blazor WebAssembly app, run the app from the solution's **`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 <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:
* [`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 **.NET WebAssembly 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](xref:blazor/host-and-deploy/webassembly#ahead-of-time-aot-compilation)
* [Runtime relinking](xref:blazor/host-and-deploy/webassembly#runtime-relinking)
* <xref:blazor/webassembly-native-dependencies>

## Additional resources

* [.NET command-line interface (CLI)](/dotnet/core/tools/)
* <xref:test/hot-reload>
* <xref:blazor/hosting-models>
* <xref:blazor/project-structure>
* <xref:blazor/hybrid/tutorials/index>

:::moniker-end