AtomUI/docs/releases/6.1.4-api-changes.md

AtomUI 6.1.4 API Change Examples

This document supplements the main 6.1.4 release notes with the breaking API changes and migration examples from 6.1.3. For the authoritative release entries, see the repository root CHANGELOG.md and CHANGELOG.zh-CN.md.

Applications that use SearchEdit search events, custom localization catalogs, manually constructed localization descriptors, or custom static language packages must migrate before upgrading.

Chinese version: 6.1.4 API 变更示例.

Quick Reference

Area	6.1.3	6.1.4
SearchEdit event	SearchButtonClick with RoutedEventArgs	SearchRequested with SearchRequestedEventArgs
SearchEdit Enter behavior	No built-in Enter request	Enter requests search by default; use IsSearchOnEnterEnabled to configure it
Catalog version identity	LanguageCatalogAttribute.ContractVersion	Stable enum keys and source fingerprints
Runtime localization descriptors	Constructors and descriptors carry ContractVersion	No version argument or property
Language-package verification	AtomUILanguageContractVersion and AtomUIRequireVerifiedLanguageContract	Verification inferred from the authoritative component reference
Localization build-task override	AtomUILocalizationBuildTasksAssembly	AtomUIBuildTasksAssembly shared by all build features

SearchEdit Request Migration

Replace SearchButtonClick with SearchRequested

SearchButtonClickEvent and SearchButtonClick have been removed. The replacement event represents a search request from either the search button or the Enter key. Its event arguments contain the text snapshot captured when the request was raised and the trigger source.

6.1.3

<atom:SearchEdit
    Text="{Binding Query}"
    SearchButtonClick="HandleSearchButtonClick" />

private void HandleSearchButtonClick(object? sender, RoutedEventArgs e)
{
    if (sender is SearchEdit searchEdit)
    {
        StartSearch(searchEdit.Text ?? string.Empty);
    }
}

6.1.4

<atom:SearchEdit
    Text="{Binding Query}"
    SearchRequested="HandleSearchRequested" />

private void HandleSearchRequested(object? sender, SearchRequestedEventArgs e)
{
    StartSearch(e.Query, e.Trigger);
}

private void StartSearch(string query, SearchTriggerSource trigger)
{
    var source = trigger switch
    {
        SearchTriggerSource.Button => "button",
        SearchTriggerSource.EnterKey => "enter",
        _ => throw new ArgumentOutOfRangeException(nameof(trigger))
    };

    Search(query, source);
}

Code that references the routed event field must migrate from SearchButtonClickEvent to SearchRequestedEvent. Use e.Query instead of reading SearchEdit.Text later; Query is the request-time snapshot and remains stable if the input changes while an asynchronous search is running.

Preserve button-only search behavior

Enter now raises SearchRequested on an unhandled KeyUp by default. Set IsSearchOnEnterEnabled to false when an existing application must preserve the 6.1.3 button-only behavior:

<atom:SearchEdit
    IsSearchOnEnterEnabled="False"
    SearchRequested="HandleSearchRequested" />

When IsOperating=true, SearchEdit suppresses requests from both the button and Enter key. Applications should keep using this property to prevent repeated requests while a search is in progress.

Localization Contract Migration

Remove Catalog contract versions

LanguageCatalogAttribute.ContractVersion has been removed. Catalog enum member names and matching XLIFF unit id values are the stable keys; published keys must be appended and must not be deleted, reordered, renamed, or reused for a different meaning.

6.1.3

using AtomUI.Localization;

[LanguageCatalog(ContractVersion = 3)]
public enum AppLangResourceKind
{
    Title,
    Save
}

6.1.4

using AtomUI.Localization;

[LanguageCatalog]
public enum AppLangResourceKind
{
    Title,
    Save
}

Do not replace the removed version with a custom numeric identity. Compatibility is validated from the Catalog ID, stable keys, source text, placeholders, and the generated source fingerprint.

Update manually constructed descriptors

LanguageCatalogDescriptor.ContractVersion and TranslationBundleDescriptor.ContractVersion have been removed, along with the corresponding constructor arguments.

6.1.3

