Host and deploy topic #15

guardrex · 2018-04-04T04:08:34Z

Fixes #5

Azure CDN hosting ... I wish! There are several problems to address. I don't even want to open an issue for it given that it will likely require engineering changes to work.
Links off to our aspnet/Docs topics for ASP.NET Core hosting.
We have a section here on using IIS (local and Win Server) as a static file server, which we don't have over in the aspnet/Docs.
Info from @rstropek for Nginx and Nginx on Docker is present.
@rstropek will circle around later to add a section on Azure App Service hosting. Add Azure App Service to the Host and deploy topic #18

Host and deploy topic

rstropek

I think a section about hosting Blazor on Azure App Service would be very relevant. If you want, I could try to contribute it.

docs/host-and-deploy/index.md

guardrex · 2018-04-04T06:02:09Z

@rstropek Cool ... I'll make those changes right now.

rstropek · 2018-04-04T06:03:32Z

Did you see my comment about the missing Azure App Service section? Do you also think it would be important?

guardrex · 2018-04-04T06:05:01Z

Yes, sounds great. Let me put this commit in for your feedback, then you can branch from this branch and submit a PR back to this branch ... if that makes sense 😵 ... I'm sure u know what I mean. 😄

guardrex · 2018-04-04T06:13:18Z

@rstropek Ok ... all set. I'm headed off to bed. 💤 🛌 💤

I'll just do a grammar+style pass after I merge your PR. I'll take it off of WIP after that and call for review.

Feel free to take a look at the components one, too, if you want. No rush, of course. We still have plenty of time.

rstropek · 2018-04-04T15:05:18Z

I am sorry but I did not make it to write the chapter about deployment to Azure App Service. I think we have to postpone that until after the launch of the initial set of docs.

guardrex · 2018-04-04T15:15:37Z

@rstropek No worries. I opened #18 and backlogged it.

I'll call for review on this now.

guardrex · 2018-04-04T15:29:21Z

@rstropek I think I should change the "Blazor Middleware" remarks. UseBlazor configures the middleware pipeline to work with Blazor ... doesn't seem to be "middleware" really (but it does configure middleware). Thoughts?

[EDIT] I went ahead and made this change.

SteveSandersonMS

Cool, good stuff!

SteveSandersonMS · 2018-04-04T22:16:15Z

docs/host-and-deploy/index.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:


Just as a general point, is the passive tone considered house style? I would normally write something like "You can publish a Blazor app for deployment using the following command..."

Yes, we avoid 2nd person whenever possible, which often leads to passive voice. It's more of a repo rule than a MS style manual guideline.

SteveSandersonMS · 2018-04-04T22:19:45Z

docs/host-and-deploy/index.md

+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.


Instead of saying it strips unused IL, could we say it strips unused methods? (which BTW is the actual level of granularity it works on)

Example:

As part of the build process, the .NET linker removes any unused methods and assemblies. This makes the resulting application payload much smaller than it would have been if the entire .NET Base Class Library (BCL) was packaged with it.

The link is actually run on every build, not just on publish. I would also prefer not to use the made up name ".NET linker". Instead how about: "When the app is published it will first be built (if it hasn't been already). As part of the build any used methods and assemblies will be removed to reduce app download size and speed up load times."

SteveSandersonMS · 2018-04-04T22:21:31Z

docs/host-and-deploy/index.md

+
+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.


The assets in the publish folder are moved to the web server.

That's misleading as it implies it happens automatically. Just running dotnet publish doesn't do this. I'm guessing you intend to say something like "The contents of the publish directory are what you need to deploy to your production web server".

That's misleading as it implies it happens automatically.

Yep ... let's make a new section for this remark called Deployment. We can expand the language from there on the next commit if needed.

SteveSandersonMS · 2018-04-04T22:28:42Z

docs/host-and-deploy/index.md

+
+[!INCLUDE[](~/includes/blazor-preview-notice.md)]
+
+## Publishing


The structure of this doc might be a bit confusing. I think we should make clear the two different hosting models (standalone and hosted-on-ASP.NET) and explain what you need to do to deploy in each case. Example:

This "Publishing" subheading relates to standalone but not to the hosted-on-ASP.NET model. We don't want to confuse people doing hosted-on-ASP.NET by implying they should be running dotnet publish on the client app.

