Oxpecker 0.13.1

Oxpecker

Oxpecker 是一个基于 ASP.NET Core 端点路由的 F# 框架（类似于 Minimal APIs，因此它们是竞争对手），具有易于理解的 API，主要继承了 Giraffe 框架。

Nuget 包 dotnet add package Oxpecker

示例可以在这里找到 这里

性能测试位于 这里

文档

对 Oxpecker 所有功能的深入功能参考。

目录

• 基本概念
  • 核心概念
  • Oxpecker 管道与 ASP.NET Core 管道的比较
  • 创建新的 EndpointHandler 和 EndpointMiddleware
  • 组合
  • Continue 与 Return
• 基础
  • 将 Oxpecker 插入 ASP.NET Core
  • 依赖关系管理
  • 多个环境和配置
  • 日志记录
  • 错误和 NotFound 处理
• Web 请求处理
  • HTTP 头
  • HTTP 动词
  • HTTP 状态码
  • 路由
    • route
    • routef
    • subRoute
    • addMetadata
    • configureEndpoint
  • 查询字符串
  • 模型绑定
    • 绑定 JSON
    • 绑定表单
    • 绑定查询字符串
  • 文件上传
  • WebSockets
  • 身份验证和授权
  • 条件请求
  • 响应写入
    • 写入字节数
    • 写入文本
    • 写入 JSON
    • 写入 IResult
    • 写入 HTML 字符串
    • 写入 HTML 视图
  • 流式传输
  • 重定向
  • 响应压缩
• 测试

基本概念

核心概念

Oxpecker 是基于 ASP.NET Core 端点路由 构建而成，并为 F# 用户提供了方便的声明式语言。

使用 Oxpecker 时，请确保您熟悉 ASP.NET Core 以及其概念，因为 Oxpecker 会重用很多内置功能。

EndpointHandler

Oxpecker 中的主要构建块是 EndpointHandler

type EndpointHandler = HttpContext -> Task

EndpointHandler是一个函数，它接受HttpContext，并在完成后返回一个Task。

EndpointHandler函数完全控制传入的HttpRequest和生成的HttpResponse。它紧密遵循RequestDelegate签名，但采用F#风格。

EndpointHandler通常应被视为一个终端处理器，这意味着它应该向响应写入一些结果（但不一定，如组合部分所述）。

EndpointMiddleware

type EndpointMiddleware = EndpointHandler -> HttpContext -> Task

EndpointMiddleware与EndpointHandler类似，但接受第一个参数为next EndpointHandler。

每个EndpointMiddleware都可以在通过调用下一个EndpointMiddleware继续向下传递到Oxpecker管道之前处理传入的HttpRequest，或者通过返回自己的Task来提前中断执行。

EndpointHandler 与 EndpointMiddleware 的对比

那么，何时你应该定义一个或另一个呢？答案在于处理器的职责

• 如果你想要有条件地返回响应或进一步在管道中执行，请使用EndpointMiddleware。示例是认证端点中间件和预条件端点中间件。
• 如果你想在下一个处理器完成后执行某些逻辑，请使用EndpointMiddleware
• 其他情况下请使用EndpointHandler

Oxpecker 管道与 ASP.NET Core 管道的比较

Oxpecker 管道是与 ASP.NET Core 管道（面向对象）的（类似）函数等价物。ASP.NET Core 管道由中间件定义，而EndpointMiddleware类似于常规中间件，EndpointHandler类似于终端中间件。

如果 Oxpecker 管道没有处理传入的HttpRequest（因为没有匹配路由），则其他 ASP.NET Core 中间件仍然可以处理请求（例如，静态文件中间件或在 Oxpecker 之后插入的另一个 Web 框架）。

这种架构允许 F# 开发者通过函数组合构建丰富的前端应用程序EndpointMiddleware和EndpointHandler函数，同时通过使用现有的 ASP.NET Core 中间件而从更广泛的 ASP.NET Core 生态系统受益。

Oxpecker 管道通过OxpeckerMiddleware本身集成到更广泛的 ASP.NET Core 管道中，因此是对它的补充而不是替代。

创建新的 EndpointHandler 和 EndpointMiddleware 的方法

有几种方法可以在 Oxpecker 中创建一个新的EndpointHandler。

最简单的方法是重用现有的EndpointHandler函数

let sayHelloWorld : EndpointHandler = text "Hello World, from Oxpecker"

你还可以在返回现有的EndpointHandler函数之前添加附加参数

let sayHelloWorld (name: string) : EndpointHandler =
    let greeting = sprintf "Hello World, from %s" name
    text greeting

如果你需要访问HttpContext对象，你必须显式地返回一个接受HttpContext对象并返回Task的EndpointHandler函数

let sayHelloWorld : EndpointHandler =
    fun (ctx: HttpContext) ->
        let name =
            ctx.TryGetQueryValue "name"
            |> Option.defaultValue "Oxpecker"
        let greeting = sprintf "Hello World, from %s" name
        text greeting ctx

定义新EndpointHandler函数的最啰嗦版本是显式返回一个Task。在EndpointHandler函数内调用异步操作时非常有用。

type Person = { Name : string }

let sayHelloWorld : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            let! person = ctx.BindJson<Person>()
            let greeting = sprintf "Hello World, from %s" person.Name
            return! text greeting ctx
        }

EndpointMiddleware的构建方式与EndpointHandler非常相似，但它接受一个额外的EndpointHandler作为第一个参数

let tryCatchMW : EndpointMiddleware =
    fun (next: EndpointHandler) (ctx: HttpContext) ->
        task {
            try
                return! next ctx
            with
            | ex ->
                ctx.Response.StatusCode <- 500
                return! text (sprintf "An error occurred: %s" ex.Message) ctx
        }

推迟 Task 的执行

请务必注意，在.NET中，一个Task<'T>表示任务最终异步完成时对类型的承诺。除非您以最冗长的方式定义一个EndpointHandler函数（带有task {} CE）并显式使用let!或return!等待嵌套结果，否则处理程序不会在返回到OxpeckerMiddleware之前等待任务完成。

如果您想在任务返回后执行EndpointHandler中的代码，如使用use关键字清理资源，这具有重要的意义。例如，下面代码中的IDisposable将在返回实际响应之前被释放。这是因为EndpointHandler是HttpContext -> Task类型，因此代码text "Hello" ctx只返回了一个尚未完成的Task。

let doSomething : EndpointHandler =
    fun ctx ->
        use __ = somethingToBeDisposedAtTheEndOfTheRequest
        text "Hello" ctx

但是，通过在task {} CE中显式调用text，可以确保在释放IDisposable之前执行text。

let doSomething : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            use __ = somethingToBeDisposedAtTheEndOfTheRequest
            return! text "Hello" ctx
        }

组合

处理程序组合

鱼形操作符(>=>)将两个函数组合成一个。

它可以组合

• EndpointMiddleware和EndpointMiddleware
• EndpointMiddleware和EndpointHandler
• EndpointHandler和EndpointHandler

这是Oxpecker中的一个重要组合器，它允许将许多较小的函数组合成一个大型的Web应用程序

鱼形操作符可以连接的函数数量没有任何限制

let app =
    route "/" (
        setHttpHeader "X-Foo" "Bar"
        >=> setStatusCode 200
        >=> text "Hello World"
    )

每个函数都可以决定：短路管道或继续。对于EndpointMiddleware，它是选择调用next或不调用，对于EndpointHandler，它是开始编写响应或不编写。

如果您想了解更多有关>=>(鱼形)操作符的起源，请参阅Scott Wlaschin的技术博客文章关于铁路导向编程。

routef函数不能直接与鱼形操作符一起使用，因此添加了额外的操作符以使路由可读性更高

routef "/{%s}" (setStatusCode 200 >>=> handler)
routef "/{%s}/{%s}" (setStatusCode 200 >>=>+ handler)
routef "/{%s}/{%s}/{%s}" (setStatusCode 200 >>=>++ handler)

绑定组合

bindQuery、bindForm和bindJson辅助函数可以被处理程序组合

route "/test" (bindQuery handler)

routef在与bind*函数组合时也需要额外的操作符

routef "/{%s}" (bindQuery << handler)
routef "/{%s}/{%s}" (bindForm <<+ handler)
routef "/{%s}/{%s}/{%s}" (bindJson <<++ handler)

多路由处理程序

有时，您希望使用一些通用的处理程序或中间件不仅仅是与一个路由一起使用，而是与整个路由集合一起使用。这可以通过使用applyBefore和applyAfter函数来实现。例如

let MY_HEADER = applyBefore (setHttpHeader "my" "header")

