barcode-capture-net-ios

适用于 iOS 的 BarcodeCapture .NET 技能

重要：请勿轻信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCapture API 在不同主要 SDK 版本之间变化显著——属性可能会重命名、移除或重新组织。.NET 绑定使用的命名约定也与原生 Swift SDK 不同（PascalCase、使用 Create(...) 工厂方法而不是 init(context:settings:)、使用 Enabled 而不是 isEnabled 等）。

编写或建议代码之前，务必根据此技能提供的参考资料核实 API。 请勿依赖记忆中的方法签名、参数或属性名称。如果在提供的参考资料中找不到某个 API，请先获取相关文档页面，再作答。

值得特别指出的 .NET-iOS 注意事项：

• 此技能面向非 MAUI .NET for iOS 工作负载（项目使用 <TargetFramework>net10.0-ios</TargetFramework>，且没有 <UseMaui> 标志）。对于 MAUI 应用，请改用 barcode-capture-net-maui 技能。
• .NET API 使用 PascalCase 工厂方法，而不是 Swift 的 BarcodeCapture(context:settings:) 初始化器。请使用 BarcodeCapture.Create(context, settings)、BarcodeCaptureSettings.Create()、BarcodeCaptureOverlay.Create(barcodeCapture, dataCaptureView)、DataCaptureView.Create(dataCaptureContext, frame)。
• 条码类型名称使用 C# PascalCase：Symbology.Ean13Upca、Symbology.Ean8、Symbology.Code128、Symbology.InterleavedTwoOfFive、Symbology.Qr、Symbology.DataMatrix。它们不是 Swift 的 .ean13UPCA 风格。
• 捕获模式的启用属性是 barcodeCapture.Enabled（不是 IsEnabled，也不是 Swift 的 isEnabled）。
• CodeDuplicateFilter 的类型是 TimeSpan，不是 Swift 的 TimeInterval。请使用 CodeDuplicate.DefaultDuplicateFilter、CodeDuplicate.ReportDataAndSymbologyOnlyOnce、TimeSpan.FromMilliseconds(500)、TimeSpan.FromSeconds(2.5) 或 TimeSpan.Zero。将 CodeDuplicateFilter = 0.5（作为 double）会导致类型错误。
• BarcodeCapture.RecommendedCameraSettings 是一个静态属性，不是方法。标准用法（官方 .NET iOS 示例中使用）是 camera = Camera.GetDefaultCamera(); camera.ApplySettingsAsync(BarcodeCapture.RecommendedCameraSettings);。在 .NET 绑定中还存在一个 Camera.GetDefaultCamera(CameraSettings?) 重载（内部会调用 ApplySettingsAsync），但示例使用明确的两行写法——为清晰起见，建议优先使用这种写法。
• IBarcodeCaptureListener 回调使用 C# 命名：OnBarcodeScanned、OnSessionUpdated、OnObservationStarted、OnObservationStopped。IFrameData 参数的名称是 frameData。
• .NET 绑定还在 BarcodeCapture 上提供了基于 C# 事件的 API：BarcodeScanned 和 SessionUpdated（二者均为 EventHandler<BarcodeCaptureEventArgs>）。可以使用监听器接口或事件，但不要通过两种方式重复注册同一个处理程序。
• OnBarcodeScanned 会在 UI 线程之外调用。任何 UI 更新都必须通过 DispatchQueue.MainQueue.DispatchAsync(...) 分派。
• **务必在 OnBarcodeScanned 和 OnSessionUpdated 末尾调用 frameData.Dispose()。**官方 iOS 示例会显式释放 frame，以避免视频流“冻结、无响应或严重卡顿”。在 iOS 上这不是可选操作。
• 请在 OnBarcodeScanned 顶部调用 barcodeCapture.Enabled = false，再执行其他操作，以防止重复扫描或扫描竞争。当应用准备好再次扫描时，使用 barcodeCapture.Enabled = true 重新启用。
• DataCaptureView.Create(dataCaptureContext, frame) 的初始 frame 参数接受 CGRect（或 this.View.Bounds）——这与仅接受 context 的 Android 绑定不同。设置 AutoresizingMask = UIViewAutoresizing.FlexibleHeight | UIViewAutoresizing.FlexibleWidth，并将其作为子视图添加到 this.View。
• 生命周期：ViewWillAppear 启用捕获模式并启动摄像头；ViewWillDisappear 停止摄像头。官方示例只在 ViewWillDisappear 中停止摄像头，并在 OnBarcodeScanned 中设置 Enabled = false——这两种模式都有效。
• 必需的 Info.plist 键是 NSCameraUsageDescription（Privacy - Camera Usage Description）。缺少此项会导致应用在首次访问摄像头时崩溃。
• NuGet 包为 Scandit.DataCapture.Core 和 Scandit.DataCapture.Barcode。不要使用 *.Maui 包——它们仅适用于 MAUI。不要根据训练数据猜测版本——在固定版本前，请通过 WebFetch 从 https://www.nuget.org/packages/Scandit.DataCapture.Barcode/ 获取最新稳定版。编造一个不存在的版本（例如仅发布了 8.4.0 时写成 8.13.0）会导致 dotnet restore 因 Unable to find package Scandit.DataCapture.Core with version (>= …) 而失败。完整流程请参阅 references/integration.md 的第 0 步。
• **SDK 8.0+ 需要显式初始化。**在触及任何 Scandit API 之前，于 AppDelegate.FinishedLaunching 中调用 ScanditCaptureCore.Initialize() + ScanditBarcodeCapture.Initialize()（通常在创建 window / 根视图控制器之前）。否则 SDK 的 DI 容器不会注册任何内容，首次调用 DataCaptureView.Create / BarcodeCapture.Create 时应用会在启动阶段崩溃。6.x / 7.x 不需要——这些主版本会自行初始化。完整的 AppDelegate 模板请参阅集成指南。

