Udostępnij za pośrednictwem

Obsługa zmian stanu klucza sprzętowego Microsoft Copilot

W tym artykule opisano, jak aplikacje mogą rejestrować się, aby były aktywowane i otrzymywały powiadomienia, gdy klawisz sprzętowy Copilot lub klawisz Windows + C zostanie naciśnięty, przytrzymany oraz zwolniony. Ta funkcja umożliwia aplikacjom wykonywanie różnych akcji w zależności od wykrytej zmiany stanu klucza. Na przykład aplikacja może wykonać normalną aktywację po jednokrotnym naciśnięciu klawisza, ale wykonać zrzut ekranu po jego przytrzymaniu. Lub aplikacja może rozpocząć nagrywanie dźwięku i pokazać wskaźnik stanu, że dźwięk jest rejestrowany po naciśnięciu i przytrzymaniu przycisku, a kończy nagrywanie dźwięku po jego zwolnieniu. Klawisz musi być naciśnięty i przytrzymywany przez co najmniej 300 ms, aby przejść do stanu przytrzymania.

Ta funkcja rozszerza funkcje podstawowego dostawcy kluczy sprzętowych Microsoft Copilot, który po prostu rejestruje się w celu uruchomienia po naciśnięciu klawisza sprzętu. Aby uzyskać więcej informacji, zobacz Microsoft Copilot dostawcy kluczy sprzętowych.

W pozostałej części tego artykułu opisano tworzenie prostej aplikacji WinUI w języku C# WinUI 3, która reaguje na aktywację zainicjowaną przez pojedyncze naciśnięcie lub naciśnięcie i wstrzymanie i zwolnienie przycisku Microsoft Copilot.

Utwórz nowy projekt

W Visual Studio utwórz nowy project. W tym przykładzie w oknie dialogowym Tworzenie nowego projektu ustaw filtr języka na C# i typ projektu na WinUI, a następnie wybierz pozycję "Pusta aplikacja WinUI (spakowana)".

Dodaj właściwość do śledzenia stanu naciśnięcia klawisza Microsoft Copilot

W tym przykładzie utworzymy właściwość o nazwie State , która będzie używana do wyświetlania bieżącego stanu aktywacji w interfejsie użytkownika. W MainWindow.xaml.cs, wewnątrz definicji MainWindow dodaj następujący kod, aby utworzyć właściwość ciągu, z którą możemy powiązać się w naszym pliku 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();
        }
    }
}

Dodaj kontrolkę TextBox do interfejsu użytkownika, aby wyświetlić bieżący stan aktywacji aplikacji. Zastąp domyślny element StackPanel w pliku MainPage.xaml następującym kodem.

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

Na koniec zaktualizuj konstruktor MainWindow , aby podjąć argument, który ustawi właściwość State podczas tworzenia okna.

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

    _state = state;
}

Rejestracja dla aktywacji URI

System uruchamia dostawców kluczy sprzętowych Microsoft Copilot przy użyciu aktywacji identyfikatora URI. Zarejestruj protokół uruchamiania, dodając element uap:Protocol do manifestu aplikacji. Aby uzyskać więcej informacji na temat rejestrowania jako domyślnego programu obsługi schematu identyfikatora URI, zobacz Handle URI activation (Obsługa aktywacji identyfikatora URI).

W poniższym przykładzie pokazano uap:Extension rejestrujący schemat 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>
  ...

rozszerzenie aplikacji klucza sprzętowego Microsoft Copilot

Aby zarejestrować się jako dostawca kluczy sprzętowych Microsoft Copilot, należy spakować aplikację. Aby uzyskać informacje na temat tworzenia pakietów aplikacji, zobacz Przegląd tożsamości pakietu w aplikacji Windows. Dostawcy kluczy sprzętowych Microsoft Copilot deklarują swoje informacje rejestracyjne w uap3:AppExtension. Atrybut Name rozszerzenia musi być ustawiony na "com.microsoft.windows.copilotkeyprovider". Aby zapewnić obsługę kluczowych zmian stanu, aplikacje muszą podać kilka dodatkowych wpisów do deklaracji uap3:AppExtension .