let webApp = [
    MY_HEADER <| subRoute "/auth" [
        route "/open" handler1
        route "/closed" handler2
    ]
]

Continue 与 Return

在Oxpecker中，特定的EndpointMiddleware或EndpointHandler可以使用两种场景

• 与下一个处理程序继续
• 提前返回

继续

例如，一个假设的中间件，它在设置给定的HTTP头之后，总是调用到next http处理器

let setHttpHeader key value : EndpointMiddleware =
    fun (next: HttpFunc) (ctx: HttpContext) ->
        ctx.SetHttpHeader key value
        next ctx

中间件对HttpRequest和/或HttpResponse对象执行某些操作，然后调用next处理器以**继续**执行管道。

它也可以实现为EndpointHandler

let setHttpHeader key value : EndpointHandler =
    fun (ctx: HttpContext) ->
        ctx.SetHttpHeader key value
        Task.CompletedTask

如果这种处理程序在管道**中间**被使用，下一个处理程序将被调用，因为ctx.Response.HasStarted将返回false。如果它在管道**末尾**，则响应将开始，因为没有下一个处理器被调用。

提前返回

有时，EndpointHandler或EndpointMiddleware想要提前返回，而不是继续剩余的管道。

一个典型的例子是一个身份验证或授权处理程序，如果用户未通过身份验证，它不会继续剩余的管道。相反，它可能想要返回一个401 Unauthorized响应

let checkUserIsLoggedIn : EndpointMiddleware =
    fun (next: EndpointHandler) (ctx: HttpContext) ->
        if isNotNull ctx.User && ctx.User.Identity.IsAuthenticated then
            next ctx
        else
            setStatusCode 401 ctx
            Task.CompletedTask

在else子句中，checkUserIsLoggedIn处理程序返回一个401 Unauthorized HTTP响应，并通过不调用next而是一个已经完成的任务来跳过剩余的EndpointHandler管道。

如果您将EndpointMiddleware定义为一个带有task {} CE的示例，则可以按照以下方式重写它

let checkUserIsLoggedIn : EndpointMiddleware =
    fun (next: EndpointHandler) (ctx: HttpContext) ->
        task {
            if isNotNull ctx.User && ctx.User.Identity.IsAuthenticated then
                return! next ctx
            else
                return ctx.SetStatusCode 401
        }

还可以使用EndpointHandler来实现这一点，但是必须显式启动响应

let checkUserIsLoggedIn : EndpointHandler =
    fun (ctx: HttpContext) ->
        if isNotNull ctx.User && ctx.User.Identity.IsAuthenticated then
            Task.CompletedTask
        else
            ctx.SetStatusCode 401
            text "Unauthorized" ctx // start response

基础

将 Oxpecker 插入 ASP.NET Core

安装Oxpecker NuGet包

PM> Install-Package Oxpecker

创建一个网络应用，并将其连接到ASP.NET Core中间件

open Oxpecker

// usually your application consists of several routes
let webApp = [
    route "/"       <| text "Hello world"
    route "/ping"   <| text "pong"
]
// sometimes it can only be a single route
let webApp1 = route "/" <| "Hello Oxpecker"
// or it can only be a single "MultiEndpoint" route
let webApp2 = GET [
    route "/" <| "Hello Oxpecker"
]

let configureApp (appBuilder: IApplicationBuilder) =
    appBuilder
        .UseRouting()
        .UseOxpecker(webApp) // Add Oxpecker to the ASP.NET Core pipeline, should go after UseRouting
        //.UseOxpecker(webApp1) will work
        //.UseOxpecker(webApp2) will also work
    |> ignore

let configureServices (services: IServiceCollection) =
    services
        .AddRouting()
        .AddOxpecker() // Register default Oxpecker dependencies
    |> ignore

[<EntryPoint>]
let main _ =
    let builder = WebApplication.CreateBuilder(args)
    configureServices builder.Services
    let app = builder.Build()
    configureApp app
    app.Run()
    0

依赖关系管理

ASP.NET Core 内置了依赖管理功能，与Oxpecker开箱即用

注册服务

与任何其他ASP.NET Core网络应用一样，注册服务的方式相同

let configureServices (services : IServiceCollection) =
    // Add default Oxpecker dependencies
    services.AddOxpecker() |> ignore

    // Add other dependencies
    // ...

检索服务

