DLL file extension change updates

guardrex · guardrex · commit bc1e0aaac7ee · 2025-04-11T10:40:52.000-04:00
diff --git a/aspnetcore/blazor/host-and-deploy/index.md b/aspnetcore/blazor/host-and-deploy/index.md
@@ -43,20 +43,20 @@ dotnet publish -c Release
 
 Publishing the app triggers a [restore](/dotnet/core/tools/dotnet-restore) of the project's dependencies and [builds](/dotnet/core/tools/dotnet-build) the project before creating the assets for deployment. As part of the build process, unused methods and assemblies are removed to reduce app download size and load times.
 
-Publish locations:
+## Publish locations
 
 :::moniker range=">= aspnetcore-8.0"
 
 * Blazor Web App: The app is published into the `/bin/Release/{TARGET FRAMEWORK}/publish` folder, where the `{TARGET FRAMEWORK}` placeholder is the target framework. Deploy the contents of the `publish` folder to the host.
-* Standalone Blazor WebAssembly: The app is published into the `bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\` folder. To deploy the app as a static site, copy the contents of the `wwwroot` folder to the static site host.
+* Standalone Blazor WebAssembly: The app is published into the `bin/Release/{TARGET FRAMEWORK}/publish` folder. To deploy the app as a static site, copy the contents of the `wwwroot` folder to the static site host.
 
 :::moniker-end
 
 :::moniker range="< aspnetcore-8.0"
 
 * Blazor Server: The app is published into the `/bin/Release/{TARGET FRAMEWORK}/publish` folder, where the `{TARGET FRAMEWORK}` placeholder is the target framework.. Deploy the contents of the `publish` folder to the host.
 * Blazor WebAssembly
-  * Standalone: The app is published into the `/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot` or `bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish` folder, depending on the version of the SDK used to publish the app. To deploy the app as a static site, copy the contents of the `wwwroot` folder to the static site host.
+  * Standalone: The app is published into the `/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot` or `bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish` folder, depending on the version of the SDK used to publish the app. To deploy the app as a static site, copy the contents of the `wwwroot` folder to the static site host.
   * Hosted: The client Blazor WebAssembly app is published into the `/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot` folder of the server app, along with any other static web assets of the client app. Deploy the contents of the `publish` folder to the host.
 
 :::moniker-end
diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/deployment-layout.md b/aspnetcore/blazor/host-and-deploy/webassembly/deployment-layout.md
@@ -17,8 +17,18 @@ This article explains how to enable hosted Blazor WebAssembly deployments in env
 > [!NOTE]
 > This guidance addresses environments that block clients from downloading and executing DLLs. In .NET 8 or later, Blazor uses the Webcil file format to address this problem. For more information, see <xref:blazor/host-and-deploy/webassembly/index?view=aspnetcore-8.0&preserve-view=true#webcil-packaging-format-for-net-assemblies>. Multipart bundling using the experimental NuGet package described by this article isn't supported for Blazor apps in .NET 8 or later. You can use the guidance in this article to create your own multipart bundling NuGet package for .NET 8 or later.
 
+:::moniker range=">= aspnetcore-8.0"
+
+Blazor WebAssembly apps require [dynamic-link libraries (DLLs)](/windows/win32/dlls/dynamic-link-libraries) to function, but some environments block clients from downloading and executing DLLs. Security products are often able to scan the content of files traversing the network and block or quarantine DLL files. This article describes one approach for enabling Blazor WebAssembly apps in these environments, where a multipart bundle file is created from the app's DLLs so that the DLLs can be downloaded together bypassing security restrictions.
+
+::: moniker-end
+
+:::moniker range="< aspnetcore-8.0"
+
 Blazor WebAssembly apps require [dynamic-link libraries (DLLs)](/windows/win32/dlls/dynamic-link-libraries) to function, but some environments block clients from downloading and executing DLLs. In a subset of these environments, [changing the file name extension of DLL files (`.dll`)](xref:blazor/host-and-deploy/webassembly/index#change-the-file-name-extension-of-dll-files) is sufficient to bypass security restrictions, but security products are often able to scan the content of files traversing the network and block or quarantine DLL files. This article describes one approach for enabling Blazor WebAssembly apps in these environments, where a multipart bundle file is created from the app's DLLs so that the DLLs can be downloaded together bypassing security restrictions.
 
+::: moniker-end
+
 A hosted Blazor WebAssembly app can customize its published files and packaging of app DLLs using the following features:
 
 * [JavaScript initializers](xref:blazor/js-interop/index#javascript-initializers) that allow customizing the Blazor boot process.
diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/index.md b/aspnetcore/blazor/host-and-deploy/webassembly/index.md
@@ -439,42 +439,22 @@ Blazor performs Intermediate Language (IL) linking on each Release build to remo
 
 :::moniker-end
 
-:::moniker range=">= aspnetcore-5.0"
+:::moniker range=">= aspnetcore-5.0 < aspnetcore-8.0"
 
 ## Change the file name extension of DLL files
 
-*This section applies to ASP.NET Core 6.x and 7.x. In ASP.NET Core in .NET 8 or later, .NET assemblies are deployed as WebAssembly files (`.wasm`) using the Webcil file format. In ASP.NET Core in .NET 8 or later, this section only applies if the Webcil file format has been disabled in the app's project file.*
+*This section applies to .NET 5 through .NET 7. In .NET 8, .NET assemblies are deployed as WebAssembly files (`.wasm`) using the Webcil file format.*
 
 If a firewall, anti-virus program, or network security appliance is blocking the transmission of the app's dynamic-link library (DLL) files (`.dll`), you can follow the guidance in this section to change the file name extensions of the app's published DLL files.
 
-:::moniker-end
-
-:::moniker range=">= aspnetcore-8.0"
-
-> [!NOTE]
-> Changing the file name extensions of the app's DLL files might not resolve the problem because many security systems scan the content of the app's files, not merely check file extensions.
->
-> For a more robust approach in environments that block the download and execution of DLL files, use ASP.NET Core in .NET 8 or later, which packages .NET assemblies as WebAssembly files (`.wasm`) using the [Webcil](https://github.com/dotnet/runtime/blob/main/docs/design/mono/webcil.md) file format. For more information, see the *Webcil packaging format for .NET assemblies* section in an 8.0 or later version of this article.
->
-> Third-party approaches exist for dealing with this problem. For more information, see the resources at [Awesome Blazor](https://github.com/AdrienTorris/awesome-blazor).
-
-:::moniker-end
+Changing the file name extensions of the app's DLL files might not resolve the problem because many security systems scan the content of the app's files, not merely check file extensions.
 
-:::moniker range=">= aspnetcore-5.0 < aspnetcore-8.0"
+For a more robust approach in environments that block the download and execution of DLL files, take ***either*** of the following approaches:
 
-> [!NOTE]
-> Changing the file name extensions of the app's DLL files might not resolve the problem because many security systems scan the content of the app's files, not merely check file extensions.
->
-> For a more robust approach in environments that block the download and execution of DLL files, take ***either*** of the following approaches:
->
-> * Use ASP.NET Core in .NET 8 or later, which packages .NET assemblies as WebAssembly files (`.wasm`) using the [Webcil](https://github.com/dotnet/runtime/blob/main/docs/design/mono/webcil.md) file format. For more information, see the *Webcil packaging format for .NET assemblies* section in an 8.0 or later version of this article.
-> * In ASP.NET Core in .NET 6 or later, use a [custom deployment layout](xref:blazor/host-and-deploy/webassembly/deployment-layout).
->
-> Third-party approaches exist for dealing with this problem. For more information, see the resources at [Awesome Blazor](https://github.com/AdrienTorris/awesome-blazor).
+* Use .NET 8 or later, which packages .NET assemblies as WebAssembly files (`.wasm`) using the [Webcil](https://github.com/dotnet/runtime/blob/main/docs/design/mono/webcil.md) file format. For more information, see the *Webcil packaging format for .NET assemblies* section in an 8.0 or later version of this article.
+* In .NET 6 or later, use a [custom deployment layout](xref:blazor/host-and-deploy/webassembly/deployment-layout).
 
-:::moniker-end
-
-:::moniker range=">= aspnetcore-5.0"
+Third-party approaches exist for dealing with this problem. For more information, see the resources at [Awesome Blazor](https://github.com/AdrienTorris/awesome-blazor).
 
 After publishing the app, use a shell script or DevOps build pipeline to rename `.dll` files to use a different file extension in the directory of the app's published output.
 
@@ -487,32 +467,22 @@ In the following examples:
 
 To use a different file extension than `.bin`, replace `.bin` in the following commands with the desired file extension.
 
-On Windows:
+# [Windows](#tab/windows)
 
-:::moniker-end
+In the following commands, the `{PATH}` placeholder is the path to the published `_framework` folder in the [`publish` folder](xref:blazor/host-and-deploy/index#publish-locations).
 
-:::moniker range=">= aspnetcore-10.0"
+Rename file extensions in the folder:
 
 ```powershell
 dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