Wewnątrz elementu uap3:AppExtension dodaj element uap3:Properties z elementami podrzędnymi PressAndHoldStart i PressAndHoldStop. Zawartość tych elementów powinna być URI schematu protokołu zarejestrowanego w manifeście w poprzednim kroku. Argumenty ciągu zapytania określają, czy identyfikator URI jest uruchamiany, ponieważ użytkownik naciśnięto i przytrzymał skrót klawiszowy, czy też zwolnił skrót klawiszowy. Aplikacja używa tych wartości ciągu zapytania podczas aktywacji aplikacji, aby określić poprawną akcję do wykonania. Określenie elementu SingleTap jest opcjonalne, ale może być przydatne do określenia, czy aplikacja została uruchomiona z klucza sprzętowego 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> 
  ...

Zarządzanie aktywacją identyfikatora URI

Aby wykryć, czy aplikacja została aktywowana za pomocą identyfikatora URI, wywołaj metodę AppInstance.GetActivatedEventArgs i sprawdź, czy wartość właściwości AppActivationArguments.Kind to Protocol. Jeśli aplikacja została uruchomiona za pośrednictwem aktywacji protokołu, sprawdź, czy schemat identyfikatora URI jest taki sam jak nazwa protokołu określona w manifeście aplikacji. Jeśli wszystkie te testy kończą się pomyślnie, wiesz, że aplikacja została aktywowana przez użytkownika naciskającego klawisz sprzętowy Copilot. W tym momencie można przeanalizować ciąg zapytania identyfikatora URI i pobrać parametr stanu, który będzie miał wartości określone w elementach PressAndHoldStart i PressAndHoldStop w manifeście aplikacji.

// 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();
}

Ważne

Należy pamiętać, że domyślnie aplikacje WinUI są wieloinstancyjne, co oznacza, że nowe wystąpienie zostanie uruchomione za każdym razem, gdy klawisz Microsoft Copilot zostanie naciśnięty lub zwolniony. Może to być pożądane zachowanie wielu dostawców, ale jeśli woleliby, możesz zaktualizować aplikację, żeby korzystała z jednego wystąpienia. Aby uzyskać więcej informacji, zobacz Create a single-instanced WinUI app with C#(Tworzenie pojedynczej aplikacji WinUI za pomocą języka C#).

Obsługa wywołania szybkiej ścieżki

Oprócz aktywacji identyfikatora URI aplikacje mogą rejestrować się w celu obsługi szybkiej wywołania ścieżki, w której uruchomiona aplikacja odbiera komunikaty dotyczące aplikacji sprzętowej Copilot za pośrednictwem komunikatów okna. W przypadku aktualnie uruchomionej aplikacji ta metoda wywołania jest szybsza niż aktywacja URI i zapewni lepsze wrażenia użytkownika, ponieważ aplikacja może rozpocząć nasłuchiwanie mowy szybciej po przytrzymaniu klawisza.

Zaktualizuj plik manifestu aplikacji, aby obsługiwać wywołanie szybkiej ścieżki

Aby dodać obsługę szybkiego wywołania ścieżki, zaktualizuj rozszerzenie "com.microsoft.windows.copilotkeyprovider", dodając atrybut MessageWParam do elementów SingleTap, PressAndHoldStart i PressAndHoldStop. Każda wartość MessageWParam musi być unikatową 32-bitową liczbą całkowitą, ale używane wartości są wybierane przez aplikację. W tym przykładzie użyto odpowiednio wartości 0, 1 i 2. Te wartości będą używane w dalszej części przykładu, gdy są przekazywane w parametrze wParam komunikatu systemu Windows, w celu określenia bieżącego stanu wciśnięcia klawisza sprzętowego 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>

Dostęp do interfejsów API Win32 dla rejestracji okien

Umożliwia się aktywację szybkiej ścieżki przez ustawienie właściwości skojarzonej z jednym z okien aplikacji w magazynie IPropertyStore. To wymaga dostępu do niektórych natywnych API Win32. W tym przewodniku zostanie użyta biblioteka CsWin32, która automatyzuje generowanie powiązań języka C# i jest dostępna jako pakiet NuGet.