您可以通过Oxpecker的EndpointHandler函数中的内置服务定位器（RequestServices）来检索已注册的服务，该服务包含一个HttpContext对象

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let fooBar =
            ctx.RequestServices.GetService(typeof<IFooBar>)
            :?> IFooBar
        // Do something with `fooBar`...
        // Return a Task

Oxpecker还有一个名为GetService<'T>的附加HttpContext扩展方法，可以使代码更简洁

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let fooBar = ctx.GetService<IFooBar>()
        // Do something with `fooBar`...
        // Return a Task

还有一些扩展方法可以用于检索默认依赖项，例如IWebHostEnvironment或ILogger对象，有关这些内容，请参阅本文件的相应部分。

功能化依赖注入

但是，如果您更愿意使用更功能化的依赖注入方法，则不应使用基于容器的策略，而应遵循Env策略。

该方法在文章https://medium.com/@lanayx/dependency-injection-in-f-the-missing-manual-d376e9cafd0f 中进行了描述，并且要了解其实践方式，您可以参考存储库中的CRUD示例。

多个环境和配置

ASP.NET Core内建了对多个环境的处理和配置管理的支持，它们都与Oxpecker配合工作。

此外，Oxpecker提供了一个名为GetHostingEnvironment()的扩展方法，可以用于轻松地从EndpointHandler函数中检索IWebHostEnvironment对象

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let env = ctx.GetHostingEnvironment()
        // Do something with `env`...
        // Return a Task

可以通过GetService<'T>扩展方法检索配置选项

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let settings = ctx.GetService<IOptions<MySettings>>()
        // Do something with `settings`...
        // Return a Task

如果您需要在配置服务时访问配置，可以按照如下方式进行访问

let configureServices (services: IServiceCollection) =
    let serviceProvider = services.BuildServiceProvider()
    let settings = serviceProvider.GetService<IConfiguration>()
    // Configure services using the `settings`...
    services.AddOxpecker() |> ignore

日志记录

ASP.NET Core内建了一个与Oxpecker开箱即用的日志记录API。

在EndpointHandler函数中记录日志

您可以通过GetLogger<'T>或GetLogger (categoryName : string)扩展方法检索一个ILogger对象（可以用于记录日志）。

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        // Retrieve an ILogger through one of the extension methods
        let loggerA = ctx.GetLogger<ModuleName>()
        let loggerB = ctx.GetLogger("someHandler")

        // Log some data
        loggerA.LogCritical("Something critical")
        loggerB.LogInformation("Logging some random info")
        // etc.

        // Return a Task

错误处理

Oxpecker没有内建的错误处理或未找到处理机制，因为它可以很容易地使用以下函数实现，这些函数应该在Oxpecker中间件之前和之后注册

// error handling middleware
let errorHandler (ctx: HttpContext) (next: RequestDelegate) =
    task {
        try
            return! next.Invoke(ctx)
        with
        | :? ModelBindException
        | :? RouteParseException as ex ->
            let logger = ctx.GetLogger()
            logger.LogWarning(ex, "Unhandled 400 error")
            ctx.SetStatusCode StatusCodes.Status400BadRequest
            return! ctx.WriteHtmlView(errorView 400 (string ex))
        | ex ->
            let logger = ctx.GetLogger()
            logger.LogError(ex, "Unhandled 500 error")
            ctx.SetStatusCode StatusCodes.Status500InternalServerError
            return! ctx.WriteHtmlView(errorView 500 (string ex))
    } :> Task

// not found terminal middleware
let notFoundHandler (ctx: HttpContext) =
    let logger = ctx.GetLogger()
    logger.LogWarning("Unhandled 404 error")
    ctx.SetStatusCode 404
    ctx.WriteHtmlView(errorView 404 "Page not found!")

///...

let configureApp (appBuilder: IApplicationBuilder) =
    appBuilder
        .UseRouting()
        .Use(errorHandler) // Add error handling middleware BEFORE Oxpecker
        .UseOxpecker(endpoints)
        .Run(notFoundHandler) // Add not found middleware AFTER Oxpecker

Web 请求处理

Oxpecker附带了一组默认的HttpContext扩展方法和默认的EndpointHandler函数，可用于构建丰富的网络应用。

HTTP 头

在Oxpecker中处理HTTP头很直接。扩展方法TryGetHeaderValue (key: string)尝试检索给定HTTP头的值，然后返回Some string或者None

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let someValue =
            match ctx.TryGetHeaderValue "X-MyOwnHeader" with
            | None -> "default value"
            | Some headerValue -> headerValue

        // Do something with `someValue`...
        // Return a Task