var catalog = new LanguageCatalogDescriptor<AppLangResourceKind>(
    "Acme.App:Acme.AppLangResourceKind",
    3,
    [
        new LanguageCatalogUnitDescriptor("Title"),
        new LanguageCatalogUnitDescriptor("Save")
    ],
    static key => key switch
    {
        AppLangResourceKind.Title => 0,
        AppLangResourceKind.Save => 1,
        _ => -1
    });

var bundle = new TranslationBundleDescriptor(
    catalog.CatalogId,
    catalog.ContractVersion,
    LanguageTags.EnUS,
    TranslationSourceKind.ModuleBuiltIn,
    "Acme.App",
    ["Settings", "Save"]);

6.1.4

var catalog = new LanguageCatalogDescriptor<AppLangResourceKind>(
    "Acme.App:Acme.AppLangResourceKind",
    [
        new LanguageCatalogUnitDescriptor("Title"),
        new LanguageCatalogUnitDescriptor("Save")
    ],
    static key => key switch
    {
        AppLangResourceKind.Title => 0,
        AppLangResourceKind.Save => 1,
        _ => -1
    });

var bundle = new TranslationBundleDescriptor(
    catalog.CatalogId,
    LanguageTags.EnUS,
    TranslationSourceKind.ModuleBuiltIn,
    "Acme.App",
    ["Settings", "Save"]);

Most applications should not construct these descriptors directly. Update AtomUI packages together and regenerate the Catalog and bundle source rather than editing generated files.

Update static language-package projects

AtomUILanguageContractVersion and AtomUIRequireVerifiedLanguageContract are no longer accepted authoring contracts. Remove them from project properties and AtomUILanguage item metadata. A normal component ProjectReference, or an authoring-only component PackageReference, now supplies the authoritative Catalog automatically.

6.1.3

<PropertyGroup>
  <AtomUIBuildLanguagePackage>true</AtomUIBuildLanguagePackage>
  <AtomUILanguageTag>ja-JP</AtomUILanguageTag>
  <AtomUILanguageModuleId>Acme.Controls</AtomUILanguageModuleId>
  <AtomUILanguageContractVersion>3</AtomUILanguageContractVersion>
  <AtomUIRequireVerifiedLanguageContract>true</AtomUIRequireVerifiedLanguageContract>
</PropertyGroup>

<ItemGroup>
  <ProjectReference Include="../Acme.Controls/Acme.Controls.csproj" />
</ItemGroup>

6.1.4

<PropertyGroup>
  <AtomUIBuildLanguagePackage>true</AtomUIBuildLanguagePackage>
  <AtomUILanguageTag>ja-JP</AtomUILanguageTag>
  <AtomUILanguageModuleId>Acme.Controls</AtomUILanguageModuleId>
</PropertyGroup>

<ItemGroup>
  <ProjectReference Include="../Acme.Controls/Acme.Controls.csproj" />
</ItemGroup>

The normal component reference makes contract verification required. When the component is not available while a community language package is authored, the package remains Deferred and the consuming application validates it when the target module becomes active. Do not hand-author AtomUILanguageContractValidation in generated package props.

Rename custom build-task path overrides

Normal NuGet consumers do not set a build-task path. Custom source-build or test harnesses that override the task DLL location must rename AtomUILocalizationBuildTasksAssembly to the shared AtomUIBuildTasksAssembly property.

6.1.3

<PropertyGroup>
  <AtomUILocalizationBuildTasksAssembly>$(RepoRoot)/tools/AtomUI.Build.Tasks.dll</AtomUILocalizationBuildTasksAssembly>
</PropertyGroup>

6.1.4

<PropertyGroup>
  <AtomUIBuildTasksAssembly>$(RepoRoot)/tools/AtomUI.Build.Tasks.dll</AtomUIBuildTasksAssembly>
</PropertyGroup>

The shared property is used by localization, theme assets, and linked registration. Do not set different task assembly paths for individual AtomUI build features.

Rebuild compatibility boundary

Catalog and bundle constructor signatures changed, and generated package metadata no longer carries numeric contract versions. Upgrade the component package, Generator, application, and static language packages together. Re-export from the current authoritative en-US.xlf, rebuild all language packages, and do not mix 6.1.3 localization assemblies or generated language-package assets with 6.1.4 runtime packages.