意图路由

根据用户的请求，在回复前加载相应的参考文件：

• 从头集成 BarcodeCapture、配置设置、自定义反馈、添加取景器、处理扫描结果，或在扫描后执行异步操作（例如“将 BarcodeCapture 添加到我的 .NET iOS 应用”“在 C# / iOS 中设置条码扫描”“如何在 net-ios 中使用 BarcodeCapture”“筛选重复扫描”“关闭提示音”“添加取景器”“查找条码时禁用扫描”）→ 阅读 references/integration.md 并遵循其中的说明。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit .NET SDK 升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md 并遵循其中的说明。
• 用 BarcodeCapture 替换第三方条码扫描器（例如“用 BarcodeCapture 替换我的 ZXing.Net.Mobile 扫描器”“将 AVFoundation 条码扫描迁移到 Scandit”“从 [library] 切换到 BarcodeCapture”）→ 阅读 references/third-party-migration.md 并遵循其中的说明。

API 使用政策

仅使用下方 Scandit 参考资料中明确记载的 API。不要臆造或猜测方法签名、参数或属性名称。如果不确定某个 API 是否存在或如何调用，或者遇到编译错误，请先获取相关参考页面，再回复。不要让用户自行查阅文档。回答后，务必附上相关链接，方便用户进一步了解。

切勿编造或猜测文档 URL。 需要特定类或属性的 API 页面时：

1. 先检查已获取的页面是否包含指向该页面的直接超链接——主题页面会直接链接到相关 API 符号。请求获取内容时，务必一并要求提供链接。
2. 如果没有找到直接链接，请获取 API 索引（见下表中的 完整 API 参考），从中提取实际链接并访问。

URL 结构可能有所不同（例如 api/ui/ 子目录），猜测 URL 会导致 404 错误。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 native，许可证平台为 ios。

按以下顺序操作——切勿让用户等待 MCP：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，传入产品 native、平台 ios、app_identifier（应用的 bundle 或 application ID；对于 Web 应用，使用其生产域名，绝不能使用 localhost）和环境变量 SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用该结果中的密钥 ID，或使用 list_license_keys 获取的密钥 ID，调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征求用户同意再获取。聊天中最多只显示经过遮蔽的预览；绝不显示完整密钥。

2. Scandit MCP 服务未连接——告知用户一次，他们可以在自己的 MCP 客户端中连接远程 Scandit MCP 服务 https://ssl.scandit.com/mcp，然后继续执行第 1 步。不要自行修改 MCP 客户端配置。

   身份验证基于浏览器，因此不支持无头模式或 CI。该服务仅签发试用密钥；绝不会创建、撤销或修改生产许可证。

3. 用户拒绝，或没有 MCP 客户端——让用户自行前往 https://ssl.scandit.com 生成密钥（尚无账户：https://ssl.scandit.com/dashboard/sign-up?p=test），然后粘贴密钥。

然后将密钥写入代码：在许可证密钥调用中，用密钥替换占位符；密钥可以是 get_license_key 返回的密钥，也可以是用户粘贴或提供的密钥。聊天中仍然只能显示经过遮蔽的预览。不要在项目、文件或环境中搜索密钥。

参考资料

根据用户的问题，引导他们前往合适的资源：

主题	资源
开始使用	开始使用（.NET for iOS）
高级主题（自定义反馈、取景器、位置选择、扫描意图、复合码）	高级配置
不同主版本 SDK 之间的迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API（.NET iOS）

此技能涵盖的 API

官方 RST 文档中所有带有 :available: dotnet.ios 的类，都在 references/integration.md 中进行了说明：

• BarcodeCapture — Create(context, settings)、Create(settings)、Enabled、PointOfInterest、Feedback、BarcodeCaptureLicenseInfo、Context、静态属性 RecommendedCameraSettings、ApplySettingsAsync、AddListener / RemoveListener、事件 BarcodeScanned / SessionUpdated。
• BarcodeCaptureSettings — Create()、EnableSymbology、EnableSymbologies(ICollection<Symbology>)、EnableSymbologies(CompositeType)、GetSymbologySettings、EnabledSymbologies、EnabledCompositeTypes、CodeDuplicateFilter、LocationSelection、BatterySaving、ScanIntention、SetProperty / GetProperty<T> / TryGetProperty<T>。
• BarcodeCaptureFeedback — 静态属性 DefaultFeedback、Success。
• BarcodeCaptureSession — NewlyRecognizedBarcode、NewlyLocalizedBarcodes、FrameSequenceId、Reset()。
• IBarcodeCaptureListener — OnObservationStarted、OnObservationStopped、OnBarcodeScanned、OnSessionUpdated。
• BarcodeCaptureEventArgs — BarcodeCapture、Session、FrameData。
• BarcodeCaptureLicenseInfo — LicensedSymbologies。
• BarcodeCaptureOverlay — Create(barcodeCapture, view)、Create(barcodeCapture)、Brush、静态属性 DefaultBrush、Viewfinder、ShouldShowScanAreaGuides、SetProperty。