可以通过扩展方法SetHttpHeader (key: string) (value: obj)设置响应中的HTTP头

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        ctx.SetHttpHeader "X-CustomHeader" "some-value"
        // Do other stuff...
        // Return a Task

您还可以通过setHttpHeader HTTP处理程序设置HTTP头

let customHeader : EndpointHandler =
    setHttpHeader "X-CustomHeader" "Some value"

let webApp = [
    route "/foo" (customHeader >=> text "Foo")
]

请注意，这些是Oxpecker的附加功能，它们补充了ASP.NET Core框架中现有的HTTP响应头功能。ASP.NET Core通过ctx.Request.GetTypedHeaders()方法提供了更高级的HTTP响应头功能。

HTTP 动词

Oxpecker公开了一组功能，可以基于请求的HTTP动词过滤请求

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD
• OPTIONS
• TRACE
• CONNECT

还有一个额外的GET_HEAD处理程序，可以同时过滤HTTP的GET和HEAD请求。

根据HTTP动词过滤请求在实现根据动词（例如GET与POST）行为不同的路由时非常有用。

let submitFooHandler : EndpointHandler =
    // Do something

let submitBarHandler : EndpointHandler =
    // Do something

let webApp = [
    // Filters for GET requests
    GET [
        route "/foo" <| text "Foo"
        route "/bar" <| text "Bar"
    ]
    // Filters for POST requests
    POST [
        route "/foo" <| submitFooHandler
        route "/bar" <| submitBarHandler
    ]
]

如果您需要从EndpointHandler函数内部检查请求的HTTP动词，则可以使用默认的ASP.NET Core HttpMethods类。

open Microsoft.AspNetCore.Http

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        if HttpMethods.IsPut ctx.Request.Method then
            // Do something
        else
            // Do something else
        // Return a Task

GET_HEAD是一个特殊函数，可以用来同时启用资源的GET和HEAD请求。在启用缓存且客户端可能想要在发出GET请求之前发送HEAD请求以检查ETag或Last-Modified HTTP响应头时，这非常有用。

您还可以使用applyHttpVerbsToEndpoints函数创建自定义HTTP动词组合。

let GET_HEAD_OPTIONS: Endpoint seq -> Endpoint =
    applyHttpVerbsToEndpoints(Verbs [ HttpVerb.GET; HttpVerb.HEAD; HttpVerb.OPTIONS ])

let webApp = [
    GET_HEAD_OPTIONS [
        route "/foo" <| text "Foo"
        route "/bar" <| text "Bar"
    ]
]

HTTP 状态码

设置响应的HTTP状态码可以通过SetStatusCode (httpStatusCode: int)扩展方法或使用setStatusCode (statusCode: int)函数完成。

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        ctx.SetStatusCode 200
        // Return a Task

// or...

let someHandler : EndpointHandler =
    setStatusCode 200
    >=> text "Hello World"

路由

Oxpecker提供了一些路由功能来满足大多数使用场景。请注意，Oxpecker路由建立在ASP.NET Core端点路由之上，因此所有路由都不区分大小写。

route

可以通过route HTTP处理程序以最简单的方式执行路由。

let webApp = [
    route "/foo" <| text "Foo"
    route "/bar" <| text "Bar"
]

routef

如果路由包含用户定义的参数，则可以使用routef HTTP处理程序。

let fooHandler first last age : EndpointHandler =
    fun (ctx: HttpContext) ->
        (sprintf "First: %s, Last: %s, Age: %i" first last age
        |> text) ctx

let webApp = [
    routef "/foo/{%s}/{%s}/{%i}" fooHandler
    routef "/bar/{%O:guid}" (fun (guid: Guid) -> text (string guid))
]

routef HTTP处理程序接受两个参数 - 一个格式字符串和一个EndpointHandler函数。

格式字符串支持以下格式字符

注意：routef处理程序只能处理最多5个路由参数。不建议在路由中使用超过3个参数，但如果确实需要很多，可以使用带有利用.TryGetRouteValue扩展方法的EndpointHandler函数的route。

