Zpracovat změnu stavu hardwarového klíče Microsoft Copilot

Tento článek popisuje, jak se aplikace mohou zaregistrovat k aktivaci a přijímání oznámení při stisknutí, stisknutí a přidržení nebo uvolnění hardwarové klávesy Microsoft Copilot nebo kombinace kláves Windows + C. Tato funkce umožňuje aplikacím provádět různé akce v závislosti na zjištěné změně stavu klíče. Aplikace může například provést normální aktivaci, když je stisknutá klávesa, ale po stisknutí a podržení klávesy pořídit snímek obrazovky. Nebo aplikace může začít nahrávat zvuk a zobrazovat indikátor stavu, který se nahrává při stisknutí a přidržení klávesy, a po uvolnění klávesy zastavit nahrávání zvuku. Klávesa musí být stisknuta a přidržována nejméně 300 ms, aby se přesunula do přidržovaného stavu.

Tato funkce rozšiřuje funkce základního Microsoft Copilot poskytovatele hardwarových klíčů, který se jednoduše zaregistruje při stisknutí hardwarové klávesy. Další informace najdete v tématu Microsoft Copilot poskytovatelé hardwarových klíčů.

Zbytek tohoto článku vám pomůže vytvořit jednoduchou aplikaci WinUI 3 jazyka C#, která reaguje na aktivaci iniciovanou jedním stisknutím nebo stisknutím a podržením a uvolněním tlačítka Microsoft Copilot.

Vytvoření nového project

V Visual Studio vytvořte nový project. V tomto příkladu v dialogovém okně Vytvořit nový projekt nastavte filtr jazyka na C# a typ projektu na WinUI a pak vyberte "Prázdná aplikace WinUI (zabaleno)".

Přidání vlastnosti ke sledování stavu stisknutí klávesy Microsoft Copilot

V tomto příkladu vytvoříme vlastnost s názvem State , kterou použijeme k zobrazení aktuálního stavu aktivace v uživatelském rozhraní. Uvnitř MainWindow.xaml.csdefinice MainWindow přidejte následující kód pro vytvoření řetězcové vlastnosti, se kterou můžeme vytvořit vazbu v souboru XAML.

// MainWindow.xaml.cs
public event PropertyChangedEventHandler? PropertyChanged;

private void OnPropertyChanged([CallerMemberName] string propertyName = "State")
{
    PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}

public void SetState(string state)
{
    State = state;
}

private string _state;
public string State
{
    get => _state;
    set
    {
        if (_state != value)
        {
            _state = value;
            OnPropertyChanged();
        }
    }
}

Přidejte do uživatelského rozhraní ovládací prvek TextBlock , aby se zobrazil aktuální stav aktivace aplikace. Nahraďte výchozí element StackPanel v MainWindow.xaml následujícím kódem.

<!-- MainWindow.xaml -->
<StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
    <TextBlock Name="KeyStateText" Text="{x:Bind State, Mode=OneWay}" />
</StackPanel>

Nakonec aktualizujte MainWindow konstruktor tak, aby vzal argument, který nastaví State vlastnost při vytvoření okna.

// MainWindow.xaml.cs
public MainWindow(string state)
{
    this.InitializeComponent();

    SetState(state);
}

Registrace k aktivaci identifikátoru URI

Systém spustí zprostředkovatele hardwarových klíčů Microsoft Copilot pomocí aktivace identifikátoru URI. Zaregistrujte spouštěcí protokol přidáním elementu uap:Protocol do manifestu aplikace. Další informace o tom, jak se zaregistrovat jako výchozí obslužná rutina pro schéma identifikátoru URI, naleznete v tématu Zpracování aktivace identifikátoru URI.

Následující příklad ukazuje, jak uap:Extension registruje schéma URI "myapp-copilothotkey".

<!-- Package.appxmanifest -->
...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
...

<Extensions> 
  ...
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="myapp-copilothotkey"> <!-- app-defined protocol name -->
      <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  ...

rozšíření aplikace Microsoft Copilot pro hardwarový klíč

Aby se aplikace mohla zaregistrovat jako poskytovatel hardwarového klíče Microsoft Copilot, musí být zabalená. Informace o balíčkování aplikací naleznete v části Přehled identity balíčku v aplikaci Windows. Microsoft Copilot poskytovatelé hardwarových klíčů deklarují své registrační informace v uap3:AppExtension. Atribut Název rozšíření musí být nastaven na "com.microsoft.windows.copilotkeyprovider". Aby aplikace podporovaly změny stavu klíče, musí do deklarace uap3:AppExtension zadat některé další položky.

