From c226a015eb37f4d71b6aa634b62ff94d27d24a25 Mon Sep 17 00:00:00 2001 From: Dustin Moris Gorski Date: Mon, 23 Nov 2020 18:33:09 +0000 Subject: [PATCH] Added missing link to endpoint routing --- DOCUMENTATION.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index c5c82e0c..f064fd39 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -46,6 +46,7 @@ An in depth functional reference to all of Giraffe's default features. - [Common Helper Functions](#common-helper-functions) - [Computation Expressions](#computation-expressions) - [Additional Features](#additional-features) + - [Endpoint Routing](#endpoint-routing) - [TokenRouter](#tokenrouter) - [Razor](#razor) - [DotLiquid](#dotliquid) @@ -3263,17 +3264,17 @@ There's more features available for Giraffe web applications through additional ### Endpoint Routing Starting with Giraffe 5.x we introduced a new module called `Giraffe.EndpointRouting`. The endpoint routing module implements an alternative router to Giraffe's default routing functions which integrates with [ASP.NET Core's endpoint routing APIs](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-5.0). - + Given the way how ASP.NET Core's Endpoint Routing works this module comes with several benefits (and unfortunately also some minor downsides) in comparison to Giraffe's default router. The main benefit of `Giraffe.EndpointRouting` is that it nicely integrates with the rest of ASP.NET Core and can benefit from everything which Endpoint Routing makes possible. It also means that any performance improvements made to the ASP.NET Core router will directly translate to Giraffe. The downsides are that several existing routing functions couldn't be ported to `Giraffe.EndpointRouting` and routes are case-insensitive by default. Whilst this can be a problem with some applications overall the limitations are minimal and the benefits should greatly outweigh the downsides in the long term. Endpoint Routing is definitely the new preferred option of routing in ASP.NET Core and will undoubtedly see a lot of investment and improvements by the ASP.NET team over the years. - + At last it is possible to have the `Giraffe.EndpointRouting` module and Giraffe's default router work side by side, benefiting from Endpoint Routing where possible and keeping the default router elsewhere. - + #### Endpoint Routing Basics - + In order to make use of Giraffe's endpoint routing functions one has to open the required module first: - + ```fsharp -open Giraffe.EndpointRouting +open Giraffe.EndpointRouting ``` Giraffe's HTTP handlers remain unchanged regardless if they are used from a typical Giraffe router or the `Giraffe.EndpointRouting` module. This makes porting to the `Giraffe.EndpointRouting` module tremendously easy: @@ -3329,7 +3330,7 @@ The following routing functions are available as part of the `Giraffe.EndpointRo The `route`, `routef` and `subRoute` handlers are all case-insensitive. Other handlers such as `routex`, `subRoutef` or `choose` are not supported by the `Giraffe.EndpointRouting` module. -The `choose` handler is replaced by composing an `Endpoint list`. +The `choose` handler is replaced by composing an `Endpoint list`. Other routing handlers couldn't be ported like for like, but the ASP.NET Core Endpoint Routing API allows for greater control and better insight into an endpoint by exposing useful helper functions. @@ -3344,10 +3345,10 @@ let myHandler (foo : int, bar : string) : HttpHandler = let routeData = ctx.GetRouteData() routeData.Values // Values produced on the current path routeData.DataTokens // Tokens produced on the current path - + sprintf "Yada Yada %i %s" foo bar |> ctx.WriteTextAsync -``` +``` The `GetEndpoint` extension method returns the endpoint for the currently executed path and can be used to further explore the metadata and other data attached to this endpoint: