Aspnetcore.docs: 1.1 feature: URL Rewriting Middleware

[tdykstra]

From the list in #2260

[guardrex]

@Rick-Anderson Are you good for coverage on this one? Otherwise, I chatted with @tdykstra about working on grammar+style (e.g., commas, third person, etc.) in existing docs, so I can work on some of those if you like.

[Rick-Anderson]

@GuardRex let's hold off on editing for now. I thought you wanted to do this article?

[guardrex]

@Rick-Anderson Yes, that's awesome, thanks. :smile: This one is especially interesting to me because over the years I've been generally unhappy with every doc out there on URL Rewrite rules (regular expressions) for IIS. I want to take a crack at presenting the "rules" part of the doc in a clear and helpful manner that will put other docs to shame.

Will Pranav, Nate, Mikael, or Justin provide an outline for this, or would you like me to float it?

[Rick-Anderson]

@GuardRex I'll get you an outline and some more info.

[Rick-Anderson]

@danroth27 who's the right dev to provide an outline and sample code (perhaps pointing to samples/unit tests in repro).

[guardrex]

This seems to need a URL Rewriting Middleware doc stub.

[Rick-Anderson]

@mikaelm12 please provide an outline and a code sample. [@]Tratcher will review.

[guardrex]

Cross-ref: https://github.com/aspnet/Docs/issues/1839

[guardrex]

@mikaelm12 I have some time this weekend to write, so I'd like to get a little bit down "on paper." This is highly brainstormed ... I just rattled off some ideas. I'll be writing to your outline. This is just to get me started today with a few sections.

• Introduction
  
  
  
  • What is URL Rewriting?
  
  
  • Use cases (abstraction: URL from location)
  
  
  • Moving a resource on the network
  
  
  • Search Engine Optimization (SEO)
  
  
  • Redirecting insecure requests to secure endpoints
  
  
  • Modifying URLs
  
  
  • URL redirect versus URL rewrite
  
  
  • Response Status Codes: 301 (Moved Permanently) vs. 302 (Found)
  
  
• URL Rewrite Middleware
  
  
  
  • When to use URL Rewrite Middleware (when not behind IIS or Apache)
  
  
  • Package - Microsoft.AspNetCore.Rewrite
  
  
  • Extension & Options - RewriteOptions() + app.UseRewriter(options)
  
  
  • Note chaining
  
  
  • AddRedirect
    
    
    
    
    
    • (string regex, string replacement) Default statusCode: 302 (Found)
    
    
    
    • (string regex, string replacement, int statusCode)
    
    
    
  
  
  • AddRedirectToHttps
    
    
    
    
    
    • () Default statusCode: 302 (Found) port: null
    
    
    
    • (int statusCode) Default port: null
    
    
    
    • (int statusCode, int port)
    
    
    
  
  
  • AddRedirectToHttpsPermanent()
    
    
    
    
    
    • () Default statusCode: 301 (Moved Permanently)
    
    
    
  
  
  • AddRewrite(string regex, string replacement, skipRemainingRules: true/false)
    
    
    
    
    
    • skipRemainingRules and performance
    
    
    
  
  
  • AddApacheModRewrite(IFileProvider fileProvider, string filePath)
    
    
    
    
    
    • Deployment must include URLRewrite.txt
    
    
    
    • Link best "official" mod_rewrite doc
    
    
    
    • Supported server variables ref
    
    
    
  
  
  • AddIISUrlRewrite(IFileProvider fileProvider, string filePath)
    
    
    
    
    
    • Deployment must include URLRewrite.xml
    
    
    
    • Link overview IIS.net doc
    
    
    
    • Disabling IIS Rewrite Module in web.config
    
    
    
    • Unsupported features
      
      
      i. Global rules
      
      
      ii. Rewrite Maps
      
      
      iii. CustomResponse action
      
      
      iv. Server Variables/Custom Server Variables
      
      
      v. AbortRequest action
      
      
      vi. None action
      
      
      vii. trackAllCaptures
      
      
      viii. WildCards
      
      
      ix. LogRewrittenUrl
    
    
    
    • Supported server variables ref
    
    
    
  
  
  • Add(Action)
  
  
  • Add(IRule)
  
  
  • Regex Examples
  
  
• Additional Resources
  
  
  
  • Application Startup
  
  
  • Middleware
  
  
  • Regular expressions in .NET
  
  
  • Regular expression language - quick reference
  
  
  • Apache mod_rewrite
  
  
  • Using Url Rewrite Module 2.0 (for IIS)
  
  
  • URL Rewrite Module Configuration Reference
  
  
  • IIS URL Rewrite Module Forum
  
  
  • Keep a simple URL structure
  
  
  • 10 URL Rewriting Tips and Tricks
  
  

