指南

介绍
指南

Cookies

本文档描述了如何使用 cookies。

概述

DotNetBrowser 将 cookie 的工作委托给 Chromium 引擎。 Chromium 决定如何从网络服务器下载 cookie，从 HTTP 标头中提取它们并将它们存储在本地文件系统（持久性 cookie）或内存（会话 cookie）中。

ICookieStore 接口允许您获取、修改和删除 cookie。 Cookie 类提供有关特定 cookie 的信息。

要获取特定 Profile 的 ICookieStore ，请使用 Profiles.CookieStore() 方法。 IEngine.CookieStore() 方法返回与默认配置文件关联的 CookieStore。

支持的协议

DotNetBrowser 支持使用以下协议发送的 cookie：

  • HTTP
  • HTTPS
  • WS (WebSocket)
  • WSS (Secured WebSocket)

如果使用不在列表中的协议发送 cookie，例如 ftp://，它将不会存储在 cookie 存储中。

DotNetBrowser 支持以下类型的 cookie：

  • 持久性 cookie — 存储在 Chromium 用户数据目录中。 如果删除 Chromium 用户数据目录，所有持久性 cookie 也将被删除。
  • 会话 cookie — 存储在应用程序内存中，当应用程序终止时会自动删除。
  • 安全 cookie — 只能通过 HTTPS 加密连接传输。 这使得 cookie 不太可能暴露于使用窃听的 cookie 盗窃。
  • HttpOnly cookies — 不能被客户端 API 访问，例如 JavaScript。 此限制消除了使用跨站脚本 (XSS) 窃取 cookie 的威胁。 但是，cookie 仍然容易受到跨站跟踪 (XST) 和跨站请求伪造 (XSRF) 攻击。

当您修改 cookie 时，使用 ICookieStore.Flush() 方法可以将更改保存在 cookie 存储中。

要获取所有 cookie，请使用 GetAllCookies() 方法：

engine.Profiles.Default.CookieStore.GetAllCookies()
    .Result.ToList().ForEach(cookie => Console.WriteLine("cookie = " + cookie));

engine.Profiles.Default.CookieStore.GetAllCookies().Result.ToList().
    ForEach(Sub(cookie) 
        Console.WriteLine("cookie = " & cookie.ToString())
    End Sub)

要通过 URL 获取所有 cookie，请使用带有字符串参数的 GetAllCookies() 方法：

engine.Profiles.Default.CookieStore.GetAllCookies("https://www.google.com")
    .Result.ToList().ForEach(cookie => Console.WriteLine("cookie = " + cookie));

engine.Profiles.Default.CookieStore.GetAllCookies("https://google.com").Result.ToList().
    ForEach(Sub(cookie)
        Console.WriteLine("cookie = " & cookie.ToString())
    End Sub)

持久性

要创建持久性 cookie，请使用以下代码示例：

Cookie cookie = new Cookie.Builder(".google.com")
{
    Name = "name",
    Value = "value",
    ExpirationTime = expirationTime,
    Path = "/"
}.Build();

bool success = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result;
engine.Profiles.Default.CookieStore.Flush();

Dim cookie As Cookie = New Cookie.Builder(".google.com") With {
    .Name = "name",
    .Value = "value",
    .ExpirationTime = expirationTime,
    .Path = "/"
}.Build()

Dim success As Boolean = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result
engine.Profiles.Default.CookieStore.Flush()

上面的代码示例为 http://www.google.com URL 创建了一个持久性 cookie。 如果成功创建 cookie 并将其添加到 cookie 存储，则 success 变量将为 true。

会话

要创建会话 cookie，请使用以下代码示例：

Cookie cookie = new Cookie.Builder(".google.com")
{
    Name = "name",
    Value = "value",
    Path = "/"
}.Build();

bool success = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result;
engine.Profiles.Default.CookieStore.Flush();

Dim cookie As Cookie = New Cookie.Builder(".google.com") With {
    .Name = "name",
    .Value = "value",
    .Path = "/"
}.Build()

Dim success As Boolean = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result
engine.Profiles.Default.CookieStore.Flush()

一些具有特定名称的 cookie 具有特定的语义。

名称以 __Host- 开头的 Cookie 必须使用安全标记设置，必须来自安全页面（HTTPS），必须未指定域（因此不会发送到子域），路径必须是 /。 域名应通过 API 指定，但在本例中仅用于验证目的。