route "/{a}/{b}/{c}/{d}/{e}/{f}" (fun ctx ->
    let a = ctx.TryGetRouteValue("a") |> Option.defaultValue ""
    let b = ctx.TryGetRouteValue("b") |> Option.defaultValue ""
    let c = ctx.TryGetRouteValue("c") |> Option.defaultValue ""
    let d = ctx.TryGetRouteValue("d") |> Option.defaultValue ""
    let e = ctx.TryGetRouteValue("e") |> Option.defaultValue ""
    let f = ctx.TryGetRouteValue("f") |> Option.defaultValue ""
    text (sprintf "%s %s %s %s %s %s", a b c d e f) ctx
)

subRoute

它允许您在不重复已预先过滤的路由部分的情况下对路由进行分类。

let webApp =
    subRoute "/api" [
        subRoute "/v1" [
            route "/foo" <| text "Foo 1"
            route "/bar" <| text "Bar 1"
        ]
        subRoute "/v2" [
            route "/foo" <| text "Foo 2"
            route "/bar" <| text "Bar 2"
        ]
    ]

在此示例中，检索“Bar 2”的最终URL为http[s]://your-domain.com/api/v2/bar。

addMetadata

它允许您向路由添加元数据，这些元数据可以在管道的后续部分中使用。

let webApp =
    GET [
        route "/foo" (text "Foo") |> addMetadata "foo"
    ]

configureEndpoint

此函数允许您使用ASP.NET .With*扩展方法配置端点。

let webApp =
    GET [
        route "/foo" (text "Foo")
          |> configureEndpoint
             _.WithMetadata("foo")
              .WithDisplayName("Foo")
    ]

查询字符串

在Oxpecker中与查询字符串的工作方式类似于处理HTTP响应头。扩展方法TryGetQueryValue (key : string)尝试检索给定查询字符串参数的值，然后返回Some string或None。

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        let someValue =
            match ctx.TryGetQueryValue "q" with
            | None   -> "default value"
            | Some q -> q

        // Do something with `someValue`...
        // Return a Task

您还可以通过ctx.Request.Query对象访问查询字符串，该对象返回一个IQueryCollection对象，允许您对其进行更多操作。

最后但同样重要的是，还有一个名为BindQuery<'T>的HttpContext扩展方法，它允许您将整个查询字符串绑定到类型为'T的对象（请参阅绑定查询字符串）。

模型绑定

Oxpecker默认提供了一些HttpContext扩展方法和等价的EndpointHandler函数，这使得可以将HTTP请求的有效负载或查询字符串绑定到自定义对象。

绑定 JSON

可以使用BindJson[T]()扩展方法将JSON有效负载绑定到类型的对象。

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let submitCar : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Binds a JSON payload to a Car object
            let! car = ctx.BindJson<Car>()

            // Sends the object back to the client
            return! ctx.Write <| TypedResults.Ok car
        }

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
    ]
    POST [
        route "/car" submitCar
    ]
]

或者，您也可以使用bindJson http处理程序。

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
    ]
    POST [
        route "/car" (bindJson<Car> (fun car -> %TypedResults.Ok car))
    ]
]

这两种方式，无论是HttpContext扩展方法还是EndpointHandler函数，都会尝试创建类型的实例，不管提交的有效负载是否包含了对的完整表示。解析后的对象可能只包含部分数据（一些属性可能是null），在进一步处理之前可能需要额外的null检查。

请注意，为了让模型绑定工作，记录类型必须用[<CLIMutable>]属性装饰，以确保类型具有无参构造函数。

底层的JSON序列化器可以在应用程序启动时作为依赖项进行配置（参见JSON）。

绑定表单

扩展方法BindForm[T] (?cultureInfo : CultureInfo)可以将表单数据绑定到类型的对象。您还可以指定一个可选的CultureInfo对象，用于解析如DateTime对象或浮点数等特定于文化的数据。

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let submitCar : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Binds a form payload to a Car object
            let! car = ctx.BindForm<Car>()

            // or with a CultureInfo:
            let british = CultureInfo.CreateSpecificCulture("en-GB")
            let! car2 = ctx.BindForm<Car>(british)

            // Sends the object back to the client
            return! ctx.Write <| Ok car
        }

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
    ]
    POST [ route "/car" submitCar ]
]

