Skip to content
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

Update WASM AOT guidance 8.0 #30152

Merged
merged 6 commits into from
Aug 25, 2023
Merged

Update WASM AOT guidance 8.0 #30152

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
77a7e36
Update WASM AOT guidance
guardrex Aug 25, 2023
4a68470
Update
guardrex Aug 25, 2023
ef4548a
Updates
guardrex Aug 25, 2023
d288d6c
Updates
guardrex Aug 25, 2023
b6215b8
Updates
guardrex Aug 25, 2023
a9e78de
Updates
guardrex Aug 25, 2023
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
97 changes: 62 additions & 35 deletions aspnetcore/blazor/tooling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -675,83 +675,110 @@ For more information on template options, see the following resources:

## .NET WebAssembly build tools

:::moniker-end

:::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.
* Execute `dotnet workload install wasm-tools` in an administrative command shell.

> [!NOTE]
> .NET WebAssembly build tools for .NET 6 projects
>
> The `wasm-tools` workload installs the build tools for the latest release. However, the current 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 a later release 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is already wasm-tools-net7 and wasm-tools is Net8 I think

Copy link
Collaborator Author

@guardrex guardrex Aug 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made an update for wasm-tools to say it applies to the latest release, but I don't know what this should say for .NET 6 projects. You may need to supply the exact line of text that makes sense. The language here came directly from Dan's blog post IIRC.

You probably already figured out ..........

mccoy

Damn it Jim! I'm a doc author, not a compiler expert!

     — Dr. Leonard H. "Bones" McCoy (DeForest Kelley) Star Trek, ©1966-69 Paramount Pictures

🙈😆

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note in passing that the rest of the AOT content (and runtime relinking in a following section) is at ...

https://learn.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-7.0#ahead-of-time-aot-compilation

I think a long-range task is to combine the content from both docs into one new article in the Fundamentals node. I opened an issue to do the work at ...

Combine and relocate WASM build tools content
#30153

With the .NET 8 workload, which will go right into 24Q1, I won't reach that for a while tho 🏃.

>
> ```dotnetcli
> dotnet workload install wasm-tools-net6
> ```

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>

:::moniker-end

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

When [ahead-of-time (AOT) compilation](xref:blazor/host-and-deploy/webassembly#ahead-of-time-aot-compilation) is used, [WebAssembly Single Instruction, Multiple Data (SIMD)](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md) 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.
### Ahead-of-time (AOT) compilation

To enable [ahead-of-time (AOT) compilation](xref:blazor/host-and-deploy/webassembly#ahead-of-time-aot-compilation), set `<RunAOTCompilation>` to `true` in the app's project file (`.csproj`):

```xml
<PropertyGroup>
<RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>
```

### Single Instruction, Multiple Data (SIMD)

:::moniker-end

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

When [ahead-of-time (AOT) compilation](xref:blazor/host-and-deploy/webassembly#ahead-of-time-aot-compilation) is used, [WebAssembly Single Instruction, Multiple Data (SIMD)](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md) 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`:
[WebAssembly Single Instruction, Multiple Data (SIMD)](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md) can improve the throughput of vectorized computations by performing an operation on multiple pieces of data in parallel using a single instruction. SIMD is enabled by default for all major browsers.

To disable SIMD, for example when targeting old browsers (on mobile devices), add the `<WasmEnableSIMD>` property set to `false` in the app's project file (`.csproj`):

```xml
<PropertyGroup>
<WasmEnableSIMD>true</WasmEnableSIMD>
<RunAOTCompilation>true</RunAOTCompilation>
<WasmEnableSIMD>false</WasmEnableSIMD>
</PropertyGroup>
```

<!-- UPDATE 8.0 Remove note when https://github.com/dotnet/runtime/issues/89302 is fixed -->

> [!IMPORTANT]
> During 8.0 preview releases, disabling SIMD isn't supported. For more information, see [SIMD cannot be disabled (dotnet/runtime #89302)](https://github.com/dotnet/runtime/issues/89302).

For more information, see [Configuring and hosting .NET WebAssembly applications: SIMD - Single instruction, multiple data](https://github.com/dotnet/runtime/blob/main/src/mono/wasm/features.md#simd---single-instruction-multiple-data).

:::moniker-end

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

[WebAssembly Single Instruction, Multiple Data (SIMD)](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md) can improve the throughput of vectorized computations by performing an operation on multiple pieces of data in parallel using a single instruction.

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

```xml
<PropertyGroup>
<WasmEnableExceptionHandling>true</WasmEnableExceptionHandling>
<WasmEnableSIMD>true</WasmEnableSIMD>
</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:
>
> ```dotnetcli
> dotnet workload install wasm-tools-net6
> ```
For more information, see [Configuring and hosting .NET WebAssembly applications: SIMD - Single instruction, multiple data](https://github.com/dotnet/runtime/blob/main/src/mono/wasm/features.md#simd---single-instruction-multiple-data). Note that the guidance in this document isn't versioned and applies to the latest public release.

For more information, see the following resources:
:::moniker-end

* [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>
:::moniker range=">= aspnetcore-6.0"

### Exception handling

:::moniker-end

:::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0"
:::moniker range=">= aspnetcore-8.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:
Exception handling is enabled by default. To disable exception handling, add the `<WasmEnableExceptionHandling>` property with a value of `false` in the app's project file (`.csproj`):

* 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.
```xml
<PropertyGroup>
<WasmEnableExceptionHandling>false</WasmEnableExceptionHandling>
</PropertyGroup>
```

For more information, see the following resources:
:::moniker-end

* [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>
:::moniker range=">= aspnetcore-6.0 < aspnetcore-8.0"

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

```xml
<PropertyGroup>
<WasmEnableExceptionHandling>true</WasmEnableExceptionHandling>
</PropertyGroup>
```

:::moniker-end

Expand Down