The "Rewrite URLs for correct routing" content applies to standalone publishing only.

People using the "Blazor hosted" template (i.e., the hosted-on-ASP.NET publishing model) don't need to do anything other than the normal ASP.NET server-side publishing process, so I hope we can just link to those docs. We just need to emphasise that it's the server project you need to publish, not the client one (which automatically gets included with the server).

SteveSandersonMS · 2018-04-04T22:29:36Z

docs/host-and-deploy/index.md

+
+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


This is good content but we should be clear it's only applicable to publishing standalone (not ASP.NET-hosted) Blazor apps.

I think most of the content in this section belongs in the routing doc, not here. It's really only the last two paragraphs that address the host concern of dealing with requests to specific pages.

SteveSandersonMS · 2018-04-04T22:30:11Z

docs/host-and-deploy/index.md

+
+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.


Let's not mention the .blazor.config files - it's an implementation detail that might change

SteveSandersonMS · 2018-04-04T22:30:23Z

docs/host-and-deploy/index.md

+
+* 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.


No live reloading in 0.2.0 any more

SteveSandersonMS · 2018-04-04T22:30:58Z

docs/host-and-deploy/index.md

+
+## 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).


This bug is fixed, but in any case developers shouldn't have to know about the .blazor.config files. There's nothing you can do with them manually.

I think this section should be removed.

SteveSandersonMS · 2018-04-04T22:34:27Z

docs/host-and-deploy/index.md

+
+## 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.


This phrasing feels overcomplicated. Suggestion: If you're deploying a standalone Blazor application, you can use any web server that serves static files.

Well, can't use "you" (unless it can't be avoided). How about ...

When deploying a standalone Blazor app, any web server or hosting service that serves static files can host a Blazor app.

Although, we'll eat those words with Azure CDN AFAICT. I might need to take a little more time with it. I noted that @danroth27 said in an issue comment that the _ (underscore) prefix on the _frameworks folder can be removed.

SteveSandersonMS · 2018-04-04T22:36:41Z

docs/host-and-deploy/index.md

+
+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


I wonder how useful it is really to describe how to configure IIS to serve static content. Might there be some external IIS documentation we could link to instead? It's not Blazor-specific. What do you think @danroth27?

If we were going to put in detailed instructions, I'd suggest focusing on Azure app service deployment would be a much higher priority.

@rstropek says he has direct experience with Blazor client-server apps on Azure App Service, and he can link our aspnet/Docs content to help explain and handle troubleshooting. We have an issue open to cover it: #18

RE: IIS static file server

I looked ... the coverage isn't as clear and focused as I would've liked. My (biased) impression is that following these instructions makes IIS config simple and fast. I'll check their IIS topic again and report back.

Ugh .....

https://docs.microsoft.com/iis/manage/creating-websites/scenario-build-a-static-website-on-iis

https://docs.microsoft.com/iis/web-hosting/getting-started/deploying-a-static-content-server

Yeah ... that's what I saw a few days ago. I'd prefer NOT to link those for several reasons, including missing info and references to WS1012.

I would prefer to not document how to install and setup a site with IIS. That should be documented in the IIS docs. I do however agree that piecing together the full set of steps listed here from the IIS docs is not easy. @shirhatti You should consider working with @guardrex to make the IIS docs better so he doesn't have to keep documenting all these steps 😃

I do think we need to document that we generate a web.config file with the right mime type mappings and URL rewrite rules, and that you nee to install the URL rewrite module.

I also think documenting Azure App Service is required. At a minimum we should document that from VS you can right-click -> Publish.

danroth27 · 2018-04-05T05:09:02Z

docs/host-and-deploy/index.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:


I think we need to clarify a bit what "publish" means in this context. Publishing in the .NET Core world means something pretty specific that I believe is different from what most people think of as publishing. Publishing for us means preparing the app to be deployed. You can't just deploy the built output.

So maybe say something like: "To prepare a Blazor app for deployment it first needs to be published. Publishing the app packs the application and its dependencies into a folder for deployment to a hosting system. Blazor apps are published for deployment using the [dotnet publish]((https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish) command. . ."

I have an idea that given how much I just ripped the guts out of this that I should try to work that back in on the following commit (after the next one). I'm performing a big overhaul of the layout here. Let's see where "publish" fits after the next commit, and then I can roll that language into it.