-((Get-Content {PATH}\dotnet.boot.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\dotnet.boot.js
 ```
 
-:::moniker-end
-
-:::moniker range="< aspnetcore-10.0"
+Rename file extensions in the `blazor.boot.json` file:
 
 ```powershell
-dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
 ((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json
 ```
 
-:::moniker-end
-
-:::moniker range=">= aspnetcore-5.0"
-
-In the preceding command, the `{PATH}` placeholder is the path to the published `_framework` folder (for example, `.\bin\Release\{TFM}\browser-wasm\publish\wwwroot\_framework` from the project's root folder, where the `{TFM}` placeholder is the [target framework moniker (TFM)](/dotnet/standard/frameworks)).
-
 If service worker assets are also in use because the app is a [Progressive Web App (PWA)](xref:blazor/progressive-web-app):
 
 ```powershell
@@ -521,32 +491,22 @@ If service worker assets are also in use because the app is a [Progressive Web A
 
 In the preceding command, the `{PATH}` placeholder is the path to the published `service-worker-assets.js` file.
 
-On Linux or macOS:
+# [Linux / macOS](#tab/linux-macos)
 
-:::moniker-end
+In the following commands, the `{PATH}` placeholder is the path to the published `_framework` folder in the [`publish` folder](xref:blazor/host-and-deploy/index#publish-locations).
 
-:::moniker range=">= aspnetcore-10.0"
+Rename file extensions in the folder:
 
 ```console
 for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
-sed -i 's/\.dll"/.bin"/g' {PATH}/dotnet.boot.js
 ```
 
-:::moniker-end
-
-:::moniker range="< aspnetcore-10.0"
+Rename file extensions in the `blazor.boot.json` file:
 
 ```console
-for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
 sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json
 ```
 
-:::moniker-end
-
-:::moniker range=">= aspnetcore-5.0"
-
-In the preceding command, the `{PATH}` placeholder is the path to the published `_framework` folder (for example, `.\bin\Release\{TFM}\browser-wasm\publish\wwwroot\_framework` from the project's root folder), where the `{TFM}` placeholder is the [target framework moniker (TFM)](/dotnet/standard/frameworks))
-
 If service worker assets are also in use because the app is a [Progressive Web App (PWA)](xref:blazor/progressive-web-app):
 
 ```console
@@ -555,70 +515,40 @@ sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js
 
 In the preceding command, the `{PATH}` placeholder is the path to the published `service-worker-assets.js` file.
 
-:::moniker-end
-
-:::moniker range=">= aspnetcore-10.0"
-
-To address the compressed `dotnet.boot.js.gz` and `dotnet.boot.js.br` files, adopt either of the following approaches:
-
-* Remove the compressed `dotnet.boot.js.gz` and `dotnet.boot.js.br` files. **Compression is disabled with this approach.**
-* Recompress the updated `dotnet.boot.js` file.
-
-The preceding guidance for the compressed `dotnet.boot.js` file also applies when service worker assets are in use. Remove or recompress `service-worker-assets.js.br` and `service-worker-assets.js.gz`. Otherwise, file integrity checks fail in the browser.
-
-The following Windows example for .NET 6 or later uses a PowerShell script placed at the root of the project. The following script, which disables compression, is the basis for further modification if you wish to recompress the `dotnet.boot.js` file. Pass the app's path and TFM to the script.
-
-`ChangeDLLExtensions.ps1:`:
-
-```powershell
-param([string]$filepath,[string]$tfm)
-dir $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
-((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\dotnet.boot.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\dotnet.boot.js
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\dotnet.boot.js.gz
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\dotnet.boot.js.br
-```
-
-Recompress `dotnet.boot.js` to re-enable compression.
+---
 
-:::moniker-end
+To address the compressed `blazor.boot.json` file, adopt either of the following approaches:
 
-:::moniker range="< aspnetcore-10.0"
+* Recompress the updated `blazor.boot.json` file, producing new `blazor.boot.json.gz` and `blazor.boot.json.br` files. (*Recommended*)
+* Remove the compressed `blazor.boot.json.gz` and `blazor.boot.json.br` files. (*Compression is disabled with this approach.*)
 
-To address the compressed `blazor.boot.json.gz` and `blazor.boot.json.br` files, adopt either of the following approaches:
+For a [Progressive Web App (PWA)](xref:blazor/progressive-web-app)'s compressed `service-worker-assets.js` file, adopt either of the following approaches:
 
-* Remove the compressed `blazor.boot.json.gz` and `blazor.boot.json.br` files. **Compression is disabled with this approach.**
-* Recompress the updated `blazor.boot.json` file.
+* Recompress the updated `service-worker-assets.js` file, producing new `service-worker-assets.js.br` and `service-worker-assets.js.gz` files. (*Recommended*)
+* Remove the compressed `blazor.boot.json.gz` and `blazor.boot.json.br` files. (*Compression is disabled with this approach.*)
 
-The preceding guidance for the compressed `blazor.boot.json` file also applies when service worker assets are in use. Remove or recompress `service-worker-assets.js.br` and `service-worker-assets.js.gz`. Otherwise, file integrity checks fail in the browser.
+### Automate the extension change
 
-The following Windows example for .NET 6 to .NET 9 uses a PowerShell script placed at the root of the project. The following script, which disables compression, is the basis for further modification if you wish to recompress the `blazor.boot.json` file. Pass the app's path and TFM to the script.
+The following Windows example for .NET 6 or later uses a PowerShell script placed at the root of the project. The following script, which disables compression, is the basis for further modification if you wish to recompress the `blazor.boot.json` file and `service-worker-assets.js` file if the app is a [Progressive Web App (PWA)](xref:blazor/progressive-web-app). Pass the path to the [`publish` folder](xref:blazor/host-and-deploy/index#publish-locations) to the script.
 
 `ChangeDLLExtensions.ps1:`:
 
 ```powershell
-param([string]$filepath,[string]$tfm)
-dir $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
-((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.gz
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.br
+param([string]$filepath)
+dir $filepath\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
+((Get-Content $filepath\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\_framework\blazor.boot.json
+Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.gz
+Remove-Item $filepath\wwwroot\_framework\blazor.boot.json.br
 ```
 
-Recompress `blazor.boot.json` to re-enable compression.
-
-:::moniker-end
-
-:::moniker range=">= aspnetcore-5.0"
-
 If service worker assets are also in use because the app is a [Progressive Web App (PWA)](xref:blazor/progressive-web-app), add the following commands:
 
 ```powershell
-((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js.gz
-Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js.br
+((Get-Content $filepath\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\service-worker-assets.js
+Remove-Item $filepath\wwwroot\service-worker-assets.js.gz
+Remove-Item $filepath\wwwroot\service-worker-assets.js.br
 ```
 
-Recompress `service-worker-assets.js` to re-enable compression.
-
 In the project file, the script is executed after publishing the app for the `Release` configuration:
 
 ```xml
@@ -627,6 +557,8 @@ In the project file, the script is executed after publishing the app for the `Re
 </Target>
 ```
 
+After publishing the app, manually recompress `blazor.boot.json`, and `service-worker-assets.js` if used, to re-enable compression.
+
 > [!NOTE]
 > When renaming and lazy loading the same assemblies, see the guidance in <xref:blazor/webassembly-lazy-load-assemblies#onnavigateasync-events-and-renamed-assembly-files>.
 
diff --git a/aspnetcore/blazor/webassembly-lazy-load-assemblies.md b/aspnetcore/blazor/webassembly-lazy-load-assemblies.md
@@ -351,6 +351,8 @@ The <xref:Microsoft.AspNetCore.Components.Routing.NavigationContext> object pass
 
 For more information, see <xref:blazor/fundamentals/routing#handle-cancellations-in-onnavigateasync>.
 
+:::moniker range=">= aspnetcore-5.0 < aspnetcore-8.0"
+
 ## `OnNavigateAsync` events and renamed assembly files
 
 The resource loader relies on the assembly names that are defined in the boot manifest file. If [assemblies are renamed](xref:blazor/host-and-deploy/webassembly/index#change-the-file-name-extension-of-dll-files), the assembly names used in an <xref:Microsoft.AspNetCore.Components.Routing.Router.OnNavigateAsync> callback and the assembly names in the boot manifest file are out of sync.
@@ -360,6 +362,8 @@ To rectify this:
 * Check to see if the app is running in the `Production` environment when determining which assembly names to use.
 * Store the renamed assembly names in a separate file and read from that file to determine what assembly name to use with the <xref:Microsoft.AspNetCore.Components.WebAssembly.Services.LazyAssemblyLoader> service and <xref:Microsoft.AspNetCore.Components.Routing.Router.OnNavigateAsync> callback.
 
+:::moniker-end
+
 :::moniker range="< aspnetcore-8.0"
 
 ## Lazy load assemblies in a hosted Blazor WebAssembly solution