[mikaelm12]

@GuardRex Thanks for writing the outline! It looks great.

One thing that might be nice to add to this list is the different types of actions in addition to the Redirect and Rewrite. The abort and Gone actions for example.

Another point might be why use our rewriting middleware instead of the module provided by IIS.

A note on performance might also be nice. We did a basic perf investigation in https://github.com/aspnet/BasicMiddleware/pull/105 and with large numbers of poorly written rules the performance tanks.

Also, currently the Custom response action and TrackAllCaptures features are not supported yet.

[mikaelm12]

Anything else that you think should go in there @Tratcher ?

[guardrex]

@mikaelm12

One thing that might be nice to add to this list is the different types of actions in addition to the Redirect and Rewrite. The abort and Gone actions for example.

I'm not quite following "Abort" and "Gone" (outside of status codes). How do you mean?

Another point might be why use our rewriting middleware instead of the module provided by IIS.

Yes, and the recommendation has been to use IIS or use Apache mod_rewrite when available. I've updated the outline to include that point in the Intro: "When to use URL Rewriting middleware?"

A note on performance might also be nice.

I have a note at "skipRemainingRules and performance" to talk about that. Did you want something more dedicated. Because perf is so highly variable based on the number and types of rules and because less than ten rules seems not to hurt perf so badly, I was just going to touch on making sure they suspend additional rules when one matches if they don't need additional rule processing on a request.

currently the Custom response action and TrackAllCaptures features are not supported yet.

By "custom response action," do you mean Add(Action<RewriteContext>) and/or Add(IRule)? I tested those and they seem to work ok.

I have no familiarity with TrackAllCaptures? I'll look it up, but if you have a link or additional info, I'll find out what you mean on that one.

[Tratcher]

It would be good to have a more comprehensive list of not supported features. @mikaelm12 what else isn't supported yet?

Why us this vs IIS:

• Use it when you're not behind IIS
• Some of the IIS rules do not work with the ASP.NET Core project layout, like IsFile and IsDirectory. There is a common rule for angular that uses these and people keep breaking on. We fixed these in the middleware version. https://github.com/aspnet/IISIntegration/issues/192#issuecomment-230000908

[mikaelm12]

The custom response action I referred to is actually its own type of action docs here, There they also describe the other actions types like Abort.

Here is a link to docs for trackAllCaptures feature. In a nutshell it allows you to keep track of captures groups across conditions. There is a PR for this now.

Global rules also currently aren't supported.

I have a note at "skipRemainingRules and performance" to talk about that. Did you want something more dedicated.

Nope. I think that's fine. I just wanted to make sure that it was mentioned because of the potential for serious performance hits.

[guardrex]

@mikaelm12 I added an "Unsupported features" entry under AddIISUrlRewrite and listed the items mentioned. How does it look?

[guardrex]

@mikaelm12 I'm wrapping up the Response Caching doc with [@]JunTaoLuo now, so I should get back to this one Friday morning and jam on it right through the weekend :guitar:. How does the outline look now?

[guardrex]

@Rick-Anderson Looks like this Url Rewrite doc needs a doc stub/location.

[Rick-Anderson]

@tdykstra can you work with @GuardRex on this?

[guardrex]

@Rick-Anderson My coauthor on this one is Tom and not Mikael? ... or both?

[Rick-Anderson]

@GuardRex - @tdykstra will manage/UE review/merge/etc

[tdykstra]

I'll create the doc stub but need a TOC location ...

@danroth27 Is under Fundamentals/Middleware the best TOC location? E.g.,

• Middleware (node goes to current Middleware doc, expands to show URL Rewriting under it)
  
  
  
  • URL Rewriting Middleware
  
  

This article is not really about "fundamentals" but I don't see a logical place for it elsewhere. The only alternative I see is Publishing, but it doesn't seem to fit well there.

[tdykstra]

@GuardRex Pending review by @danroth27 et al, I put the stub in hosting/url-rewriting.md. It's not ideal but on second thought seems a better fit than fundamentals or publishing. If we find a better place for it later we can move it.

[guardrex]

@tdykstra

RE: Title URL Rewriting Middleware

According to the outline and bits of discussion, this is going to be the definitive doc on the subject, so there won't be two docs (a URL rewriting doc and a middleware doc). If that's correct (one doc to cover the whole subject), I'll change the TOC+index title to URL Rewriting in my branch, so that will update on master with the PR later.

Otherwise, I'll need to strip the introduction out of the outline and my draft and just title case URL rewriting middleware to URL Rewriting Middleware.

[tdykstra]

Changing the title is fine, I just took what was in the section heading of the announcement blog.

[guardrex]

Cross-ref WRT server variables lack of parity: https://github.com/aspnet/BasicMiddleware/issues/195