從傳統型應用程式釘選次要磚

發行項
03/22/2025

桌面應用程式，例如使用 Windows App SDK 的 WinUI 3 應用程式，或是 Windows Presentation Foundation （WPF）或 Windows Forms （WinForms）應用程式，可以透過已打包的應用程式釘選次要磚（請參閱從程式代碼建置 MSIX 套件）。這以前稱為桌面橋接器。

次要磚的螢幕快照

重要

需要 Fall Creators Update：您必須目標 SDK 16299 並執行 16299 或更高版本的組建，才能從 Desktop Bridge 應用程式釘選次要磁貼。

從 Windows App SDK、WPF 或 WinForms 應用程式新增次要磚與純 UWP 應用程式非常類似。唯一的差異在於您必須指定主視窗控制代碼（HWND）。這是因為當您釘選磁磚時，Windows 會顯示一個模態對話框，請您確認是否要釘選該磁磚。如果桌面應用程式未設定擁有者視窗的 SecondaryTile 物件，則 Windows 不知道要在哪裡繪製對話窗口，作業將會失敗。

封裝您的應用程式

如果您要使用 WinUI 3 建立 Windows App SDK 應用程式，則必須使用已封裝的應用程式來釘選次要磚。如果您開始使用已封裝的應用程式範本，則不需要額外的步驟來封裝您的應用程式。

如果您使用 WPF 或 WinForms，且尚未使用桌面橋封裝應用程式，則在使用 Windows 執行階段 API 之前，您需先進行封裝（請參閱從程式碼建置 MSIX 套件）。

使用 IInitializeWithWindow 介面初始化和釘選次要磚

注意

本節適用於 WinUI 3，並且適用於 .NET 6 或更新版本的 WPF/WinForms。

在專案檔中，將 TargetFramework 屬性設定為可讓您存取 Windows 運行時間 API 的值（請參閱 .NET 6 和更新版本：使用目標框架暱稱選項）。這包括存取 WinRT.Interop 命名空間（請參閱從 .NET 應用程式呼叫 Interop API）。例如：
```
<PropertyGroup>
  
  <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
</PropertyGroup>
```

初始化新的次要磚物件，就像使用一般 UWP 應用程式一樣。若要深入瞭解如何建立和釘選次要磚，請參閱釘選次要磚。

// Initialize the tile with required arguments
var tile = new Windows.UI.StartScreen.SecondaryTile(
    "myTileId5391",
    "Display name",
    "myActivationArgs",
    new Uri("ms-appx:///Assets/Square150x150Logo.png"),
    TileSize.Default);

擷取視窗句柄，並使用該句柄初始化次要磚物件。在下列程式代碼中，this 是 Window 對象的參考（無論是 WinUI 3 視窗、WPF 視窗還是 WinForms 視窗）。如需詳細資訊，請參閱擷取視窗句柄（HWND）和顯示相依於 CoreWindow的 WinRT UI 物件。
```
var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
WinRT.Interop.InitializeWithWindow.Initialize(tile, hWnd);
```

最後，請像在一般 UWP 應用程式中一樣，要求釘選磁貼。

// Pin the tile
bool isPinned = await tile.RequestCreateAsync();

// Here, update UI to reflect whether user can now either unpin or pin

注意

適用於 .NET 版本早於 5 的 WPF/WinForms。

使用 ComImport 和 Guid 屬性來宣告 IInitializeWithWindow 介面。

[System.Runtime.InteropServices.ComImport]
[System.Runtime.InteropServices.Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
[System.Runtime.InteropServices.InterfaceType(
    System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown
)]
public interface IInitializeWithWindow
{
    void Initialize(IntPtr hWnd);
}

初始化新的次要磚物件，就像使用一般 UWP 應用程式一樣。若要深入瞭解如何建立和釘選次要磚，請參閱釘選次要磚。

// Initialize the tile with required arguments
var tile = new Windows.UI.StartScreen.SecondaryTile(
    "myTileId5391",
    "Display name",
    "myActivationArgs",
    new Uri("ms-appx:///Assets/Square150x150Logo.png"),
    TileSize.Default);

擷取視窗句柄，並使用該句柄初始化次要磚物件。如需詳細資訊，請參閱擷取視窗句柄（HWND）和顯示相依於 CoreWindow的 WinRT UI 物件。

var wih = new System.Windows.Interop.WindowInteropHelper(this);
var hWnd = wih.Handle; // For a WinForms window object, access the NativeWindow.Handle property instead.
IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)tile;
initWindow.Initialize(hWnd);

最後，請求將磚釘選，就像您在一般 UWP 應用程式中所做的那樣。

// Pin the tile
bool isPinned = await tile.RequestCreateAsync();

// Here, update UI to reflect whether user can now either unpin or pin

將下列內容新增至您的 pch.h 檔案。 shobjidl.h 提供 IInitializeWithWindow 介面的存取權;Microsoft.UI.Xaml.Window.h 提供 WinUI 3 Window 類別的存取權。
```
#include <shobjidl.h>
#include <winrt/Windows.Foundation.h> 
#include <winrt/Windows.UI.StartScreen.h>
#include <Microsoft.UI.Xaml.Window.h>
```

初始化新的次要磚物件，就像使用一般 UWP 應用程式一樣。若要深入瞭解如何建立和釘選次要磚，請參閱釘選次要磚。

auto tile = Windows::UI::StartScreen::SecondaryTile(
        L"myTileId5391",
        L"Display name",
        L"myActivationArgs",
        Windows::Foundation::Uri(L"ms-appx:///Assets/Square150x150Logo.png"),
        Windows::UI::StartScreen::TileSize::Default);

取得視窗控制代碼，並使用該控制代碼初始化次要圖塊物件。在下列程式代碼中，this 是 WinUI 3 Window 物件的指標。如需詳細資訊，請參閱擷取視窗句柄（HWND）和顯示相依於 CoreWindow的 WinRT UI 物件。
```
auto windowNative{ this->m_inner.as<::IWindowNative>() };
HWND hWnd{ 0 };
windowNative->get_WindowHandle(&hWnd);

tile.as<IInitializeWithWindow>()->Initialize(hWnd);
```

最後，請求像在一般 UWP 應用程式中一樣釘選磚塊。

// Pin the tile
bool isPinned = co_await tile.RequestCreateAsync();

// Here, update UI to reflect whether user can now either unpin or pin

傳送磁磚通知

重要

需要 2018 年 4 月版本 17134.81 或更新版本：您必須執行組建 17134.81 或更新版本，才能從桌面橋接應用程式將磁磚或徽章通知傳送至次要磁磚。在此 .81 服務更新之前，從桌面橋接應用程式將磚或徽章通知傳送至次要磚時，會發生0x80070490 元素找不到 例外狀況。

傳送磚或徽章通知與UWP應用程式相同。請參閱傳送本機磚通知以開始進行。

共用方式為

從傳統型應用程式釘選次要磚

封裝您的應用程式

使用 IInitializeWithWindow 介面初始化和釘選次要磚

傳送磁磚通知

資源

其他資源