Cookie cookie = new Cookie.Builder(".a.com")
{
    Name = "__Host-1PLSID",
    Value = "value",
    Secure = true,
    HttpOnly = false
}.Build();
bool success = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result;
engine.Profiles.Default.CookieStore.Flush();

Dim cookie As Cookie = New Cookie.Builder(".a.com") With {
    .Name = "__Host-1PLSID",
    .Value = "value",
    .Secure = True,
    .HttpOnly = False
}.Build()
Dim success As Boolean = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result
engine.Profiles.Default.CookieStore.Flush()

以 __Secure-（破折号是前缀的一部分）开头的 Cookie 名称必须通过安全页面（HTTPS）设置安全标记。 以下是创建这些 cookie 的方法：

Cookie cookie = new Cookie.Builder(".a.com")
{
    Name = "__Secure-Asd",
    Path = "/",
    Secure = true
}.Build();
bool success = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result;
engine.Profiles.Default.CookieStore.Flush();

Dim cookie As Cookie = New Cookie.Builder(".a.com") With {
    .Name = "__Secure-Asd",
    .Path = "/",
    .Secure = True
}.Build()
Dim success As Boolean = engine.Profiles.Default.CookieStore.SetCookie(cookie).Result
engine.Profiles.Default.CookieStore.Flush()

要删除所有 cookie，请使用 DeleteAllCookies() 方法：

int numberOfDeletedCookies = engine.Profiles.Default.CookieStore.DeleteAllCookies().Result;
engine.Profiles.Default.CookieStore.Flush();

Dim numberOfDeletedCookies As Integer = 
        engine.Profiles.Default.CookieStore.DeleteAllCookies().Result
engine.Profiles.Default.CookieStore.Flush()

要删除一个 cookie，请使用 Delete(Cookie) 方法。 下面的代码示例逐个删除所有 cookie，并获取操作结果：

engine.Profiles.Default.CookieStore.GetAllCookies().Result.ToList().ForEach(c => 
    engine.Profiles.Default.CookieStore.Delete(c).Wait());
engine.Profiles.Default.CookieStore.Flush();

engine.Profiles.Default.CookieStore.GetAllCookies().Result.ToList().ForEach(Function(c) 
        engine.Profiles.Default.CookieStore.Delete(c).Wait()
    End Function)
engine.Profiles.Default.CookieStore.Flush()

您可以使用 Network 的 CanSetCookieHandler 和 CanGetCookiesHandler 处理程序控制所有传入和传出的 cookie。

要抑制传出的 cookie，请使用以下代码示例：

network.CanSetCookieHandler = 
    new Handler<CanSetCookieParameters, CanSetCookieResponse>(p =>
    {
        return CanSetCookieResponse.Deny());
    }

network.CanSetCookieHandler = 
    New Handler(Of CanSetCookieParameters, CanSetCookieResponse)(Function(p) 
        Return CanSetCookieResponse.Deny()
    End Function)

要抑制传入的 cookie，请使用以下代码示例：

network.CanGetCookiesHandler = 
    new Handler<CanGetCookiesParameters, CanGetCookiesResponse>(p =>
    {
        return CanGetCookiesResponse.Deny());
    }

network.CanGetCookiesHandler = 
    New Handler(Of CanGetCookiesParameters, CanGetCookiesResponse)(Function(p)
        Return CanGetCookiesResponse.Deny()
    End Function)

您可以配置 Chromium 如何控制第三方 cookie：

  • 关闭控制。
  • 阻止第三方 cookie。
  • 在隐身模式下阻止第三方 cookie。

请查阅 CookieControlsMode 枚举中的可用选项。

例如：

IProfile profile = engine.Profile.Default;
profile.Preferences.ThirdPartyCookieMode = CookieControlsMode.BlockThirdParty;

Dim profile As IProfile = engine.Profile.Default
profile.Preferences.ThirdPartyCookieMode = CookieControlsMode.BlockThirdParty

加密

DotNetBrowser 默认支持 cookie 加密。 它使用 Chromium cookies 加密例程，因此 cookies 的存储方式与 Chromium 相同。

在 Windows 系统中，DotNetBrowser 仅使用 DPAPI 来加密 cookie。 目前没有替代方案。

Go Top