或使用bindForm和bindFormC（额外的文化参数）http处理程序。

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let british = CultureInfo.CreateSpecificCulture("en-GB")

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
    ]
    POST [
        route "/car" (bindForm<Car> (fun model -> %Ok model))
        route "/britishCar" (bindFormC<Car> british (fun model -> %Ok model))
    ]
]

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let submitCar : EndpointHandler =
    fun (ctx: HttpContext) ->
        // Binds the query string to a Car object
        let car = ctx.BindQuery<Car>()

        // or with a CultureInfo:
        let british = CultureInfo.CreateSpecificCulture("en-GB")
        let car2 = ctx.BindQuery<Car>(british)

        // Sends the object back to the client
        ctx.Write <| Ok car

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
        route "/car" <| submitCar
    ]
]

[<CLIMutable>]
type Car = {
    Name   : string
    Make   : string
    Wheels : int
    Built  : DateTime
}

let british = CultureInfo.CreateSpecificCulture("en-GB")

let webApp = [
    GET [
        route "/"    <| text "index"
        route "ping" <| text "pong"
    ]
    POST [
        route "/car" (bindQuery<Car> (fun model -> %Ok model))
        route "/britishCar" (bindQueryC<Car> british (fun model -> %Ok model))
    ]
]

let fileUploadHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        match ctx.Request.HasFormContentType with
        | false ->
            ctx.Write <| BadRequest()
        | true  ->
            ctx.Request.Form.Files
            |> Seq.fold (fun acc file -> $"{acc}\n{file.FileName}") ""
            |> ctx.WriteText

let webApp = [ route "/upload" fileUploadHandler ]

let fileUploadHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            let formFeature = ctx.Features.Get<IFormFeature>()
            let! form = formFeature.ReadFormAsync CancellationToken.None
            return!
                form.Files
                |> Seq.fold (fun acc file -> $"{acc}\n{file.FileName}") ""
                |> ctx.WriteText
        }

let webApp = [ route "/upload" fileUploadHandler ]

let configureApp (appBuilder: IApplicationBuilder) =
    appBuilder
        .UseRouting()
        .UseOxpecker(webApp) // Add Oxpecker
        .UseWebSockets() // Add WebSockets
    |> ignore

let webApp = [
    // single endpoint
    route "/" (text "Hello World")
        |> configureEndpoint
            _.DisableAntiforgery()
             .RequireAuthorization()
    // endpoint group
    GET [
        route "/index" <| text "index"
        route "/ping"  <| text "pong"
    ] |> configureEndpoint _.RequireAuthorization(
            AuthorizeAttribute(AuthenticationSchemes = "MyScheme")
        )
]

let someHandler (eTag         : string)
                (lastModified : DateTimeOffset)
                (content      : string) =
    let eTagHeader = Some (EntityTagHelper.createETag eTag)
    validatePreconditions eTagHeader (Some lastModified) >=> text content

// Pass an optional eTag and lastModified timestamp into the handler, because generating an eTag might require to load the entire resource into memory and therefore this is not something which should be done on every request.
let someHttpHandler eTag lastModified : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            match ctx.ValidatePreconditions(eTag, lastModified) with
            | ConditionFailed     -> return ctx.PreconditionFailedResponse()
            | ResourceNotModified -> return ctx.NotModifiedResponse()
            | AllConditionsMet | NoConditionsSpecified ->
                // Continue as normal
                // Do stuff
        }

let webApp = [
    route "/"    <| text "Hello World"
    route "/foo" <| someHttpHandler None None
]

let someHandler (data: byte[]) : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteBytes data
        }

// or...

let someHandler (data: byte[]) : EndpointHandler =
    // Do stuff
    bytes data

let yaml (x: obj) : EndpointHandler =
    setHttpHeader "Content-Type" "text/yaml"
    >=> bytes (x |> YamlSerializer.toYaml |> Encoding.UTF8.GetBytes)

let someHandler (str: string) : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteText str
        }

// or...

let someHandler (str: string) : EndpointHandler =
    // Do stuff
    text str

let someHandler (animal: Animal) : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteJson animal
        }

// or...

let someHandler (animal: Animal) : EndpointHandler =
    // Do stuff
    json animal

let someHandler (person: Person) : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteJsonChunked person
        }

// or...

let someHandler (person: Person) : EndpointHandler =
    // Do stuff
    jsonChunked person

let configureServices (services : IServiceCollection) =
    // First register all default Oxpecker dependencies
    services.AddOxpecker() |> ignore
    // Now register custom serializer
    services.AddSingleton<Serializers.IJsonSerializer>(CustomSerializer()) |> ignore
    // or use default STJ serializer, but with different options
    services.AddSingleton<Serializers.IJsonSerializer>(
            SystemTextJson.Serializer(specificOptions)) |> ignore