I think that in an IDE one can build/publish and probably (?) get to the assets (dist folder) without running the dotnet publish command directly. Therefore, let's see where the draft goes on the next commit and where it fits.

danroth27 · 2018-04-05T05:11:45Z

docs/host-and-deploy/index.md

+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 link is actually run on every build, not just on publish. I would also prefer not to use the made up name ".NET linker". Instead how about: "When the app is published it will first be built (if it hasn't been already). As part of the build any used methods and assemblies will be removed to reduce app download size and speed up load times."

danroth27 · 2018-04-05T05:13:20Z

docs/host-and-deploy/index.md

+
+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.


hosts of hosted Blazor apps

A bit awkward

danroth27 · 2018-04-05T05:19:39Z

docs/host-and-deploy/index.md

+
+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


I think most of the content in this section belongs in the routing doc, not here. It's really only the last two paragraphs that address the host concern of dealing with requests to specific pages.

danroth27 · 2018-04-05T05:31:01Z

docs/host-and-deploy/index.md

+
+## Host with ASP.NET Core
+
+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`:


I suggest starting this section with: "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 and then configuring each app in the server-side app's middleware pipeline with the UseBlazor extension method on IApplicationBuilder in Startup.Configure:"

danroth27 · 2018-04-05T05:32:08Z

docs/host-and-deploy/index.md

+
+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)


I think this first link is sufficient.

danroth27 · 2018-04-05T05:33:36Z

docs/host-and-deploy/index.md

+
+## 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).


I think this section should be removed.

danroth27 · 2018-04-05T05:45:09Z

docs/host-and-deploy/index.md

+
+### 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


We shouldn't documented "unsupported" things. But it's OK to describe work that needs to be done and then to give example solutions. For example: "To handle URL rewrites you can 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 rafrex/spa-github-pages on GitHub."

There also an issue if you use a project site, instead of an org site. Project sites have a path, so I think you need to update the base tag in index.html from / to /repo-name.

danroth27 · 2018-04-05T05:56:16Z

docs/host-and-deploy/index.md

+
+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


I would prefer to not document how to install and setup a site with IIS. That should be documented in the IIS docs. I do however agree that piecing together the full set of steps listed here from the IIS docs is not easy. @shirhatti You should consider working with @guardrex to make the IIS docs better so he doesn't have to keep documenting all these steps 😃

I do think we need to document that we generate a web.config file with the right mime type mappings and URL rewrite rules, and that you nee to install the URL rewrite module.

danroth27 · 2018-04-05T05:58:37Z

docs/host-and-deploy/index.md

+
+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


I also think documenting Azure App Service is required. At a minimum we should document that from VS you can right-click -> Publish.

guardrex · 2018-04-05T06:53:09Z

@danroth27 @SteveSandersonMS

I think most of the content in this section belongs in the routing doc, not here. It's really only the last two paragraphs that address the host concern of dealing with requests to specific pages.

We don't have the routing doc tho. Shall we leave this here until we can get the routing topic set up and then move the content over? @rstropek and I both slaved over this section ... I'd hate to see this sit on the sidelines.

I do think we need to document that we generate a web.config file with the right mime type mappings and URL rewrite rules, and that you nee to install the URL rewrite module.

Ok, if that's what you want. CSAT is going to suffer. I'll give them the first link and doc the bits we need on the next pass.

For the next round, I have these action items:

~~Possibly pull most of the URL redirect content (but I suggest leaving it until the routing doc is written)~~
Pull the IIS piece, link to that IIS static hosting topic, and document that we generate a web.config file with the right mime type mappings and URL rewrite rules, and that you need to install the URL rewrite module.
Figure out where/how dotnet publish fits and in regard to publishing with IDEs where the command isn't executed directly at a command prompt.
Document web.config features pertaining to Blazor publshing
Azure Apps 👉 one-click publish feature in VS

Let me know given this last commit how the overall structure looks now and any additional comments or notes you have for where/how on those five items ☝️.

danroth27 · 2018-04-05T18:02:49Z

We don't have the routing doc tho. Shall we leave this here until we can get the routing topic set up and then move the content over? @rstropek and I both slaved over this section ... I'd hate to see this sit on the sidelines.

OK, that sounds reasonable.

guardrex · 2018-04-05T23:07:24Z

@SteveSandersonMS @danroth27 Updated based on your comments:

Revised outline:
- Reduction in payload size on build
- Hosted deployment with ASP.NET Core
- Standalone deployment
- Static hosting strategies for standalone apps:
  - IIS
  - Nginx
  - Nginx with Docker
  - GitHub Pages
Links out to Azure App publishing topics in aspnet/Docs
Cuts IIS down to the critical bits:
- URL Rewrite Module
- Configure website
- Troubleshooting
Includes coverage for web.config configuration

It's ready for another look 👀.

Update

danroth27

Most of these updates look good. A few more comments.

danroth27 · 2018-04-06T03:10:22Z

docs/host-and-deploy/index.md

+
+### Nginx in Docker
+
+Add one line to the Dockerfile, as shown in the following example:


This says to modify a Dockerfile that I didn't even know I had yet. Can we add a sentence before this that provides some context? Maybe say something like: "To host Blazor in Docker using Nginx, setup your Dockerfile to use the Alpine based Nginx image. Then update the Dockerfile to copy your nginx.config file into the container.

danroth27 · 2018-04-06T03:18:39Z

docs/host-and-deploy/index.md

+
+[!INCLUDE[](~/includes/blazor-preview-notice.md)]
+
+## Reduction in payload size on build


This feels off topic. Instead I think it makes more sense to start off with a "Publishing your app" section that describes the need to prepare your app for deployment by running dotnet publish like we had discussed earlier. While it's true that your IDE may handle doing the dotnet publish for you, I still think it's an important concept to understand so that you can figure out how to deploy to any host.

After that I think there should be a short section that summarizes the difference between hosted vs standalone deployments and states right up front that you don't need .NET on the server deploy a Blazor app. And after that would be the nice sections you have already with all the specific details on how to do hosted and standalone deployments.

danroth27 · 2018-04-06T03:22:52Z

docs/host-and-deploy/index.md

+
+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 `/<repo-name>`.


I believe it's a real issue not a "potential" issue. Suggested wording: "Also, when using a project site instead of an organization site, update the base tag in index.html from / to /<repo-name>."

Actually, this issue isn't specific to GitHub pages. It also applies when hosted in an IIS vdir. So maybe we should have a short separate section that speaks general updating the base path similar to how we discuss the need for URL rewrite?

I see what you mean in your earlier remark.

danroth27 · 2018-04-06T03:30:38Z

docs/host-and-deploy/index.md

+
+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 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 references the Blazor app project. The ASP.NET Core app is then configured to host Blazor app with the UseBlazor extension method . . .

danroth27 · 2018-04-06T03:34:17Z

docs/host-and-deploy/index.md

+* 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 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 will be included with 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 . . .

danroth27 · 2018-04-06T03:35:31Z

docs/host-and-deploy/index.md

+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.
+


Consider adding a section that discusses setting the base path here.

guardrex · 2018-04-06T06:45:29Z

@danroth27 Updates made.

In the reverted opening section on dotnet publish, this attempts to be explicit about how tooling may automate dotnet publish and deployment.
Explains app base path setting.
Made your suggested updates.

[EDIT] I noticed in blazor.js that the app base path is used in client-side routing, so we might need to expand the app base path purpose explanation to include that its used in link generation and client-side routing.

Add Dan Update Update Updates Updates Updates

danroth27

Looks great! Just one minor comment about flipping the order so that standalone hosting is discussed first.

danroth27 · 2018-04-10T06:06:30Z

docs/host-and-deploy/index.md

+
+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:


Since the standalone section has the detailed discussion on SPA routing and specifying the app base path I think it would make sense to flip the order here and put the standalone section first. That way when these concepts are referred to in the ASP.NET Core section you know what they are.

I think we should reorganize ... it breaks the topic a bit to split the standalone content across the hosted Blazor content.

How about going to this outline:

Publishing

Rewrite URLs for correct routing

App base path

Deployment types

Hosted

Standalone with deployment strategies

guardrex · 2018-04-10T06:39:31Z

@danroth27 Try it now with a revised outline ... it solves the problem you mentioned and keeps the standalone content together.

danroth27 · 2018-04-10T07:29:35Z

Works for me.

Host and deploy topic

3632ed2

Host and deploy topic

guardrex added the 🚧 WIP Work-in-progress - HOLD REVIEW! label Apr 4, 2018

rstropek suggested changes Apr 4, 2018

View reviewed changes

docs/host-and-deploy/index.md Outdated Show resolved Hide resolved

docs/host-and-deploy/index.md Outdated Show resolved Hide resolved

docs/host-and-deploy/index.md Outdated Show resolved Hide resolved

React to feedback

d0192f7

guardrex changed the title ~~[WIP] Host and deploy topic~~ Host and deploy topic Apr 4, 2018

guardrex removed the 🚧 WIP Work-in-progress - HOLD REVIEW! label Apr 4, 2018

guardrex requested review from SteveSandersonMS and danroth27 April 4, 2018 15:16

guardrex added 2 commits April 4, 2018 10:34

Refactor 'Blazor Middleware' language

d9124b0

Add a link for Azure App Service

a10c9d0

SteveSandersonMS reviewed Apr 4, 2018

View reviewed changes

danroth27 suggested changes Apr 5, 2018

View reviewed changes

React to feedback

705e749

React to feedback

a1865bb

Update

guardrex force-pushed the guardrex/host-and-deploy branch from 54dcab1 to a1865bb Compare April 5, 2018 23:14

danroth27 suggested changes Apr 6, 2018

View reviewed changes

guardrex force-pushed the guardrex/host-and-deploy branch from 32d633c to 3ee45ad Compare April 6, 2018 06:44

guardrex force-pushed the guardrex/host-and-deploy branch 2 times, most recently from 6bb1b1f to a4b32ed Compare April 6, 2018 06:56

guardrex force-pushed the guardrex/host-and-deploy branch 2 times, most recently from 02c6fa8 to c5a83cf Compare April 7, 2018 00:25

React to feedback

ae3a4de

Add Dan Update Update Updates Updates Updates

guardrex force-pushed the guardrex/host-and-deploy branch from 1c72bf1 to ae3a4de Compare April 9, 2018 16:18

danroth27 approved these changes Apr 10, 2018

View reviewed changes

Reorganize outline

24794f8

danroth27 approved these changes Apr 10, 2018

View reviewed changes

guardrex merged commit a020a09 into staging Apr 10, 2018

guardrex deleted the guardrex/host-and-deploy branch April 10, 2018 07:31

aspnet deleted a comment Apr 16, 2018

guardrex mentioned this pull request Apr 17, 2018

Host and deploy Blazor: Index topic #5

Closed


		## Publishing

		Blazor apps are published for deployment in Release configuration with the [dotnet publish](https://docs.microsoft.com/dotnet/core/tools/dotnet-publish) command:


		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.


		[!INCLUDE[](~/includes/blazor-preview-notice.md)]

		## Publishing


		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


		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.


		## 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.


		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


		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.


		## Host with ASP.NET Core

		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`:


		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)


		### 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


		### Nginx in Docker

		Add one line to the Dockerfile, as shown in the following example:


		[!INCLUDE[](~/includes/blazor-preview-notice.md)]

		## Reduction in payload size on build


		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 `/<repo-name>`.


		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 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`:


		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:

Host and deploy topic #15

Host and deploy topic #15

Conversation

guardrex commented Apr 4, 2018 • edited Loading

rstropek left a comment

Choose a reason for hiding this comment

guardrex commented Apr 4, 2018

rstropek commented Apr 4, 2018

guardrex commented Apr 4, 2018

guardrex commented Apr 4, 2018

rstropek commented Apr 4, 2018

guardrex commented Apr 4, 2018

guardrex commented Apr 4, 2018 • edited Loading

SteveSandersonMS left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Apr 5, 2018 • edited Loading

danroth27 commented Apr 5, 2018

guardrex commented Apr 5, 2018 • edited Loading

danroth27 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Apr 6, 2018 • edited Loading

danroth27 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Apr 10, 2018

danroth27 commented Apr 10, 2018

guardrex commented Apr 4, 2018 •

edited

Loading

guardrex commented Apr 4, 2018 •

edited

Loading

guardrex commented Apr 5, 2018 •

edited

Loading

guardrex commented Apr 5, 2018 •

edited

Loading

guardrex commented Apr 6, 2018 •

edited

Loading