抠丁客 抠丁客
项目
编辑 (2024/6/29)

AngleSharp 升级指南

从 0.17 到 1.0

从 API 角度来看，这两个版本是兼容的，但是 ABI 不兼容，因为一些构造函数发生了变化（比如添加了新的可选参数等）。因此，在动态使用 1.0 之前需要重新编译。

从 0.16 到 0.17

对.NET Framework 4.6 的支持已被移除。AngleSharp 现在仅支持.NET 4.6.1 或更高版本/.NET Standard 2.0。如果你使用的是较旧的框架，你可能需要分叉 AngleSharp 或者继续使用 AngleSharp 的旧版本。

从 0.15 到 0.16

Url 类已从 AngleSharp 移动到了 AngleSharp.Dom 中。你可能需要调整你的 using 语句或使用完全限定名。

从 0.14 到 0.15

不再支持.NET Standard 1.3。AngleSharp 现在仅支持.NET 4.5 或更高版本/.NET Standard 2.0。如果你使用的是较旧的框架，你可能需要分叉 AngleSharp 或者继续使用 AngleSharp 的旧版本。

从 0.13 到 0.14

如果你实现了 IBrowsingContext ，那么你也需要实现 IDisposable 。大多数用户应该不会受到此影响。

从 0.12 到 0.13

将配置方法 WithCookies 重命名为 WithDefaultCookies 。我们建议使用 AngleSharp.Io 中的 WithCookies 。

移除了 TaskEventLoop 。通常，由于这是一个低级结构，它不应该对你的代码有任何影响。

从 0.11 到 0.12

对于这个变更，除非你做了 IElement 的自定义实现（不太可能），否则我们预计不需要进行任何迁移工作。

从 0.10 到 0.11

此版本遵循 0.10 的精神，并为今年晚些时候的 1.0 版本做准备。主要是增加了功能，但也有一项重要的破坏性更改：我们移除了所有与 AngleSharp.Xml 相关的内容。这现在是名为 AngleSharp.Xml 的单独库的一部分。

SVG

ISvgDocument 接口及其实现 SvgDocument 已被移除。它们现在可以通过 AngleSharp.Xml 库获得。在大多数情况下，应该没有必要直接访问这些类型—— IDocument 通常已经足够。

XML

整个 AngleSharp.Xml 命名空间已移到一个同名的独立库中。

XHTML

与 XML 一样，XHTML 也大多被移除了。但这不是一个大的变化。它只影响了 AutoSelectedMarkupFormatter，现在它是 AngleSharp.Xml 库的一部分。此外，它从 AngleSharp.Xhtml 命名空间移到了 AngleSharp.Xml 命名空间。

依赖关系

对于.NET Framework 版本的 System.Encoding.CodePages 包的同伴依赖关系已经不存在了。现在这也是.NET Framework 目标的一个依赖项。

从 0.9.x 到 0.10（或更高）

AngleSharp 的 v0.10 发布线打破了之前使用的 API。尽管仍然应用了相同的概念，但许多事情发生了变化，从 AngleSharp 预 v0.10 升级到 0.10 肯定会引发问题。以下几点应该帮助你尽可能快地完成迁移。

在以下点中，v0.10 发布线将被称为“当前”，而旧版本将被称作“先前”。

Silverlight / 非.NET 4.5

:warn: 这些平台不再受支持。目前没有解决方案计划。

建议：暂时停留在 AngleSharp pre-v0.10 版本。不便之处，敬请谅解！

配置

配置 AngleSharp 的方式已改变。之前，提供的配置被简单地引用，例如，由 BrowsingContext 引用。现在，在创建浏览上下文时，它会做一些评估并创建自己的配置副本。因此，配置也可以被视为将要成为浏览上下文考虑的选项的（重新）可用草稿。

用于处理 IConfiguration 类型对象的扩展方法已经改变。除了标准的 With 之外，我们现在还有：

  • WithOnly，它将移除同一类型的早期出现，
  • Without，它将删除给定类型的任何现有出现。

此外，除了使用普通对象和特定服务类型的重载外，我们还有一个创建者重载。该重载包含一个函数 Func<IBrowsingContext, T>（其中 T 是服务的类型），当配置被浏览上下文使用时使用。

默认配置扩展器保持不变（如 WithDefaultLoader ），但是它们的参数可能已经改变。对于 WithDefaultLoader ，你需要提供一个对象而不是使用回调。通常，相比于

config.WithDefaultLoader(setup => setup.IsResourceLoadingEnabled = true)

你现在必须写

config.WithDefaultLoader(new LoaderOptions { IsResourceLoadingEnabled = true })

HTML

统一的解析器接口已更改。不再可能调用 Parse，而是现在使用 ParseDocument 。因此，一些旧代码像

IDocument htmlDocument = parser.Parse("");

现在是

IDocument htmlDocument = parser.ParseDocument("");

注意：异步解析（仍然推荐）也是如此。这里我们现在有了 ParseDocumentAsync 。

此外，HtmlParser 在构造函数中不再接受 IConfiguration。在这种情况下，我们隐式创建了一个 BrowsingContext，我们想避免向用户显示实际发生的事情。相反，现在应该传递一个浏览上下文。

以下旧代码

