barcode-capture-net-android

BarcodeCapture .NET for Android 技能

重要：切勿相信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeCapture API 在不同主要 SDK 版本之间会发生重大变化——属性可能会重命名、移除或重新组织。.NET 绑定也使用不同于 Kotlin/Java 原生 SDK 的命名约定（PascalCase、使用 Create(...) 工厂而非 forDataCaptureContext、使用 Enabled 而非 isEnabled 等）。

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

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

• 此技能面向非 MAUI 的 .NET for Android 工作负载（项目使用 <TargetFramework>net10.0-android</TargetFramework>，且没有 <UseMaui> 标志）。对于 MAUI 应用，请改用 barcode-capture-net-maui 技能。
• .NET API 使用 PascalCase 工厂方法，而不是 Kotlin 的 forDataCaptureContext / newInstance 名称。请使用 BarcodeCapture.Create(context, settings)、BarcodeCaptureSettings.Create()、BarcodeCaptureOverlay.Create(barcodeCapture, dataCaptureView)、DataCaptureView.Create(dataCaptureContext)。
• 符号体系名称采用 C# PascalCase：Symbology.Ean13Upca、Symbology.Ean8、Symbology.Code128、Symbology.InterleavedTwoOfFive、Symbology.Qr、Symbology.DataMatrix。它们不是 Kotlin 下划线风格（EAN13_UPCA、INTERLEAVED_TWO_OF_FIVE）。
• 捕获模式的启用属性是 barcodeCapture.Enabled（不是 IsEnabled）。.NET 绑定中的 IDataCaptureMode 接口公开的是 Enabled。
• CodeDuplicateFilter 的类型是 TimeSpan，不是 TimeInterval（那是 Kotlin/Java 类型）。请使用 CodeDuplicate.DefaultDuplicateFilter、CodeDuplicate.ReportDataAndSymbologyOnlyOnce、TimeSpan.FromMilliseconds(500)、TimeSpan.FromSeconds(2.5) 或 TimeSpan.Zero。将 CodeDuplicateFilter = 500 赋值会导致类型错误。
• BarcodeCapture.RecommendedCameraSettings 是一个静态属性，不是方法。标准模式（官方 .NET Android 示例中使用）是 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 更新都必须通过 RunOnUiThread(() => { … }) 调度。
• 在 OnBarcodeScanned 顶部先调用 barcodeCapture.Enabled = false，再执行任何操作，以防止重复扫描或扫描竞争。应用准备好再次扫描时，重新启用 barcodeCapture.Enabled = true。
• 在 OnPause() 中关闭相机，并在 OnResume() 中通过 camera.SwitchToDesiredStateAsync(FrameSourceState.Off) / FrameSourceState.On 重新启用。Activity 进入后台时，相机不得处于活动状态。
• 首次扫描前，请在运行时请求 Android.Manifest.Permission.Camera 权限；仅在清单中声明权限，在 API 23 及更高版本上并不足够。官方 .NET Android 示例使用带有 RequestPermissions 和 OnRequestPermissionsResult 的 CameraPermissionActivity 基类。
• 不要在 AndroidManifest.xml 中为带有 [Activity] 特性的类声明 <activity> 元素。 [Activity(MainLauncher = true, ...)] 特性是 .NET for Android 中的标准注册方式——构建过程会使用 .NET 生成的 Java 类名（通常为 <lowercase-namespace>.MainActivity）将正确命名的条目合并到最终清单中。手动添加的 <activity android:name=".MainActivity"> 会根据 <ApplicationId>（例如 com.companyname.MyApp.MainActivity）解析，无法匹配生成的类，导致启动时出现 ClassNotFoundException: Didn't find class ... .MainActivity。只在清单中添加本技能明确要求的元素（<uses-feature>、<uses-permission>，以及必要时 <application> 上的 android:theme）——Activity 交由特性处理。
• DataCaptureView.Create(dataCaptureContext) 返回一个 Android View。请将其添加到一个 FrameLayout 容器中，并将两个维度的 LayoutParams 都设为 MatchParent。.NET 绑定的 DataCaptureView.Create 不接受 Context 参数（Kotlin 的 DataCaptureView.newInstance(context, dataCaptureContext) 则不同）。
• 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。
• CameraPermissionActivity 辅助类继承自 AppCompatActivity，因此 .csproj 中必须包含 Xamarin.AndroidX.AppCompat。dotnet new android 会通过传递依赖引入此包；手动搭建的项目必须显式添加。固定版本时，请选择包含 Xamarin 补丁修订版在内的最高可用版本（例如 1.7.1.3，而非不带修订版的 1.7.1）——.X 后缀表示 Xamarin 绑定层级的更新，并包含关键的传递依赖修复；不带后缀的版本存在已知的 Xamarin.AndroidX.SavedState 不匹配问题，会导致构建失败，并出现 CS7069: Reference to type 'ISavedStateRegistryOwner' ... could not be found。
• AndroidManifest.xml 中的 <application> 必须使用 Theme.AppCompat 的派生主题。请在 <application> 元素上添加 android:theme="@style/Theme.AppCompat.DayNight.NoActionBar"（或其他 Theme.AppCompat 子类）。否则，AppCompatActivity 会在启动时立即抛出 java.lang.IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity。dotnet new android 默认不会设置此属性，因此集成 BarcodeCapture 时必须显式添加。
• 搭建全新项目时，优先使用 dotnet new android -o MyApp，而不是手写 csproj、清单或资源文件。此命令会生成可构建的项目框架，并包含正确的 OutputType、strings.xml 和启动器图标——本技能中的清单会引用这些内容。手写的 csproj 若使用 <OutputType>Library</OutputType>，会悄悄生成 .aar 而不是可安装的 .apk。
• **SDK 8.0+ 需要显式初始化。**请继承 Android.App.Application、添加 [Application] 特性，并在 OnCreate() 中、任何 Scandit 代码运行之前调用 ScanditCaptureCore.Initialize() 和 ScanditBarcodeCapture.Initialize()。否则，SDK 的 DI 容器没有注册项，首次调用 DataCaptureView.Create / BarcodeCapture.Create 时会在启动阶段崩溃。6.x / 7.x 不需要此操作——这些主版本会自行初始化。完整的 MainApplication.cs 模板请参见集成指南。

意图路由

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

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

API 使用政策

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

**绝不要构造或猜测文档 URL。**需要特定类或属性的 API 页面时：

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

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

许可证密钥

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

请按以下顺序操作——绝不要因 MCP 而阻滞用户：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，使用产品 native、平台 android、app_identifier（应用的 bundle 或 application id；对于 Web，使用其生产域名，绝不能使用 localhost）以及 env_var SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用密钥的 id 调用 get_license_key，该 id 可以从此结果或 list_license_keys 中获取；如果 list_license_keys 显示此密钥不是试用密钥，请先征求用户同意再获取。聊天中最多显示经过掩码处理的预览；绝不要输出完整密钥。

2. 未连接——只需告知用户一次：可以在其 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 Android）
高级主题（自定义反馈、取景器、位置选择、扫描意图、复合码）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API（.NET Android）

此技能涵盖的 API 范围

官方 RST 文档中所有标有 :available: dotnet.android 的类，均在 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。