open Oxpecker
open type Microsoft.AspNetCore.Http.TypedResults

let johnDoe = {|
    FirstName = "John"
    LastName  = "Doe"
|}

let app = [
    route "/"     <| text "Hello World"
    route "/john" <| %Ok johnDoe // returns 200 OK with JSON body
    route "/bad"  <| %BadRequest() // returns 400 BadRequest with empty body
]

let myHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        ctx.Write <| TypedResults.Ok johnDoe

let someHandler (dataObj: obj) : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteHtmlString "<html><head></head><body>Hello World</body></html>"
        }

// or...

let someHandler (dataObj: obj) : EndpointHandler =
    // Do stuff
    htmlString "<html><head></head><body>Hello World</body></html>"

let indexView =
    html() {
        head() {
            title() { "Oxpecker" }
        }
        body() {
            h1(id="Header") { "Oxpecker" }
            p() { "Hello World." }
        }
    }

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteHtmlView indexView
        }

// or...

let someHandler : EndpointHandler =
    // Do stuff
    htmlView indexView

let indexView =
    html() {
        head() {
            title() { "Oxpecker" }
        }
        body() {
            h1(id="Header") { "Oxpecker" }
            p() { "Hello World." }
        }
    }

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteHtmlViewChunked indexView
        }

// or...

let someHandler : EndpointHandler =
    // Do stuff
    htmlViewChunked indexView

[<Extension>]
static member WriteMyHtmlView(ctx: HttpContext, htmlView: MyHtmlElement) =
    let bytes = htmlView |> convertToBytes
    ctx.Response.ContentType <- "text/html; charset=utf-8"
    ctx.WriteBytes bytes

// ...

let myHtmlView (htmlView: MyHtmlElement) : EndpointHandler =
    fun (ctx: HttpContext) -> ctx.WriteMyHtmlView htmlView

let someStream : Stream = ...

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteStream(
                true, // enableRangeProcessing
                someStream,
                None, // eTag
                None) // lastModified
        }

// or...

let someHandler : EndpointHandler =
    // Do stuff
    streamData
        true // enableRangeProcessing
        someStream
        None // eTag
        None // lastModified

let someHandler : EndpointHandler =
    fun (ctx: HttpContext) ->
        task {
            // Do stuff
            return! ctx.WriteFileStream(
                true, // enableRangeProcessing
                "large-file.zip",
                None, // eTag
                None) // lastModified
        }

// or...

let someHandler : EndpointHandler =
    // Do stuff
    streamFile
        true // enableRangeProcessing
        "large-file.zip"
        None // eTag
        None // lastModified

let webApp = [
    route "/new" <| text "Hello World"
    route "/old" <| redirectTo "https://myserver.com/new" true
]

let configureServices (services : IServiceCollection) =
    services
        .AddResponseCaching() // <-- Here the order doesn't matter
        .AddOxpecker()         // This is just registering dependencies
    |> ignore

let configureApp (app : IApplicationBuilder) =
    app
       .UseStaticFiles()     // Optional if you use static files
       .UseAuthentication()  // Optional if you use authentication
       .UseResponseCaching() // <-- Before UseOxpecker webApp
       .UseOxpecker webApp

// A test handler which generates a new GUID on every request
let generateGuidHandler : EndpointHandler =
    fun ctx -> ctx.WriteText(Guid.NewGuid().ToString())

let cacheHeader = Some <| CacheControlHeaderValue(MaxAge = TimeSpan.FromSeconds(30), Public = true)

let webApp = [
    route "/route1" (responseCaching cacheHeader None None >=> generateGuidHandler)
    route "/route2" (noResponseCaching >=> generateGuidHandler)
]

Cache-Control: no-store, no-cache
Pragma: no-cache
Expires: -1

let cacheHeader = Some <| CacheControlHeaderValue(MaxAge = TimeSpan.FromSeconds(30), Public = true)

// Cache for 30 seconds without any vary headers
publicResponseCaching cacheHeader None None

// Cache for 30 seconds with Accept and Accept-Encoding as vary headers
publicResponseCaching cacheHeader (Some "Accept, Accept-Encoding") None

responseCaching
    (Some (CacheControlHeaderValue(MaxAge = TimeSpan.FromSeconds(30)))
    (Some "Accept, Accept-Encoding")
    (Some [| "query1"; "query2" |])