# 文档概览 Source: https://docs.sisk-framework.org/zh-cn/docs/index.html ## 欢迎 - [入门](https://docs.sisk-framework.org/zh-cn/docs/getting-started.md): 欢迎阅读 Sisk 文档！ Sisk 是一个开源的轻量级 .NET HTTP 框架。您可以使用它构建独立的 Web 服务，将 HTTP 模块嵌入现有应用程序，或在反向代理后运行服务，仅使用所需的配置。 Sisk 的价值观包括代码透明性、模块化、性能和可扩展性。它能够处理不同的应用模式，包括 RESTful … - [安装](https://docs.sisk-framework.org/zh-cn/docs/installing.md): 您可以通过 NuGet、dotnet CLI 或 其他选项 安装 Sisk。只需在开发者控制台中运行以下命令，即可轻松设置 Sisk 环境： Shell dotnet add package Sisk.HttpServer 此命令将在您的项目中安装最新版本的 Sisk。 Sisk 1.7 支持 .NET 8、.NET … - [本机 AOT 支持](https://docs.sisk-framework.org/zh-cn/docs/native-aot.md): .NET Native AOT 允许发布本机 .NET 应用程序，这些应用程序是自给自足的，不需要在目标主机上安装 .NET 运行时。此外，Native AOT 提供诸如： 应用程序大小大大减小 初始化速度大大提高 内存消耗降低 Sisk Framework 本质上允许几乎所有功能使用 Native AOT，而无需对源 … - [部署您的 Sisk 应用程序](https://docs.sisk-framework.org/zh-cn/docs/deploying.md): 部署 Sisk 应用程序的过程包括将项目发布到生产环境。虽然该过程相对简单，但值得注意的细节可能对部署基础设施的安全性和稳定性产生致命影响。 理想情况下，在完成所有可能的测试并使应用程序准备就绪后，您应该准备好将其部署到云端。 发布您的应用 # 发布 Sisk 应用程序或服务即生成适用于生产环境的二进制文件并进行优化。 … - [使用 SSL](https://docs.sisk-framework.org/zh-cn/docs/ssl.md): 在开发中使用 SSL 可能是必要的，尤其是在需要安全性的环境下，例如大多数 Web 开发场景。Sisk 基于 HttpListener 实现，而 HttpListener 本身不支持原生 HTTPS，只支持 HTTP。不过，仍有一些变通办法可以让你在 Sisk 中使用 SSL。下面介绍几种方式： 通过 … - [Cadente](https://docs.sisk-framework.org/zh-cn/docs/cadente.md): Cadente 是为 Sisk 提供的实验性托管 HTTP/1.1 监听器实现。它作为默认的 System.Net.HttpListener 的替代品，提供更大的控制力和灵活性，尤其在非 Windows 平台上。 概述 # 默认情况下，Sisk 使用 HttpListener（来自 System.Net）作为底层 … - [在 Windows 上配置命名空间保留](https://docs.sisk-framework.org/zh-cn/docs/registering-namespace.md): 注意 此配置是可选的，仅在您希望 Sisk 在 Windows 上使用 HttpListener 引擎监听除 “localhost” 之外的主机时才需要。 Sisk 使用 HttpListener 网络接口，该接口将虚拟主机绑定到系统以监听请求。 在 Windows 上，此绑定有些限制，只允许将 localhost 绑 … - [更新日志](https://docs.sisk-framework.org/zh-cn/docs/changelogs.md): 每一次对 Sisk 的更改都记录在更新日志中。您可以在此处查看所有 Sisk 版本的更新日志。 从 1.6 迁移到 1.7 # Sisk 1.7.0 包含 Sisk.HttpServer、Sisk.Cadente、Sisk.Cadente.CoreEngine 和 Sisk.IniConfiguration … - [常见问题](https://docs.sisk-framework.org/zh-cn/docs/faq.md): 关于 Sisk 的常见问题。 Sisk 是开源的吗？ # 完全开源。Sisk 使用的所有源代码都已发布并经常在 GitHub 上更新。 是否接受贡献？ # 只要贡献符合 Sisk 哲学，所有贡献都非常欢迎！贡献不仅限于代码！您可以通过文档、测试、翻译、捐款和帖子等方式贡献。 Sisk 是否有资金支持？ # 不。目前没有 … ## 基础 - [路由](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/routing.md): The Router 是构建服务器的第一步。它负责容纳 Route 对象，这些对象是将 URL 及其方法映射到服务器执行的操作的端点。每个操作负责接收请求并向客户端返回响应。 路由是路径表达式（“路径模式”）与其可监听的 HTTP 方法的配对。当向服务器发出请求时，服务器会尝试找到匹配该请求的路由，然后调用该路由的操作 … - [请求处理](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/request-handlers.md): 请求处理程序，也称为“中间件”，是会在路由器执行请求之前或之后运行的函数。它们可以在每个路由或每个路由器上定义。 请求处理程序有两种类型： BeforeResponse：表示请求处理程序将在调用路由器操作之前执行。 AfterResponse：表示请求处理程序将在调用路由器操作之后执行。在此上下文中发送 HTTP 响应 … - [请求](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/requests.md): 请求是表示 HTTP 请求消息的结构体。HttpRequest 对象包含在整个应用程序中处理 HTTP 消息的实用函数。 HTTP 请求由方法、路径、版本、头部和正文组成。 在本文档中，我们将教您如何获取这些元素。 获取请求方法 # 要获取收到的请求的方法，可以使用 Method 属性： C# static … - [响应](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/responses.md): 响应表示对 HTTP 请求的 HTTP 响应对象。它们由服务器发送给客户端，以指示对资源、页面、文档、文件或其他对象的请求。 HTTP 响应由状态、头部和内容组成。 在本文档中，我们将教您如何使用 Sisk 构建 HTTP 响应。 设置 HTTP 状态 # 自 HTTP/1.0 起，HTTP 状态列表保持不变，Sisk … ## 功能 - [日志记录](https://docs.sisk-framework.org/zh-cn/docs/features/logging.md): 您可以配置 Sisk 自动写入访问日志和错误日志。可以定义日志轮转、扩展名和轮转频率。 The LogStream 类提供了一种异步写入日志并将其保存在可等待写入队列中的方式。LogStream 类实现了 IAsyncDisposable，确保在流关闭前写入所有未完成的日志。 本文将向您展示如何为应用程序配置日志记录。 … - [Server Sent Events](https://docs.sisk-framework.org/zh-cn/docs/features/server-sent-events.md): Sisk 开箱即支持通过 Server Sent Events 发送消息。您可以创建一次性和持久的连接，在运行时获取这些连接并使用它们。 此功能受到浏览器的某些限制，例如只能发送文本消息且无法永久关闭连接。服务器端关闭的连接会导致客户端每隔 5 秒（某些浏览器为 3 秒）尝试重新连接。 这些连接对于在服务器向客户端发送 … - [Web 套接字](https://docs.sisk-framework.org/zh-cn/docs/features/websockets.md): Sisk 也支持 Web 套接字，例如接收和发送消息给客户端。 此功能在大多数浏览器中运行良好，但在 Sisk 中仍属实验性。若发现任何错误，请在 GitHub 上报告。 接收消息 # WebSocket 消息按顺序接收，排队等待 ReceiveMessageAsync 处理。超时、操作被取消或客户端断开时，此方法不返 … - [Discard 语法](https://docs.sisk-framework.org/zh-cn/docs/features/discard-syntax.md): HTTP 服务器可以用于监听来自操作的回调请求，例如 OAuth 身份验证，并在接收到该请求后丢弃。这在需要后台操作但不想为其设置整个 HTTP 应用程序的情况下很有用。 以下示例展示了如何使用 CreateListener 创建一个在端口 5555 上监听的 HTTP 服务器并等待下一个上下文： C# using … - [依赖注入](https://docs.sisk-framework.org/zh-cn/docs/features/instancing.md): 通常，会为请求的生命周期专门分配成员和实例，例如数据库连接、已验证的用户或会话令牌。实现这一点的一种可能方式是通过 HttpContext.RequestBag ，它创建一个在整个请求生命周期中都存在的字典。 该字典可以被 请求处理程序 访问，并在整个请求中定义变量。例如，一个验证用户的请求处理程序将用户设置在 … - [流式内容](https://docs.sisk-framework.org/zh-cn/docs/features/content-streaming.md): Sisk 支持读取和发送流式内容到和从客户端。这一功能对于在请求的生命周期中序列化和反序列化内容的内存开销非常有用。 请求内容流 # 小内容会自动加载到 HTTP 连接缓冲区内存中，快速加载到 HttpRequest.Body 和 HttpRequest.RawBody。对于较大的内容，可以使用 … - [在 Sisk 中启用 CORS（跨域资源共享）](https://docs.sisk-framework.org/zh-cn/docs/features/cors.md): Sisk 提供了一个工具，可在公开服务时处理跨域资源共享 (CORS)。该功能并非 HTTP 协议的一部分，而是由 W3C 定义的浏览器特性。此安全机制阻止网页向提供该网页的域之外的域发起请求。服务提供者可以允许特定域或单个域访问其资源。 Same Origin # 要将资源标识为“同源”，请求必须在其请求中包含 … - [文件服务器](https://docs.sisk-framework.org/zh-cn/docs/features/file-server.md): Sisk 提供 Sisk.Http.FileSystem 命名空间，其中包含用于提供静态文件、目录列出和文件转换的工具。此功能允许您从本地目录提供文件，支持范围请求（音频/视频流）和自定义文件处理。 提供静态文件 # 提供静态文件的最简单方法是 Router.MapFileSystem。此方法将 URL 前缀映射到磁盘 … ## 扩展 - [模型上下文协议](https://docs.sisk-framework.org/zh-cn/docs/extensions/mcp.md): 可以使用 Sisk.ModelContextProtocol 包构建为使用大型语言模型（LLM）的代理模型提供上下文的应用程序： dotnet add package Sisk.ModelContextProtocol --prerelease 此包提供有用的类和方法，用于构建在 Streamable HTTP 上运行 … - [JSON-RPC 扩展](https://docs.sisk-framework.org/zh-cn/docs/extensions/json-rpc.md): Sisk 提供了一个实验性的 JSON-RPC 2.0 API 模块，帮助你创建更简洁的应用程序。此扩展严格实现 JSON-RPC 2.0 传输接口，并提供通过 HTTP GET、POST 请求以及 Sisk 的 WebSocket 进行传输。 你可以使用下面的命令通过 Nuget 安装此扩展。请注意，在实验/测试版中 … - [服务提供者](https://docs.sisk-framework.org/zh-cn/docs/extensions/service-providers.md): Service Providers 是一种将你的 Sisk 应用程序迁移到不同环境的方式，使用可移植的配置文件。此功能允许你在不修改每个环境的应用代码的情况下，更改服务器端口、参数以及其他选项。该模块依赖于 Sisk 的构建语法，可通过 UsePortableConfiguration 方法进行配置。 配置提供程序通过 … - [INI 配置提供程序](https://docs.sisk-framework.org/zh-cn/docs/extensions/ini-configuration.md): Sisk 提供了一种获取除 JSON 之外的启动配置的方法。实际上，任何实现了 IConfigurationReader 的管道都可以与 PortableConfigurationBuilder.WithConfigurationPipeline 一起使用，从任意文件类型读取服务器配置。 … - [API 文档](https://docs.sisk-framework.org/zh-cn/docs/extensions/api-documentation.md): Sisk.Documenting 扩展允许您自动为 Sisk 应用程序生成 API 文档。它利用您的代码结构和特性创建一个完整的文档站点，支持导出为 Open API（Swagger）格式。 警告 This package is published as a prerelease (1.7.0-rc3). Its … - [基本认证（已停用）](https://docs.sisk-framework.org/zh-cn/docs/extensions/basic-auth.md): 小心 已停用，请勿使用。 Sisk.BasicAuth 包不再维护，并已在 NuGet 上标记为已弃用，且没有替代包。其 BasicAuthenticateRequestHandler 不会解码标准 HTTP 客户端发送的 Base64 凭证，导致已认证的请求被拒绝。请使用您自己的请求处理程序实现 Basic 认证，读 … - [SSL 代理（已停用）](https://docs.sisk-framework.org/zh-cn/docs/extensions/ssl-proxy.md): 小心 已停用，请勿使用。 Sisk.SslProxy 包不再维护，在 NuGet 上已被标记为已弃用，且没有替代包。它已无法针对当前的 Cadente API 编译。若要提供 HTTPS，请使用 Cadente engine 的原生 SSL 支持或在 Working with SSL 中的选项之一。此页面仅作历史参考保 … ## 高级 - [手动（高级）设置](https://docs.sisk-framework.org/zh-cn/docs/advanced/manual-setup.md): 当需要自行组装服务器各部件时（例如一个进程必须暴露多个主机、端口、路由器或自定义服务器配置），请使用手动设置。对于大多数应用，构建器 API 更简洁且应当优先使用。手动设置在需要直接控制四个核心部件时非常有用：Router、一个或多个 ListeningHost 对象、HttpServerConfiguration，以 … - [请求生命周期](https://docs.sisk-framework.org/zh-cn/docs/advanced/request-lifecycle.md): 下面解释了请求的整个生命周期，以一个 HTTP 请求的示例为例。 Receiving the request: 每个请求都会在请求本身和将要发送给客户端的响应之间创建一个 HTTP 上下文。该上下文来自 Sisk 内置的监听器，可以是 HttpListener、Kestrel 或 Cadente。 External … - [转发解析器](https://docs.sisk-framework.org/zh-cn/docs/advanced/forwarding-resolvers.md): Forwarding Resolver 是一个帮助解码通过请求、代理、CDN 或负载均衡器识别客户端信息的工具。当您的 Sisk 服务通过反向或正向代理运行时，客户端的 IP 地址、主机和协议可能与原始请求不同，因为这是从一个服务转发到另一个服务。此 Sisk 功能允许您在处理请求之前控制并解析这些信息。这些代理通常会 … - [Http 服务器处理程序](https://docs.sisk-framework.org/zh-cn/docs/advanced/http-server-handlers.md): 在 Sisk 0.16 版本中，我们引入了 HttpServerHandler 类，旨在扩展 Sisk 的整体行为并为 Sisk 提供额外的事件处理程序，例如处理 Http 请求、路由器、上下文包等。 该类集中处理整个 HTTP 服务器以及单个请求生命周期中发生的事件。Http 协议本身没有会话概念，因此无法在请求之间 … - [每个服务器的多个监听主机](https://docs.sisk-framework.org/zh-cn/docs/advanced/multi-host-setup.md): Sisk Framework 一直支持在每个服务器上使用多个主机，也就是说，一个 HTTP 服务器可以监听多个端口，每个端口都有自己的路由器和在其上运行的服务。 这样，就可以轻松地在单个 HTTP 服务器上使用 Sisk 分离职责并管理服务。下面的示例展示了创建两个 ListeningHost，每个监听不同的端口，使用 … - [HTTP 服务器引擎](https://docs.sisk-framework.org/zh-cn/docs/advanced/server-engines.md): Sisk Framework 被分成几个包，其中主包（Sisk.HttpServer）不包含一个基本的 HTTP 服务器 - 默认情况下，HttpListener 被用作 Sisk 的主要引擎来执行服务器的低级别角色。 HTTP 引擎实现了 Sisk 提供的应用层以下的层次。这个层次负责连接管理、消息的序列化和反序列化 …