W Visual Studio w Solution Explorer kliknij prawym przyciskiem myszy plik project i wybierz pozycję Zarządzaj pakietami NuGet... . Na karcie Browse w package manager NuGet wyszukaj ciąg "cswin32" i wybierz pakiet "Microsoft.Windows.CsWin32" i kliknij pozycję *Install.

Po zainstalowaniu pakietu dodaj nowy plik tekstowy w katalogu project i nadaj mu nazwę "NativeMethods.txt". Narzędzie CsWin32 będzie szukać w tym pliku listy interfejsów API Win32, dla których wygeneruje powiązania. Umieść następujące nazwy interfejsów API w "NativeMethods.txt".

SUBCLASSPROC

SHGetPropertyStoreForWindow

IPropertyStore

SetWindowSubclass

DefSubclassProc

Rejestrowanie okna na potrzeby wywołania Microsoft Copilot fastpath

Następnie zaktualizujemy klasę MainWindow , aby zarejestrować okno w celu odbierania wywołań fastpath z klucza sprzętowego Copilot.

Najpierw wywołaj metodę GetWindowHandle , aby uzyskać dojście HWND do głównego systemu Windows. Wywołaj metodę SHGetPropertyStoreForWindow , aby pobrać element IPropertyStore dla okna. Utwórz nowy klucz PROPERTYKEY i ustaw człon fmtid na identyfikator GUID dla szybkiej aktywacji Windows Copilot. Ustaw wartość właściwości na wartość zdefiniowaną przez aplikację, która zostanie przekazana z powrotem do aplikacji z systemu po zmianie stanu klucza sprzętu. Wartość zdefiniowana przez aplikację to identyfikator komunikatu systemu Windows, który musi znajdować się w zakresie WM_APP. Aby uzyskać więcej informacji, zobacz WM_APP. Wywołaj metodę SetValue , a następnie wywołaj metodę Commit , aby zatwierdzić zmianę w magazynie właściwości.

Na koniec utwórz wywołanie zwrotne SUBCLASSPROC , które będzie wywoływane po zmianie stanu klucza sprzętu. WindowSubClass to implementacja wywołania zwrotnego, która zostanie wyświetlona w następnym kroku. Wywołaj metodę SetWindowSubclass , aby zarejestrować wywołanie zwrotne.

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);
    Microsoft.UI.Windowing.AppWindow appWindow = AppWindow;


    var propertyStoreGUID = new Guid("886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99");
    var hr = PInvoke.SHGetPropertyStoreForWindow((HWND)this.AppWindow.Id.Value, 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((HWND)appWindow.Id.Value, SubClassDelegate, 0, 0);

    _state = state;
}

Zaimplementować wywołanie zwrotne podklasy okna

Ostatnim krokiem w tym przykładzie jest zaimplementowanie wywołania zwrotnego podklasy okna, które będzie wywoływane za każdym razem, gdy aplikacja jest uruchomiona, a zmienia się stan klucza sprzętowego Windows Copilot. W tym przykładzie sprawdzamy, czy komunikat okna jest wartością WM_COPILOT, którą określiliśmy podczas ustawiania wartości magazynu właściwości w poprzednim kroku. Następnie sprawdzamy wartość argumentu wParam , aby zobaczyć, które wartości określone za pomocą atrybutów MessageWParam w manifeście aplikacji zostały przekazane. Właściwość SetState jest wywoływana w celu zaktualizowania interfejsu użytkownika przy użyciu bieżącego stanu.

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);

}

Podpisz dostawcę klucza sprzętowego Copilot systemu Windows

Aplikacje dostawcy muszą być podpisane, aby można je było włączyć jako element docelowy klucza sprzętowego Microsoft Copilot. Aby uzyskać informacje na temat pakowania i podpisywania aplikacji, zobacz Pakowanie aplikacji desktopowej lub aplikacji platformy UWP w Visual Studio.

  • Last updated on