---
title: "sdk/windows"
description: "适用于 WinUI 3 应用的 C# / .NET SDK，使用 WebView2 进行授权、PKCE S256 和 DPAPI 保护的 IsolatedStorage 进行 token 持久化。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/windows

## 状态

包状态为 **已实现 · 本地已验证**。dotnet test 通过 19 个测试用例（net8.0 跨平台构建和 net10.0）。Windows 专有 API（WebView2、DPAPI、WinUI 3）需要 Windows 构建环境验证。IdP 往返验证待人工核实。本页面记录已实现的行为，不代表生产就绪声明。

## 要求

- .NET 8 和 Windows App SDK 1.6+
- WebView2 运行时（常青版——随 Microsoft Edge 预装）
- 应用必须在项目文件中设置 <UseWinUI>true</UseWinUI>

## 安装

在应用项目文件中添加 PackageReference：

```xml
<ItemGroup>
  <PackageReference Include="Xid.Windows" Version="0.1.0" />
</ItemGroup>
```

## 快速开始

```csharp
using Xid.Windows;

// 1. Configure in App.xaml.cs OnLaunched
XidClient.Shared.Configure(new XidConfiguration
{
Issuer      = new Uri("https://xid.dev"),
ClientId    = "your_client_id",
RedirectUri = "com.example.myapp://auth/callback",
// Scopes default: openid profile email offline_access
});

// 2. Sign in (opens embedded WebView2 window)
XidSession session = await XidClient.Shared.SignInAsync();
Console.WriteLine($"Signed in: {session.User.Email}");

// 3. Get a valid access token (auto-refresh)
string? token = await XidClient.Shared.GetAccessToken();

// 4. Get current session
XidSession? current = await XidClient.Shared.GetSession();

// 5. Sign out
await XidClient.Shared.SignOut();
```

## 自定义 URI scheme callback（可选）

如果使用自定义 URI scheme 重定向而非 WebView2 嵌入窗口，请将协议激活 URI 转发给 `HandleRedirectAsync`：

```csharp
// App.xaml.cs
protected override void OnActivated(IActivatedEventArgs args)
{
if (args.Kind == ActivationKind.Protocol)
{
    var protocolArgs = (ProtocolActivatedEventArgs)args;
    await XidClient.Shared.HandleRedirectAsync(protocolArgs.Uri);
}
}
```

## 核心 API

| 方式 | 描述 |
| --- | --- |
| `Configure(XidConfiguration)` | 初始化 SDK。在应用启动时调用一次。 |
| `SignInAsync(options?, ct)` | 以 PKCE S256 打开嵌入式 WebView2 授权窗口。完成后返回 XidSession。 |
| `HandleRedirectAsync(Uri, ct)` | 处理自定义 URI scheme callback 并交换授权码。 |
| `GetSession(ct)` | 返回当前会话，接近过期时自动刷新。 |
| `GetAccessToken(options?, ct)` | 返回有效的访问令牌字符串，如需刷新则触发刷新。 |
| `SignOut(ct)` | 从 DPAPI 保护的 IsolatedStorage 中清除本地会话 token。 |
| `SetTokenStorage(ITokenStorage)` | 用自定义 ITokenStorage 实现替换默认的 DpapiTokenStorage。 |

## 存储适配器

默认存储使用 DPAPI（CurrentUser 范围）加密 token，并将其持久化到 IsolatedStorage。实现 `ITokenStorage` 以使用 Windows Hello 或 Credential Manager：

```csharp
public sealed class MyCustomStorage : ITokenStorage
{
public Task SaveAsync(StoredTokenSet tokens, CancellationToken ct = default) { ... }
public Task<StoredTokenSet?> LoadAsync(CancellationToken ct = default) { ... }
public Task ClearAsync(CancellationToken ct = default) { ... }
}
XidClient.Shared.SetTokenStorage(new MyCustomStorage());
```

## 依赖项

| 包 | 版本 | 用途 |
| --- | --- | --- |
| `Microsoft.WindowsAppSDK` | 1.6.250228002 | WinUI 3 宿主和 WebView2 嵌入 |
| `Microsoft.Web.WebView2` | 1.0.3065.39 | 基于 Chromium 的嵌入式授权窗口 |
| `System.Security.Cryptography.ProtectedData` | 8.0.0 | DPAPI token 静态加密 |

## 安全

- 公共客户端——不存储或传输客户端密钥。
- 仅 PKCE S256。服务器拒绝 plain challenge 方式。
- 使用 DPAPI（CurrentUser 范围）加密 token，并存储在 IsolatedStorage 中。其他 Windows 用户账户无法访问。
- 每次请求生成 OAuth state；在重定向时验证以防 CSRF。

## 已知限制

- 必须安装 WebView2 运行时。WebAuthenticationBroker 作为回退方案已在计划中，但尚未实现。
- 基于 JWKS 的 ID token 验签和 end\_session 登出已实现并完成本地测试。真实 Windows WebView2、DPAPI 和 IdP 往返验证前仍不具备 L4 支持。
- DpapiTokenStorage 不能在非 Windows 平台上运行。交叉编译时请使用其他 ITokenStorage 实现。

Source: https://xid.dev/zh-hans/sdks/windows/index.mdx