From 3632ed2aeea61f77ec1e6a9d4c4a44fdc3382fa9 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Sun, 1 Apr 2018 23:27:23 -0500 Subject: [PATCH 1/8] Host and deploy topic Host and deploy topic --- docs/host-and-deploy/index.md | 174 ++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/host-and-deploy/index.md diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md new file mode 100644 index 0000000..f3b0ce0 --- /dev/null +++ b/docs/host-and-deploy/index.md @@ -0,0 +1,174 @@ +--- +title: Host and deploy Blazor +author: guardrex +description: Discover how to host and deploy Blazor apps using ASP.NET Core, Content Delivery Networks (CDN), file servers, and GitHub Pages. +manager: wpickett +ms.author: riande +ms.custom: mvc +ms.date: 04/09/2018 +ms.prod: asp.net-core +ms.technology: aspnet +ms.topic: article +uid: client-side/blazor/host-and-deploy/index +--- +# Host and deploy Blazor + +By [Luke Latham](https://github.com/guardrex) and [Rainer Stropek](https://www.timecockpit.com) + +[!INCLUDE[](~/includes/blazor-preview-notice.md)] + +## Publishing + +Blazor apps are published for deployment in Release configuration with the [dotnet publish](https://docs.microsoft.com/dotnet/core/tools/dotnet-publish) command: + +```console +dotnet publish -c Release +``` + +The .NET linker strips unused [Intermediate Language (IL)](https://docs.microsoft.com/dotnet/standard/managed-code) when the app is built in Release configuration. + +The deployment is created in the */bin/Release/netstandard2.0/publish* folder. The assets in the *publish* folder are moved to the web server. + +## Rewrite URLs for correct routing + +Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: + +* **_Index.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). +* **_About.cshtml_**: About page. + +When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): + +1. The browser makes a request. +1. The default page is returned, which is usually *index.html*. +1. *index.html* bootstraps the app. +1. Blazor's router loads and the Razor Index page (*Index.cshtml*) is displayed. + +On the Index page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. + +If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. + +Because browsers make requests to Internet-based hosts for client-side pages, hosts of hosted Blazor apps must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's router takes over and responds with the correct resource. + +Not all hosting scenarios permit the enforcement of rewrite rules. Additional information is provided in the hosting configuration examples that follow. + +## Host with ASP.NET Core + +ASP.NET Core apps that host Blazor apps use Blazor Middleware by calling the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: + +```csharp +public void Configure(IApplicationBuilder app, IHostingEnvironment env) +{ + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseBlazor(); +} +``` + +The Blazor middleware performs the following tasks: + +* Reads the Blazor configuration file (*.blazor.config*) from the `ClientAssemblyPath`, which is either an option provided to the `UseBlazor` extension method or defaulted to the app's assembly file location. +* Configures [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. +* Configure live reloading when in the Development environment and Debug configuration. +* Configure single-page application routing for files outside of the *_framework* folder, which serves the default page (*index.html*) for any request that hasn't been served by a prior Static File Middleware instance. + +For general information on ASP.NET Core app hosting and deployment, see: + +* [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy) +* [.NET Core application deployment](https://docs.microsoft.com/dotnet/core/deploying/) +* [Deploying .NET Core apps with command-line interface (CLI) tools](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-cli) +* [Deploying .NET Core apps with Visual Studio](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-vs) + +## Docker/Linux hosting + +The first line of the Blazor config file (*.blazor.config*) configures the source MSBuild path to `.`. A consequence of this setting is that the webroot path is set to `.\wwwroot`, which results in published files being split between *wwwroot* and *dist* folders. For an unsupported workaround, see [On linux UseBlazor extension method fails with "The path must be absolute"](https://github.com/aspnet/Blazor/issues/376). + +## Static deployment strategies + +The following static deployment strategies make the Blazor deployment's static assets available directly for download. Conceptually, other static hosting system configurations are similar. + +### IIS + +IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, follow these steps provided. + +In the following configuration examples, the app name, and thus the app folder name, is *MyBlazorApp*. The *MyBlazorApp* folder and *web.config* file are in the *publish* folder. + +**Public hosting with Windows Server operating systems** + +> [!NOTE] +> When working with an Azure VM, open either or both HTTP (80) and HTTPS (443) ports to allow HTTP/HTTPS traffic to the VM. In the Azure portal, use the VM's **SETTINGS** > **Networking** > **Add inbound port rule** to open ports. to For more information, see [How to open ports to a virtual machine with the Azure portal](https://docs.microsoft.com/azure/virtual-machines/windows/nsg-quickstart-portal). + +1. Use the **Add Roles and Features** wizard from the **Manage** menu or select the **Add Roles and Features** link in **Server Manager** to enable the **Web Server (IIS)** server role. In the **Server Roles** step, check the box for **Web Server (IIS)**. +1. After the **Features** step, the **Role services** step loads for Web Server (IIS). Accept the default role services provided. The default role services include **Web Server** > **Common HTTP Features** > **Static Content** and **Web Server** > **Performance** > **Static Content Compression**. +1. Proceed through the **Confirmation** step to install the web server role and services. A server/IIS restart isn't required after installing the **Web Server (IIS)** role. +1. Use the Web Platform Installer to install the [URL Rewrite Module](https://www.iis.net/downloads/microsoft/url-rewrite): + 1. Locally, navigate to the [URL Rewrite Module downloads page](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads). For English, select **WebPI** to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer. + 1. Copy the installer to the server. Run the installer. Select the **Install** button and accept the license terms. A server restart isn't required after the install completes. +1. Open the **Internet Information Services (IIS) Manager** by selecting its link in the **Tools** menu of **Server Manager**. +1. In the **Connections** sidebar (left side of the window), open the server's node. Right-click the **Sites** folder and select **Add Website** from the menu. +1. Configure the website: + 1. Set the **Physical path** to the *publish* folder of the deployed Blazor app. The *publish* folder contains: + * The *web.config* file that IIS uses to configure the website, including required redirect rules and file content types. + * The app's folder, *MyBlazorApp*. + 1. Configure the **Binding**. Note that the **Default Web Site** is configured to use port 80 at the server's IP address. To use port 80 for the Blazor app, change the **Binding** of the **Default Web Site** to a port other than 80, such as 8000, before setting the binding for the Blazor app (or remove the **Default Web Site** from the server). When testing with the server's public IP address, the app is reachable at `http://`. Alternatively, the port of the Blazor app can be set to some other port than 80. Don't forget to set an inbound security rule for the same port if the site is hosted by an Azure VM. + 1. Select **OK** to add the website. +1. Navigate to the Blazor app on the Internet using the binding information configured for the website. + +**Local hosting on Windows desktop operating systems** + +1. Navigate to **Control Panel** > **Programs** > **Programs and Features** > **Turn Windows features on or off** (left side of the window). +1. Open the **Internet Information Services** node. Open the **Web Management Tools** node. +1. Check the box for **IIS Management Console**. +1. Check the box for **World Wide Web Services**. +1. Accept the default features for **World Wide Web Services**. The default features include **Common HTTP Features** > **Static Content** and **Performance Features** > **Static Content Compression**. Select the **OK** button to install the IIS features. +1. Use the Web Platform Installer to install the [URL Rewrite Module](https://www.iis.net/downloads/microsoft/url-rewrite): + 1. Navigate to the [URL Rewrite Module downloads page](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads). For English, select **WebPI** to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer. + 1. Run the installer. Select the **Install** button and accept the license terms. A restart isn't required after the install completes. +1. Open the **Internet Information Services (IIS) Manager** by executing **inetmgr.exe** from a run command prompt or by searching for **IIS** and selecting the app's link in the search results. +1. In the **Connections** sidebar (left side of the window), open the server's node. Right-click the **Sites** folder and select **Add Website** from the menu. +1. Configure the website: + 1. Provide a **Site name**. + 1. Set the **Physical path** to the *publish* folder of the deployed Blazor app. The *publish* folder contains: + * The *web.config* file that IIS uses to configure the website, including required redirect rules and file content types. + * The app's folder, *MyBlazorApp*. + 1. Configure the **Binding**. Provide a high numbered port (for example, 8000) and leave the **Host name** blank or set it to `localhost`. + 1. Select **OK** to add the website. +1. Select the website in the **Sites** folder. +1. Navigate to the Blazor app: In the IIS Manager's **Action** sidebar (right side of the window), select the link under **Browse Website** to open the app in the default browser. If the port was set to 8000, the Blazor app is available at `http://localhost:8000`. + +### Nginx + +The following *nginx.conf* file is simplified to show how to configure Nginx to send the *Index.html* file whenever it cannot find a corresponding file on disk. + +``` +events { } +http { + server { + listen 80; + + location / { + root /usr/share/nginx/html; + try_files $uri $uri/ /Index.html =404; + } + } +} +``` + +For more information on production Nginx web server configuration, see [Creating NGINX Plus and NGINX Configuration Files](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/). + +### Nginx in Docker + +Add one line to the Dockerfile, as shown in the following example: + +``` +FROM nginx:alpine +COPY ./bin/Release/netstandard2.0/publish /usr/share/nginx/html/ +COPY nginx.conf /etc/nginx/nginx.conf +``` + +### GitHub Pages + +Blazor apps can be hosted on [GitHub Pages](https://pages.github.com/). For an unsupported example approach, see [Rafael Pedicini's](http://www.rafaelpedicini.com/) [Single Page Apps for GitHub Pages](http://spa-github-pages.rafrex.com/) ([rafrex/spa-github-pages on GitHub](https://github.com/rafrex/spa-github-pages#readme)). Another example using the same approach can be seen at [blazor-demo/blazor-demo.github.io + on GitHub](https://github.com/blazor-demo/blazor-demo.github.io) ([live site](https://blazor-demo.github.io/)). From d0192f70acf0ed83e757aefca923bc040032af58 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Wed, 4 Apr 2018 01:10:03 -0500 Subject: [PATCH 2/8] React to feedback --- docs/host-and-deploy/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index f3b0ce0..dcfde9f 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -33,7 +33,7 @@ The deployment is created in the */bin/Release/netstandard2.0/publish* folder. T Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: -* **_Index.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). +* **_Main.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). * **_About.cshtml_**: About page. When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): @@ -41,13 +41,13 @@ When the app's default document is requested using the browser's address bar (fo 1. The browser makes a request. 1. The default page is returned, which is usually *index.html*. 1. *index.html* bootstraps the app. -1. Blazor's router loads and the Razor Index page (*Index.cshtml*) is displayed. +1. Blazor's router loads and the Razor Main page (*Main.cshtml*) is displayed. -On the Index page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. +On the Main page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. -Because browsers make requests to Internet-based hosts for client-side pages, hosts of hosted Blazor apps must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's router takes over and responds with the correct resource. +Because browsers make requests to Internet-based hosts for client-side pages, hosts of hosted Blazor apps must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. Not all hosting scenarios permit the enforcement of rewrite rules. Additional information is provided in the hosting configuration examples that follow. @@ -98,7 +98,7 @@ In the following configuration examples, the app name, and thus the app folder n **Public hosting with Windows Server operating systems** > [!NOTE] -> When working with an Azure VM, open either or both HTTP (80) and HTTPS (443) ports to allow HTTP/HTTPS traffic to the VM. In the Azure portal, use the VM's **SETTINGS** > **Networking** > **Add inbound port rule** to open ports. to For more information, see [How to open ports to a virtual machine with the Azure portal](https://docs.microsoft.com/azure/virtual-machines/windows/nsg-quickstart-portal). +> When working with an Azure VM, open either or both HTTP (80) and HTTPS (443) ports to allow HTTP/HTTPS traffic to the VM. In the Azure portal, use the VM's **SETTINGS** > **Networking** > **Add inbound port rule** to open ports. For more information, see [How to open ports to a virtual machine with the Azure portal](https://docs.microsoft.com/azure/virtual-machines/windows/nsg-quickstart-portal). 1. Use the **Add Roles and Features** wizard from the **Manage** menu or select the **Add Roles and Features** link in **Server Manager** to enable the **Web Server (IIS)** server role. In the **Server Roles** step, check the box for **Web Server (IIS)**. 1. After the **Features** step, the **Role services** step loads for Web Server (IIS). Accept the default role services provided. The default role services include **Web Server** > **Common HTTP Features** > **Static Content** and **Web Server** > **Performance** > **Static Content Compression**. From d9124b0a0b9fa680014de40725788a4ab1c388ad Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Wed, 4 Apr 2018 10:34:04 -0500 Subject: [PATCH 3/8] Refactor 'Blazor Middleware' language --- docs/host-and-deploy/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index dcfde9f..b329e08 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -53,7 +53,7 @@ Not all hosting scenarios permit the enforcement of rewrite rules. Additional in ## Host with ASP.NET Core -ASP.NET Core apps that host Blazor apps use Blazor Middleware by calling the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: +ASP.NET Core apps that host Blazor apps configure the server-side app's middleware pipeline with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: ```csharp public void Configure(IApplicationBuilder app, IHostingEnvironment env) @@ -67,7 +67,7 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env) } ``` -The Blazor middleware performs the following tasks: +The `UseBlazor` extension method performs the following tasks: * Reads the Blazor configuration file (*.blazor.config*) from the `ClientAssemblyPath`, which is either an option provided to the `UseBlazor` extension method or defaulted to the app's assembly file location. * Configures [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. From a10c9d0bcd195f45c9cb80e26cba2a04a472fc52 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Wed, 4 Apr 2018 10:45:40 -0500 Subject: [PATCH 4/8] Add a link for Azure App Service --- docs/host-and-deploy/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index b329e08..91ed346 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -77,6 +77,7 @@ The `UseBlazor` extension method performs the following tasks: For general information on ASP.NET Core app hosting and deployment, see: * [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy) +* [Host ASP.NET Core on Azure App Service](https://docs.microsoft.com/aspnet/core/host-and-deploy/azure-apps/) * [.NET Core application deployment](https://docs.microsoft.com/dotnet/core/deploying/) * [Deploying .NET Core apps with command-line interface (CLI) tools](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-cli) * [Deploying .NET Core apps with Visual Studio](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-vs) From 705e74921a09f5dce01130b11ee6c2e503b35bbf Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 5 Apr 2018 01:45:39 -0500 Subject: [PATCH 5/8] React to feedback --- docs/host-and-deploy/index.md | 82 ++++++++++++++++------------------- 1 file changed, 37 insertions(+), 45 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index 91ed346..49f525e 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -17,43 +17,20 @@ By [Luke Latham](https://github.com/guardrex) and [Rainer Stropek](https://www.t [!INCLUDE[](~/includes/blazor-preview-notice.md)] -## Publishing +## Reduction in payload size on build -Blazor apps are published for deployment in Release configuration with the [dotnet publish](https://docs.microsoft.com/dotnet/core/tools/dotnet-publish) command: +As part of the build process, unused methods and assemblies are removed to reduce app download size and speed up load times. -```console -dotnet publish -c Release -``` - -The .NET linker strips unused [Intermediate Language (IL)](https://docs.microsoft.com/dotnet/standard/managed-code) when the app is built in Release configuration. - -The deployment is created in the */bin/Release/netstandard2.0/publish* folder. The assets in the *publish* folder are moved to the web server. +## Hosted deployment with ASP.NET Core -## Rewrite URLs for correct routing +Under the hosted deployment model, a Blazor client-side app is hosted inside an ASP.NET Core server-side project. The published ASP.NET Core project is deployed to the web server or hosting service. -Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: - -* **_Main.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). -* **_About.cshtml_**: About page. - -When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): - -1. The browser makes a request. -1. The default page is returned, which is usually *index.html*. -1. *index.html* bootstraps the app. -1. Blazor's router loads and the Razor Main page (*Main.cshtml*) is displayed. - -On the Main page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. - -If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. - -Because browsers make requests to Internet-based hosts for client-side pages, hosts of hosted Blazor apps must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. - -Not all hosting scenarios permit the enforcement of rewrite rules. Additional information is provided in the hosting configuration examples that follow. +Blazor integrates with ASP.NET Core to handle single-page application routing and to host the Blazor app as static files. -## Host with ASP.NET Core +ASP.NET Core apps: -ASP.NET Core apps that host Blazor apps configure the server-side app's middleware pipeline with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: +* Host Blazor apps by first referencing them as dependencies. +* Configure each app in the server-side app's middleware pipeline with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`. ```csharp public void Configure(IApplicationBuilder app, IHostingEnvironment env) @@ -69,26 +46,40 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env) The `UseBlazor` extension method performs the following tasks: -* Reads the Blazor configuration file (*.blazor.config*) from the `ClientAssemblyPath`, which is either an option provided to the `UseBlazor` extension method or defaulted to the app's assembly file location. * Configures [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. -* Configure live reloading when in the Development environment and Debug configuration. * Configure single-page application routing for files outside of the *_framework* folder, which serves the default page (*index.html*) for any request that hasn't been served by a prior Static File Middleware instance. -For general information on ASP.NET Core app hosting and deployment, see: +For general information on ASP.NET Core app hosting and deployment, see [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy). -* [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy) -* [Host ASP.NET Core on Azure App Service](https://docs.microsoft.com/aspnet/core/host-and-deploy/azure-apps/) -* [.NET Core application deployment](https://docs.microsoft.com/dotnet/core/deploying/) -* [Deploying .NET Core apps with command-line interface (CLI) tools](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-cli) -* [Deploying .NET Core apps with Visual Studio](https://docs.microsoft.com/dotnet/core/deploying/deploy-with-vs) +## Standalone deployment -## Docker/Linux hosting +Standalone deployment only deploys the Blazor client-side app. There isn't an ASP.NET Core server-side hosting app. -The first line of the Blazor config file (*.blazor.config*) configures the source MSBuild path to `.`. A consequence of this setting is that the webroot path is set to `.\wwwroot`, which results in published files being split between *wwwroot* and *dist* folders. For an unsupported workaround, see [On linux UseBlazor extension method fails with "The path must be absolute"](https://github.com/aspnet/Blazor/issues/376). +**Rewrite URLs for correct routing** -## Static deployment strategies +Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: + +* **_Main.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). +* **_About.cshtml_**: About page. + +When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): + +1. The browser makes a request. +1. The default page is returned, which is usually *index.html*. +1. *index.html* bootstraps the app. +1. Blazor's router loads and the Razor Main page (*Main.cshtml*) is displayed. + +On the Main page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. + +If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. -The following static deployment strategies make the Blazor deployment's static assets available directly for download. Conceptually, other static hosting system configurations are similar. +Because browsers make requests to Internet-based hosts for client-side pages, web servers and services must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. + +Not all hosting scenarios permit the enforcement of rewrite rules. Additional information is provided in the hosting configuration examples that follow. + +## Static deployment strategies for standalone Blazor apps + +When deploying a standalone Blazor app, any web server or hosting service that serves static files can host a Blazor app. ### IIS @@ -171,5 +162,6 @@ COPY nginx.conf /etc/nginx/nginx.conf ### GitHub Pages -Blazor apps can be hosted on [GitHub Pages](https://pages.github.com/). For an unsupported example approach, see [Rafael Pedicini's](http://www.rafaelpedicini.com/) [Single Page Apps for GitHub Pages](http://spa-github-pages.rafrex.com/) ([rafrex/spa-github-pages on GitHub](https://github.com/rafrex/spa-github-pages#readme)). Another example using the same approach can be seen at [blazor-demo/blazor-demo.github.io - on GitHub](https://github.com/blazor-demo/blazor-demo.github.io) ([live site](https://blazor-demo.github.io/)). +To handle URL rewrites, add a *404.html* file with a script that handles redirecting the request to the *index.html* page. For an example implementation provided by the community, see [Single Page Apps for GitHub Pages](http://spa-github-pages.rafrex.com/) ([rafrex/spa-github-pages on GitHub](https://github.com/rafrex/spa-github-pages#readme)). An example using the community approach can be seen at [blazor-demo/blazor-demo.github.io on GitHub](https://github.com/blazor-demo/blazor-demo.github.io) ([live site](https://blazor-demo.github.io/)). + +There's also a potential issue when using a project site instead of an organization site. Project sites have a path, so the base tag in *index.html* should be updated from `/` to `/`. From a1865bb234a43a3c8e48d79ab76bf3337225939e Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 5 Apr 2018 17:59:22 -0500 Subject: [PATCH 6/8] React to feedback Update --- docs/host-and-deploy/index.md | 111 ++++++++++++++++------------------ 1 file changed, 53 insertions(+), 58 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index 49f525e..89f448d 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -23,14 +23,9 @@ As part of the build process, unused methods and assemblies are removed to reduc ## Hosted deployment with ASP.NET Core -Under the hosted deployment model, a Blazor client-side app is hosted inside an ASP.NET Core server-side project. The published ASP.NET Core project is deployed to the web server or hosting service. +In a hosted deployment, an ASP.NET Core app handles single-page application routing and hosts the Blazor app's static files. The published app is deployed to the web server or hosting service. -Blazor integrates with ASP.NET Core to handle single-page application routing and to host the Blazor app as static files. - -ASP.NET Core apps: - -* Host Blazor apps by first referencing them as dependencies. -* Configure each app in the server-side app's middleware pipeline with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`. +In the ASP.NET Core app, each hosted Blazor app is configured with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: ```csharp public void Configure(IApplicationBuilder app, IHostingEnvironment env) @@ -49,11 +44,19 @@ The `UseBlazor` extension method performs the following tasks: * Configures [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. * Configure single-page application routing for files outside of the *_framework* folder, which serves the default page (*index.html*) for any request that hasn't been served by a prior Static File Middleware instance. -For general information on ASP.NET Core app hosting and deployment, see [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy). +For information on ASP.NET Core app hosting and deployment, see [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy). + +For information on deploying to Azure App Service, see the following topics: + +[Publish to Azure with Visual Studio](https://docs.microsoft.com/aspnet/core/tutorials/publish-to-azure-webapp-using-vs) +Learn how to publish an ASP.NET Core-hosted Blazor app to Azure App Service using Visual Studio. + +[Publish to Azure with CLI tools](https://docs.microsoft.com/aspnet/core/tutorials/publish-to-azure-webapp-using-cli) +Learn how to publish an ASP.NET Core app to Azure App Service using the Git command-line client. ## Standalone deployment -Standalone deployment only deploys the Blazor client-side app. There isn't an ASP.NET Core server-side hosting app. +In a standalone deployment, only the Blazor client-side app is deployed to the server or hosting service. An ASP.NET Core server-side app isn't used to host the Blazor app. The Blazor app's static files are requested by the browser directly from the static file web server or service. **Rewrite URLs for correct routing** @@ -75,60 +78,52 @@ If a request is made using the browser's address bar for `www.contoso.com/About` Because browsers make requests to Internet-based hosts for client-side pages, web servers and services must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. -Not all hosting scenarios permit the enforcement of rewrite rules. Additional information is provided in the hosting configuration examples that follow. - -## Static deployment strategies for standalone Blazor apps +## Static hosting strategies for standalone apps When deploying a standalone Blazor app, any web server or hosting service that serves static files can host a Blazor app. ### IIS -IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, follow these steps provided. - -In the following configuration examples, the app name, and thus the app folder name, is *MyBlazorApp*. The *MyBlazorApp* folder and *web.config* file are in the *publish* folder. - -**Public hosting with Windows Server operating systems** - -> [!NOTE] -> When working with an Azure VM, open either or both HTTP (80) and HTTPS (443) ports to allow HTTP/HTTPS traffic to the VM. In the Azure portal, use the VM's **SETTINGS** > **Networking** > **Add inbound port rule** to open ports. For more information, see [How to open ports to a virtual machine with the Azure portal](https://docs.microsoft.com/azure/virtual-machines/windows/nsg-quickstart-portal). - -1. Use the **Add Roles and Features** wizard from the **Manage** menu or select the **Add Roles and Features** link in **Server Manager** to enable the **Web Server (IIS)** server role. In the **Server Roles** step, check the box for **Web Server (IIS)**. -1. After the **Features** step, the **Role services** step loads for Web Server (IIS). Accept the default role services provided. The default role services include **Web Server** > **Common HTTP Features** > **Static Content** and **Web Server** > **Performance** > **Static Content Compression**. -1. Proceed through the **Confirmation** step to install the web server role and services. A server/IIS restart isn't required after installing the **Web Server (IIS)** role. -1. Use the Web Platform Installer to install the [URL Rewrite Module](https://www.iis.net/downloads/microsoft/url-rewrite): - 1. Locally, navigate to the [URL Rewrite Module downloads page](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads). For English, select **WebPI** to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer. - 1. Copy the installer to the server. Run the installer. Select the **Install** button and accept the license terms. A server restart isn't required after the install completes. -1. Open the **Internet Information Services (IIS) Manager** by selecting its link in the **Tools** menu of **Server Manager**. -1. In the **Connections** sidebar (left side of the window), open the server's node. Right-click the **Sites** folder and select **Add Website** from the menu. -1. Configure the website: - 1. Set the **Physical path** to the *publish* folder of the deployed Blazor app. The *publish* folder contains: - * The *web.config* file that IIS uses to configure the website, including required redirect rules and file content types. - * The app's folder, *MyBlazorApp*. - 1. Configure the **Binding**. Note that the **Default Web Site** is configured to use port 80 at the server's IP address. To use port 80 for the Blazor app, change the **Binding** of the **Default Web Site** to a port other than 80, such as 8000, before setting the binding for the Blazor app (or remove the **Default Web Site** from the server). When testing with the server's public IP address, the app is reachable at `http://`. Alternatively, the port of the Blazor app can be set to some other port than 80. Don't forget to set an inbound security rule for the same port if the site is hosted by an Azure VM. - 1. Select **OK** to add the website. -1. Navigate to the Blazor app on the Internet using the binding information configured for the website. - -**Local hosting on Windows desktop operating systems** - -1. Navigate to **Control Panel** > **Programs** > **Programs and Features** > **Turn Windows features on or off** (left side of the window). -1. Open the **Internet Information Services** node. Open the **Web Management Tools** node. -1. Check the box for **IIS Management Console**. -1. Check the box for **World Wide Web Services**. -1. Accept the default features for **World Wide Web Services**. The default features include **Common HTTP Features** > **Static Content** and **Performance Features** > **Static Content Compression**. Select the **OK** button to install the IIS features. -1. Use the Web Platform Installer to install the [URL Rewrite Module](https://www.iis.net/downloads/microsoft/url-rewrite): - 1. Navigate to the [URL Rewrite Module downloads page](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads). For English, select **WebPI** to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer. - 1. Run the installer. Select the **Install** button and accept the license terms. A restart isn't required after the install completes. -1. Open the **Internet Information Services (IIS) Manager** by executing **inetmgr.exe** from a run command prompt or by searching for **IIS** and selecting the app's link in the search results. -1. In the **Connections** sidebar (left side of the window), open the server's node. Right-click the **Sites** folder and select **Add Website** from the menu. -1. Configure the website: - 1. Provide a **Site name**. - 1. Set the **Physical path** to the *publish* folder of the deployed Blazor app. The *publish* folder contains: - * The *web.config* file that IIS uses to configure the website, including required redirect rules and file content types. - * The app's folder, *MyBlazorApp*. - 1. Configure the **Binding**. Provide a high numbered port (for example, 8000) and leave the **Host name** blank or set it to `localhost`. - 1. Select **OK** to add the website. -1. Select the website in the **Sites** folder. -1. Navigate to the Blazor app: In the IIS Manager's **Action** sidebar (right side of the window), select the link under **Browse Website** to open the app in the default browser. If the port was set to 8000, the Blazor app is available at `http://localhost:8000`. +IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see [Build a Static Website on IIS](https://docs.microsoft.com/iis/manage/creating-websites/scenario-build-a-static-website-on-iis). + +Published assets are created in the *bin\Release\netstandard2.0\publish* folder. Host the contents of the *publish* folder on the web server or hosting service. + +**web.config** + +When a Blazor project is published, a *web.config* file is created with the following IIS configuration: + +* MIME types are set for the following file extensions: + - *\*.dll*: `application/octet-stream` + - *\*.json*: `application/json` + - *\*.wasm*: `application/wasm` + - *\*.woff*: `application/font-woff` + - *\*.woff2*: `application/font-woff` +* HTTP compression is enabled for the following MIME types: + - `application/octet-stream` + - `application/wasm` +* URL Rewrite Module rules are established: + - Serve the sub-directory where the app's static assets reside (`\dist\`). + - Create SPA fallback routing so that requests for non-file assets are redirected to the app's default document in its static assets folder (`\dist\index.html`). + +**Install the URL Rewrite Module** + +The [URL Rewrite Module](https://www.iis.net/downloads/microsoft/url-rewrite) is required to rewrite URLs. The module isn't installed by default, and it isn't available for install as an Web Server (IIS) role service feature. The module must be downloaded from the IIS website. Use the Web Platform Installer to install the module: + +1. Locally, navigate to the [URL Rewrite Module downloads page](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads). For the English version, select **WebPI** to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer. +1. Copy the installer to the server. Run the installer. Select the **Install** button and accept the license terms. A server restart isn't required after the install completes. + +**Configure the website** + +Set the website's **Physical path** to the Blazor app's folder. The folder contains: + +* The *web.config* file that IIS uses to configure the website, including the required redirect rules and file content types. +* The app's static asset folder. + +**Troubleshooting** + +If a *500 Internal Server Error* is received and IIS Manager throws errors when attempting to access the website's configuration, confirm that the URL Rewrite Module is installed. When the module isn't installed, the *web.config* file can't be parsed by IIS. This prevents the IIS Manager from loading the website's configuration and the website from serving Blazor's static files. + +For more information on troubleshooting deployments to IIS, see [Troubleshoot ASP.NET Core on IIS](https://docs.microsoft.com/aspnet/core/host-and-deploy/iis/troubleshoot). ### Nginx From ae3a4dee7bb906d85298373a36ffeb2015715df0 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Fri, 6 Apr 2018 01:37:14 -0500 Subject: [PATCH 7/8] React to feedback Add Dan Update Update Updates Updates Updates --- docs/host-and-deploy/index.md | 56 +++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index 89f448d..9933799 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -13,19 +13,35 @@ uid: client-side/blazor/host-and-deploy/index --- # Host and deploy Blazor -By [Luke Latham](https://github.com/guardrex) and [Rainer Stropek](https://www.timecockpit.com) +By [Luke Latham](https://github.com/guardrex), [Rainer Stropek](https://www.timecockpit.com), and [Daniel Roth](https://github.com/danroth27) [!INCLUDE[](~/includes/blazor-preview-notice.md)] -## Reduction in payload size on build +## Publishing the app -As part of the build process, unused methods and assemblies are removed to reduce app download size and speed up load times. +Blazor apps are published for deployment in Release configuration with the [dotnet publish](https://docs.microsoft.com/dotnet/core/tools/dotnet-publish) command. An IDE may handle executing the `dotnet publish` command automatically using its built-in publishing features, so it might not be necessary to manually execute the command from a command prompt depending on the development tools in use. + +```console +dotnet publish -c Release +``` + +`dotnet publish` triggers a [restore](https://docs.microsoft.com/dotnet/core/tools/dotnet-restore) of the project's dependencies and [builds](https://docs.microsoft.com/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. The deployment is created in the */bin/Release/\/publish* folder. + +The assets in the *publish* folder are deployed to the web server. Deployment might be a manual or automated process depending on the development tools in use. + +There are two deployment models for Blazor apps: + +* [Hosted deployment with ASP.NET Core](#hosted-deployment-with-aspnet-core) – Hosted deployment uses an ASP.NET Core app on the server to host the Blazor app. +* [Standalone deployment](#standalone-deployment) – Standalone deployment places the Blazor app on a static hosting web server or service, where .NET isn't used to serve the Blazor app. ## Hosted deployment with ASP.NET Core -In a hosted deployment, an ASP.NET Core app handles single-page application routing and hosts the Blazor app's static files. The published app is deployed to the web server or hosting service. +In a hosted deployment, an ASP.NET Core app handles single-page application routing and Blazor app hosting. The published ASP.NET Core app, along with one or more Blazor apps that it hosts, is deployed to the web server or hosting service. -In the ASP.NET Core app, each hosted Blazor app is configured with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`: +To host a Blazor app, the ASP.NET Core app must: + +* Reference the Blazor app project. +* Configure Blazor app hosting with the `UseBlazor` extension method on [IApplicationBuilder](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder) in `Startup.Configure`. ```csharp public void Configure(IApplicationBuilder app, IHostingEnvironment env) @@ -41,10 +57,10 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env) The `UseBlazor` extension method performs the following tasks: -* Configures [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. -* Configure single-page application routing for files outside of the *_framework* folder, which serves the default page (*index.html*) for any request that hasn't been served by a prior Static File Middleware instance. +* Configure [Static File Middleware](https://docs.microsoft.com/aspnet/core/fundamentals/static-files) to serve Blazor's static assets from the *dist* folder. In the Development environment, the files in *wwwroot* are served. +* Configure single-page application routing for resource requests that aren't for actual files that exist on disk. The app serves the default document (*index.html*) for any request that hasn't been served by a prior Static File Middleware instance. For example, a request to receive a page from the app that should be handled by the Blazor router on the client is rewritten into a request for the *index.html* page. -For information on ASP.NET Core app hosting and deployment, see [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy). +When the ASP.NET Core app is published, the Blazor app is included in the published output so that the ASP.NET Core app and the Blazor app can be deployed together. For more information on ASP.NET Core app hosting and deployment, see [Host and deploy ASP.NET Core](https://docs.microsoft.com/aspnet/core/host-and-deploy). For information on deploying to Azure App Service, see the following topics: @@ -62,8 +78,8 @@ In a standalone deployment, only the Blazor client-side app is deployed to the s Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: -* **_Main.cshtml_**: Loads at the root of the app and contains a link to the About page (`href="/About"`). -* **_About.cshtml_**: About page. +* **_Main.cshtml_** – Loads at the root of the app and contains a link to the About page (`href="/About"`). +* **_About.cshtml_** – About page. When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): @@ -76,7 +92,13 @@ On the Main page, selecting the link to the About page loads the About page. Sel If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. -Because browsers make requests to Internet-based hosts for client-side pages, web servers and services must rewrite all requests to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. +Because browsers make requests to Internet-based hosts for client-side pages, web servers and hosting services must rewrite all requests for resources not physically on the server to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. + +**App base path** + +The app base path is the virtual app root path on the server. For example, an app that resides on the Contoso server in a virtual folder at `/CoolBlazorApp` is reached at `https://www.contoso.com/CoolBlazorApp` and has a virtual base path of `/CoolBlazorApp`. By setting the app base path to `/CoolBlazorApp`, the app is made aware of where it virtually resides on the server. The app can use the app base path to construct URLs relative to the app root from a component that isn't in the root directory. This allows components that exist at different levels of the directory structure to build links to other resources at locations throughout the app. The app base path is also used to intercept hyperlink clicks where the `href` target of the link is within the app base path URI space—the Blazor router handles the internal navigation. + +In many hosting scenarios, the server's virtual path to the app is the root of the app. In these cases, the app base path is `/`, which is the default configuration for a Blazor app. In other hosting scenarios, such as GitHub Pages and IIS virtual directories, the app base path must be set to the server's virtual path to the app. To set the Blazor app's base path, update the **\** tag in *index.html*. Change the `href` attribute value from `/` to `/`, where `` is the full virtual app root path on the server for the app. ## Static hosting strategies for standalone apps @@ -86,7 +108,7 @@ When deploying a standalone Blazor app, any web server or hosting service that s IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see [Build a Static Website on IIS](https://docs.microsoft.com/iis/manage/creating-websites/scenario-build-a-static-website-on-iis). -Published assets are created in the *bin\Release\netstandard2.0\publish* folder. Host the contents of the *publish* folder on the web server or hosting service. +Published assets are created in the *\\bin\\Release\\\\\publish* folder. Host the contents of the *publish* folder on the web server or hosting service. **web.config** @@ -102,8 +124,8 @@ When a Blazor project is published, a *web.config* file is created with the foll - `application/octet-stream` - `application/wasm` * URL Rewrite Module rules are established: - - Serve the sub-directory where the app's static assets reside (`\dist\`). - - Create SPA fallback routing so that requests for non-file assets are redirected to the app's default document in its static assets folder (`\dist\index.html`). + - Serve the sub-directory where the app's static assets reside (*\\\dist\\\*). + - Create SPA fallback routing so that requests for non-file assets are redirected to the app's default document in its static assets folder (*\\\dist\\index.html*). **Install the URL Rewrite Module** @@ -127,7 +149,7 @@ For more information on troubleshooting deployments to IIS, see [Troubleshoot AS ### Nginx -The following *nginx.conf* file is simplified to show how to configure Nginx to send the *Index.html* file whenever it cannot find a corresponding file on disk. +The following *nginx.conf* file is simplified to show how to configure Nginx to send the *Index.html* file whenever it can't find a corresponding file on disk. ``` events { } @@ -147,6 +169,8 @@ For more information on production Nginx web server configuration, see [Creating ### Nginx in Docker +To host Blazor in Docker using Nginx, setup the Dockerfile to use the Alpine-based Nginx image. Update the Dockerfile to copy the *nginx.config* file into the container. + Add one line to the Dockerfile, as shown in the following example: ``` @@ -159,4 +183,4 @@ COPY nginx.conf /etc/nginx/nginx.conf To handle URL rewrites, add a *404.html* file with a script that handles redirecting the request to the *index.html* page. For an example implementation provided by the community, see [Single Page Apps for GitHub Pages](http://spa-github-pages.rafrex.com/) ([rafrex/spa-github-pages on GitHub](https://github.com/rafrex/spa-github-pages#readme)). An example using the community approach can be seen at [blazor-demo/blazor-demo.github.io on GitHub](https://github.com/blazor-demo/blazor-demo.github.io) ([live site](https://blazor-demo.github.io/)). -There's also a potential issue when using a project site instead of an organization site. Project sites have a path, so the base tag in *index.html* should be updated from `/` to `/`. +When using a project site instead of an organization site, update the **\** tag in *index.html*. Change the `href` attribute value from `/` to `/`, where `` is the GitHub repository name. From 24794f8f794d82583776f3d9e67aa47afbc603ce Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Tue, 10 Apr 2018 01:38:35 -0500 Subject: [PATCH 8/8] Reorganize outline --- docs/host-and-deploy/index.md | 72 +++++++++++++++++------------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/host-and-deploy/index.md b/docs/host-and-deploy/index.md index 9933799..3f8d35a 100644 --- a/docs/host-and-deploy/index.md +++ b/docs/host-and-deploy/index.md @@ -17,7 +17,7 @@ By [Luke Latham](https://github.com/guardrex), [Rainer Stropek](https://www.time [!INCLUDE[](~/includes/blazor-preview-notice.md)] -## Publishing the app +## Publish the app Blazor apps are published for deployment in Release configuration with the [dotnet publish](https://docs.microsoft.com/dotnet/core/tools/dotnet-publish) command. An IDE may handle executing the `dotnet publish` command automatically using its built-in publishing features, so it might not be necessary to manually execute the command from a command prompt depending on the development tools in use. @@ -29,12 +29,40 @@ dotnet publish -c Release The assets in the *publish* folder are deployed to the web server. Deployment might be a manual or automated process depending on the development tools in use. +## Rewrite URLs for correct routing + +Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: + +* **_Main.cshtml_** – Loads at the root of the app and contains a link to the About page (`href="/About"`). +* **_About.cshtml_** – About page. + +When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): + +1. The browser makes a request. +1. The default page is returned, which is usually *index.html*. +1. *index.html* bootstraps the app. +1. Blazor's router loads and the Razor Main page (*Main.cshtml*) is displayed. + +On the Main page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. + +If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. + +Because browsers make requests to Internet-based hosts for client-side pages, web servers and hosting services must rewrite all requests for resources not physically on the server to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. + +## App base path + +The app base path is the virtual app root path on the server. For example, an app that resides on the Contoso server in a virtual folder at `/CoolBlazorApp` is reached at `https://www.contoso.com/CoolBlazorApp` and has a virtual base path of `/CoolBlazorApp`. By setting the app base path to `/CoolBlazorApp`, the app is made aware of where it virtually resides on the server. The app can use the app base path to construct URLs relative to the app root from a component that isn't in the root directory. This allows components that exist at different levels of the directory structure to build links to other resources at locations throughout the app. The app base path is also used to intercept hyperlink clicks where the `href` target of the link is within the app base path URI space—the Blazor router handles the internal navigation. + +In many hosting scenarios, the server's virtual path to the app is the root of the app. In these cases, the app base path is `/`, which is the default configuration for a Blazor app. In other hosting scenarios, such as GitHub Pages and IIS virtual directories, the app base path must be set to the server's virtual path to the app. To set the Blazor app's base path, update the **\** tag in *index.html*. Change the `href` attribute value from `/` to `/`, where `` is the full virtual app root path on the server for the app. + +## Deployment models + There are two deployment models for Blazor apps: * [Hosted deployment with ASP.NET Core](#hosted-deployment-with-aspnet-core) – Hosted deployment uses an ASP.NET Core app on the server to host the Blazor app. * [Standalone deployment](#standalone-deployment) – Standalone deployment places the Blazor app on a static hosting web server or service, where .NET isn't used to serve the Blazor app. -## Hosted deployment with ASP.NET Core +### Hosted deployment with ASP.NET Core In a hosted deployment, an ASP.NET Core app handles single-page application routing and Blazor app hosting. The published ASP.NET Core app, along with one or more Blazor apps that it hosts, is deployed to the web server or hosting service. @@ -70,41 +98,13 @@ Learn how to publish an ASP.NET Core-hosted Blazor app to Azure App Service usin [Publish to Azure with CLI tools](https://docs.microsoft.com/aspnet/core/tutorials/publish-to-azure-webapp-using-cli) Learn how to publish an ASP.NET Core app to Azure App Service using the Git command-line client. -## Standalone deployment +### Standalone deployment In a standalone deployment, only the Blazor client-side app is deployed to the server or hosting service. An ASP.NET Core server-side app isn't used to host the Blazor app. The Blazor app's static files are requested by the browser directly from the static file web server or service. -**Rewrite URLs for correct routing** - -Routing requests for page components in a client-side app isn't as simple as routing requests to a server-side, hosted app. Consider a client-side app with two pages: - -* **_Main.cshtml_** – Loads at the root of the app and contains a link to the About page (`href="/About"`). -* **_About.cshtml_** – About page. - -When the app's default document is requested using the browser's address bar (for example, `https://www.contoso.com/`): - -1. The browser makes a request. -1. The default page is returned, which is usually *index.html*. -1. *index.html* bootstraps the app. -1. Blazor's router loads and the Razor Main page (*Main.cshtml*) is displayed. - -On the Main page, selecting the link to the About page loads the About page. Selecting the link to the About page works on the client because the Blazor router stops the browser from making a request on the Internet to `www.contoso.com` for `/About` and serves the About page itself. All of the requests for internal pages *within the client-side app* work the same way: Requests don't trigger browser-based requests to server-hosted resources on the Internet. The router handles the requests internally. - -If a request is made using the browser's address bar for `www.contoso.com/About`, the request fails. No such resource exists on the app's Internet host, so a *404 Not found* response is returned. - -Because browsers make requests to Internet-based hosts for client-side pages, web servers and hosting services must rewrite all requests for resources not physically on the server to the *index.html* page. When *index.html* is returned, the app's client-side router takes over and responds with the correct resource. - -**App base path** - -The app base path is the virtual app root path on the server. For example, an app that resides on the Contoso server in a virtual folder at `/CoolBlazorApp` is reached at `https://www.contoso.com/CoolBlazorApp` and has a virtual base path of `/CoolBlazorApp`. By setting the app base path to `/CoolBlazorApp`, the app is made aware of where it virtually resides on the server. The app can use the app base path to construct URLs relative to the app root from a component that isn't in the root directory. This allows components that exist at different levels of the directory structure to build links to other resources at locations throughout the app. The app base path is also used to intercept hyperlink clicks where the `href` target of the link is within the app base path URI space—the Blazor router handles the internal navigation. - -In many hosting scenarios, the server's virtual path to the app is the root of the app. In these cases, the app base path is `/`, which is the default configuration for a Blazor app. In other hosting scenarios, such as GitHub Pages and IIS virtual directories, the app base path must be set to the server's virtual path to the app. To set the Blazor app's base path, update the **\** tag in *index.html*. Change the `href` attribute value from `/` to `/`, where `` is the full virtual app root path on the server for the app. - -## Static hosting strategies for standalone apps - -When deploying a standalone Blazor app, any web server or hosting service that serves static files can host a Blazor app. +When deploying a standalone Blazor app from the published *dist* folder, any web server or hosting service that serves static files can host a Blazor app. -### IIS +#### IIS IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see [Build a Static Website on IIS](https://docs.microsoft.com/iis/manage/creating-websites/scenario-build-a-static-website-on-iis). @@ -147,7 +147,7 @@ If a *500 Internal Server Error* is received and IIS Manager throws errors when For more information on troubleshooting deployments to IIS, see [Troubleshoot ASP.NET Core on IIS](https://docs.microsoft.com/aspnet/core/host-and-deploy/iis/troubleshoot). -### Nginx +#### Nginx The following *nginx.conf* file is simplified to show how to configure Nginx to send the *Index.html* file whenever it can't find a corresponding file on disk. @@ -167,7 +167,7 @@ http { For more information on production Nginx web server configuration, see [Creating NGINX Plus and NGINX Configuration Files](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/). -### Nginx in Docker +#### Nginx in Docker To host Blazor in Docker using Nginx, setup the Dockerfile to use the Alpine-based Nginx image. Update the Dockerfile to copy the *nginx.config* file into the container. @@ -179,7 +179,7 @@ COPY ./bin/Release/netstandard2.0/publish /usr/share/nginx/html/ COPY nginx.conf /etc/nginx/nginx.conf ``` -### GitHub Pages +#### GitHub Pages To handle URL rewrites, add a *404.html* file with a script that handles redirecting the request to the *index.html* page. For an example implementation provided by the community, see [Single Page Apps for GitHub Pages](http://spa-github-pages.rafrex.com/) ([rafrex/spa-github-pages on GitHub](https://github.com/rafrex/spa-github-pages#readme)). An example using the community approach can be seen at [blazor-demo/blazor-demo.github.io on GitHub](https://github.com/blazor-demo/blazor-demo.github.io) ([live site](https://blazor-demo.github.io/)).