Uvnitř elementu uap3:AppExtension přidejte element uap3:Properties s podřízenými elementy PressAndHoldStart a PressAndHoldStop. Obsah těchto prvků by měl být identifikátor URI schématu protokolu registrovaného v manifestu v předchozím kroku. Argumenty řetězce dotazu určují, zda se identifikátor URI spouští, protože uživatel stiskl a držel klávesovou zkratku, nebo protože uživatel klávesovou zkratku uvolnil. Aplikace používá tyto hodnoty řetězce dotazu během aktivace aplikace k určení správné akce, která se má provést. Zadání elementu SingleTap je volitelné, ale může být užitečné určit, zda byla aplikace spuštěna z hardwarového klíče Copilot.

<!-- Package.appxmanifest -->

<Extensions> 
  ...
  <uap3:Extension Category="windows.appExtension"> 
    <uap3:AppExtension Name="com.microsoft.windows.copilotkeyprovider"  
      Id="MyAppId" 
      DisplayName="App display name" 
      Description="App description" 
      PublicFolder="Public"> 
      <uap3:Properties> 
        <SingleTap>myapp-copilothotkey://?state=Tap</SingleTap>
        <PressAndHoldStart>myapp-copilothotkey://?state=Down</PressAndHoldStart> 
        <PressAndHoldStop>myapp-copilothotkey://?state=Up</PressAndHoldStop>
      </uap3:Properties> 
    </uap3:AppExtension>
  </uap3:Extension> 
  ...

Zpracování aktivace identifikátoru URI

Pokud chcete zjistit, jestli byla aplikace aktivována prostřednictvím aktivace identifikátorem URI, zavolejte AppInstance.GetActivatedEventArgs a zkontrolujte, jestli hodnota AppActivationArguments.Kind je Protocol. Pokud se aplikace spustila prostřednictvím aktivace protokolu, zkontrolujte, jestli je schéma identifikátoru URI stejné jako název protokolu, který jste zadali v manifestu aplikace. Pokud všechny tyto testy projdou, víte, že aplikace byla aktivována uživatelem stisknutím hardwarové klávesy Copilot. V tomto okamžiku můžete analyzovat řetězec dotazu URI a získat parametr stavu , který bude obsahovat hodnoty, které jste zadali v elementech PressAndHoldStart a PressAndHoldStop v manifestu aplikace.

// App.xaml.cs

protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    var eventargs = AppInstance.GetCurrent().GetActivatedEventArgs();
    string state = "";
    if ((eventargs != null) && (eventargs.Kind == ExtendedActivationKind.Protocol))
    {
        var protocolArgs = (Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs)eventargs.Data;
        WwwFormUrlDecoder decoderEntries = new WwwFormUrlDecoder(protocolArgs.Uri.Query);
        state = Uri.UnescapeDataString(decoderEntries.GetFirstValueByName("state"));
    }
    state = (state == "") ? "Launched" : state;

    m_window = new MainWindow(state);
    m_window.Activate();
}

Zpracování rychlého vyvolání cesty

Kromě aktivace identifikátorem URI se mohou aplikace zaregistrovat, aby podporovaly rychlé spuštění, ve kterém spuštěná aplikace přijímá zprávy o hardwarové aplikaci Copilot prostřednictvím zpráv v okně. U aktuálně spuštěné aplikace je tato metoda vyvolání rychlejší než aktivace identifikátorem URI a poskytuje lepší uživatelské prostředí, protože aplikace může začít naslouchat řeči rychleji po stisknutí a přidržení klávesy.

Aktualizace souboru manifestu aplikace pro podporu rychlého vyvolání cesty

Pokud chcete přidat podporu pro rychlé vyvolání cesty, aktualizujte rozšíření com.microsoft.windows.copilotkeyprovider a přidejte atribut MessageWParam do elementů SingleTap, PressAndHoldStart a PressAndHoldStop . Každá hodnota MessageWParam musí být jedinečné 32bitové celé číslo, ale použité hodnoty jsou zvoleny aplikací. V tomto příkladu se používají hodnoty 0, 1 a 2. Tyto hodnoty budou použity později v příkladu při předání v parametru wParam zprávy systému Windows k určení aktuálního stisknutého stavu hardwarové klávesy Windows Copilot.

<!-- Package.appxmanifest -->

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.copilotkeyprovider"
    Id="MyAppId"
    DisplayName="App display name"
    Description="App description"
    PublicFolder="Public">
    <uap3:Properties>
      <SingleTap MessageWParam="0">myapp-copilothotkey://?state=Tap</SingleTap>
      <PressAndHoldStart MessageWParam="1">myapp-copilothotkey://?state=Down</PressAndHoldStart>
      <PressAndHoldStop MessageWParam="2">myapp-copilothotkey://?state=Up</PressAndHoldStop>
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

Přístup k rozhraní Win32 API pro registraci oken

Aktivace rychlé cesty je povolena nastavením vlastnosti na IPropertyStore přidružené k jednomu z oken aplikace. K tomu vyžaduje přístup k některým nativním rozhraním API Win32. Tento názorný postup použije knihovnu CsWin32, která automatizuje generování vazeb jazyka C# a je k dispozici jako balíček NuGet.