var parser = new HtmlParser(Configuration.Default);

因此应替换为

IBrowsingContext context = BrowsingContext.New(Configuration.Default);
var parser = new HtmlParser(context);

但最好表达为

IBrowsingContext context = BrowsingContext.New(Configuration.Default);
var parser = context.GetService<IHtmlParser>();

CSS

当前版本的 AngleSharp 将 CSS 解析（除了 CSS 选择器）分离到了自己的库中。这个库叫做 AngleSharp.Css ，可通过 NuGet 获取。

新库比旧集成的功能更丰富。除了改进的对象模型（CSSOM 及更多）之外，我们还包含了对许多事物的支持，例如，CSS 自定义属性（也称为 CSS 变量）、flexbox 和 grid。所使用的值转换的正确性测试也得到了扩展。

基本使用方法是在配置 AngleSharp 时使用 WithCss 。然后，例如，可以通过使用 AngleSharp.Css.Dom 中的 GetStyle 来访问样式。设置样式现在使用 SetStyle 扩展方法。这取代了旧的 Style 属性。

ICssStyleDeclaration 不再包含所有已知声明作为属性。相反，使用扩展方法动态附加这些 getter 和 setter，例如，GetDisplay() 和 SetDisplay(value) 而不是 Display { get; set; }。

因此，以下旧代码不再工作：

((IHtmlElement)element).Style.Display = "flex";

相反，我们现在需要使用 AngleSharp.Css NuGet 包，应该像这样在配置中使用 Configuration.Default.WithCss() 。如果这一切都满足了，以下扩展方法将工作：

((IHtmlElement)element).Style.SetDisplay("flex");

在之前的版本中，IWindow 也包含了用于样式计算的 CSS 方法。这些现在也在新的 CSS 库中作为扩展方法可用。WindowExtensions 包含在 AngleSharp.Dom 命名空间中。

构建查询选择器

在 AngleSharp v0.9 中，我们可以直接构建一个 ISelector，像这样：

var parser = new CssParser();
ISelector selector = parser.ParseSelector("p > a");

从 AngleSharp v0.10 开始，应避免直接访问此类功能。CssParser 已被移除，仅以简化形式存在于 AngleSharp.Core（无 CSS 支持）中，它实现了 ICssSelectorParser 接口。

当前访问此功能的方式是通过服务集合。

IConfiguration config = Configuration.Default;

// 使用现有的（或新的）上下文
IBrowsingContext context = BrowsingContext.New(config);

// 获取已注册的解析器实例
ICssSelectorParser parser = context.GetService<ICssSelectorParser>();

// 如之前一样使用
ISelector selector = parser.ParseSelector("foo");

通常，BrowsingContext 实例已经存在，因此访问变得更加简单。

脚本

:warn: 目前，AngleSharp.Scripting.Js 与 AngleSharp v0.10 不兼容。

我们计划弃用此包并发布 AngleSharp.Js 替代。在此期间，没有替代品。

建议：暂时停留在 AngleSharp v0.10 之前的版本，并等待 AngleSharp.Js 发布。对于带来的不便，我们深表歉意！

命名空间

AngleSharp 当前版本重新组织了命名空间的使用方式。虽然早期版本使用如 AngleSharp.Dom.Html 的模型，新版本中使用的是，例如，AngleSharp.Html.Dom。

解析器也已移动。以前，您通过 AngleSharp.Parser.Html 访问 HTML 解析器。现在通过 AngleSharp.Html.Parser 进行访问。

AngleSharp.Network 命名空间已被移除。所有与 IO 相关的定义可以在 AngleSharp.Io（与 NuGet 包同名）中找到。与网络相关的定义包含在 AngleSharp.Io.Network 中。

此外，任何核心级别的文本处理代码都可以在 AngleSharp.Text 中找到。主要被视为浏览器部分的内容现在位于 AngleSharp.Browser 中。

扩展方法

通用命名空间 AngleSharp.Extensions 已不存在。现在扩展方法总是包含在它们各自对应的命名空间中。例如，像 GetAncestors 这样的节点扩展方法现在位于 AngleSharp.Dom 中（因为它们是针对 INode 的通用扩展，且独立于 IHtmlElement ）。

扩展方法现在也被视为脚本引擎为 AngleSharp 带来可扩展性的重要部分。由于 C# 不允许我们创建扩展属性，例如，IElement 的 Style 现在以扩展方法的形式存在于 AngleSharp.Css 中。实际上，定义了两个扩展方法，GetStyle 和 SetStyle 。它们定义在一个静态类中，该类对每个要扩展的 DOM 接口包含了 DomExposed 属性。为了将这些方法定义为属性，使用了 DomAccessor 属性。

对于处理文本源（例如，在解析器中）来说， AngleSharp.Text 命名空间很有趣。它也携带了用于处理，例如，StringSource 的扩展方法，这是一个围绕现有流的源调查对象（与围绕来自 Stream 的文本文档的 TextSource 相对）。

缺失？

如有疑问，请随时在 StackOverflow 或 GitHub 上提问。如果有关迁移的重要内容尚不清楚，应该将其包含在此指南中。

如果您发现了一些应该在这里解释的内容，也可以直接为此指南提交 PR。谢谢！

在本文档中