V aplikaci Visual Studio v Průzkumník řešení klikněte pravým tlačítkem na soubor projektu a vyberte Spravovat balíčky NuGet.... Na kartě Procházet Správce balíčků NuGet vyhledejte "cswin32" a vyberte balíček "Microsoft.Windows.CsWin32" a klikněte na Nainstalovat.

Po instalaci balíčku přidejte do project adresáře nový textový soubor a pojmenujte ho "NativeMethods.txt". Nástroj CsWin32 bude v tomto souboru hledat seznam rozhraní API Win32, pro která vygeneruje vazby. DoNativeMethods.txtzadejte následující názvy rozhraní API.

SUBCLASSPROC

SHGetPropertyStoreForWindow

IPropertyStore

SetWindowSubclass

DefSubclassProc

Registrujte okno pro rychlou aktivaci Microsoft Copilot.

Dále aktualizujeme Třídu MainWindow tak, aby se okno zaregistrovalo pro příjem rychlých volání z hardwarového klíče Copilot.

Nejprve zavolejte GetWindowHandle, abyste získali popisovač HWNDMainWindow. Zavolejte SHGetPropertyStoreForWindow, abyste získali IPropertyStore pro okno. Vytvořte nový PROPERTYKEY a nastavte člen fmtid na GUID pro aktivaci funkce Windows Copilot fastpath. Nastavte hodnotu vlastnosti na hodnotu definovanou aplikací, která se předá zpět do aplikace ze systému při změně stavu klíče hardwaru. Hodnota definovaná aplikací je ID zprávy windows, které musí být v rozsahu WM_APP. Další informace najdete v tématu WM_APP. Zavolejte funkci SetValue a poté funkci Commit, abyste potvrdili změnu v úložišti vlastností.

Nakonec vytvořte zpětné volání SUBCLASSPROC , které se bude volat při změně stavu hardwarového klíče. WindowSubClass je implementace zpětného volání, která se zobrazí v dalším kroku. Zavolejte SetWindowSubclass pro registraci zpětného volání.

private HWND hWndMain;
private Windows.Win32.UI.Shell.SUBCLASSPROC SubClassDelegate;
public const int WM_COPILOT = 0x8000 + 0x0001;

public MainWindow(string state)
{
    this.InitializeComponent();

    hWndMain = (HWND)WinRT.Interop.WindowNative.GetWindowHandle(this);

    var propertyStoreGUID = new Guid("886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99");
    var hr = PInvoke.SHGetPropertyStoreForWindow(hWndMain, in propertyStoreGUID, out var propertyStore);
    var key = new PROPERTYKEY();
    var copilotFastpathGUID = new Guid("38652BCA-4329-4E74-86F9-39CF29345EEA");
    key.fmtid = copilotFastpathGUID;
    key.pid = 0x00000002;
    var value = new PROPVARIANT();
    value.Anonymous.Anonymous.vt = VARENUM.VT_UINT;
    value.Anonymous.decVal = WM_COPILOT;
    ((IPropertyStore)propertyStore).SetValue(in key, in value);
    ((IPropertyStore)propertyStore).Commit();

    SubClassDelegate = new Windows.Win32.UI.Shell.SUBCLASSPROC(WindowSubClass);
    bool bRet = PInvoke.SetWindowSubclass(hWndMain, SubClassDelegate, 0, 0);

    SetState(state);
}

Implementujte zpětné volání pro podtřídu okna

Posledním krokem v tomto příkladu je implementace callbacku podtřídy okna, který bude vyvolán při každém běhu aplikace a při změně stavu hardwarového klíče Windows Copilot. V tomto příkladu zkontrolujeme, že zpráva okna je hodnota WM_COPILOT , kterou jsme zadali při nastavení hodnoty úložiště vlastností v předchozím kroku. Potom zkontrolujeme hodnotu argumentu wParam a zjistíme, které z hodnot, které jsme zadali pomocí atributů MessageWParam v manifestu aplikace, byly předány. Funkce SetState se volá k aktualizaci uživatelského rozhraní s aktuálním stavem.

private LRESULT WindowSubClass(HWND hWnd, uint uMsg, WPARAM wParam, LPARAM lParam, nuint uIdSubclass, nuint dwRefData)
{
    switch (uMsg)
    {
        case WM_COPILOT:
        {
            switch (wParam.Value)
            {
                case 0:
                    SetState("SingleTap");
                    break;
                case 1:
                    SetState("PressAndHold START");
                    break;
                case 2:
                    SetState("PressAndHold END");
                    break;
            }
        }
        break;

    }
    return PInvoke.DefSubclassProc((HWND)hWnd, uMsg, wParam, lParam);

}

Podepsání zprostředkovatele hardwarového klíče Windows Copilot

Aby byly aplikace poskytovatele povolené jako cíl hardwarového klíče Microsoft Copilot, musí být podepsané. Informace o balení a podepisování aplikace najdete v tématu Přibalení desktopové nebo upW aplikace v Visual Studio.