アプリケーションにマイ連絡先のサポートを追加する

[アーティクル]
02/01/2024

重要

マイ連絡先は、KB5034203 が適用された Windows 11 および Windows 10 バージョンではサポートされなくなりました。

Note

Windows 10 May 2019 Update (バージョン 1903) 以降の新規の Windows 10 のインストールでは、既定で "タスクバーに連絡先" が表示されません。タスクバーを右クリックし、[タスクバーに連絡先を表示する] を押すと、この機能を有効にできます。開発者がアプリケーションにマイ連絡先のサポートを追加することは推奨されません。Windows 10 用にアプリを最適化する方法の詳細については、Windows 開発者のブログに関するページを参照してください。

マイ連絡先機能を使用すると、ユーザーは連絡先をアプリケーションからタスクバーに直接ピン留めできるようになり、さまざまな方法で操作できる新しい連絡先オブジェクトを作成できます。この記事では、この機能のサポートを追加して、ユーザーがアプリから直接、連絡先をピン留めできるようにする方法について説明します。連絡先をピン留めすると、マイ連絡先の共有や通知など、ユーザーは新しい種類の操作を利用できるようになります。

ユーザーチャット

要件

Windows 10 と Microsoft Visual Studio 2019。インストールの詳細については、「Visual Studio のセットアップ」を参照してください。
C# またはこれに類似するオブジェクト指向プログラミング言語に関する基本的な知識。 C# で作業を開始するには、「"Hello, world" アプリを作成する」を参照してください。

概要

アプリケーションでマイ連絡先機能を使用できるようにするには、次の 3 つの手順を実行する必要があります。

アプリケーションマニフェストで shareTarget アクティブ化コントラクトのサポートを宣言します。
アプリを使用してユーザーが共有できる連絡先に注釈を付けます。
アプリケーションの複数のインスタンスの同時実行をサポートします。ユーザーは、アプリケーションの完全バージョンを連絡先パネルで使用しながら、そのアプリケーションを操作できる必要があります。また、複数の連絡先パネルで同時に使用できる必要もあります。この動作をサポートするために、アプリケーションは複数のビューを同時に実行できる必要があります。そのための方法については、「アプリの複数のビューの表示」記事を参照してください。

これらの手順が完了すると、アプリケーションが注釈付きの連絡先の連絡先パネルに表示されます。

コントラクトのサポートを宣言する

マイ連絡先コントラクトのサポートを宣言するには、Visual Studio でアプリケーションを開きます。 ソリューションエクスプローラーで、Package.appxmanifest を右クリックし、[ファイルを開くアプリケーションの選択] を選択します。メニューから [XML (テキスト) エディター] を選択し、[OK] をクリックします。マニフェストを次のように変更します。

前

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	    </Application>
	</Applications>

後

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	      <Extensions>
	        <uap4:Extension Category="windows.contactPanel" />
	      </Extensions>
	    </Application>
	</Applications>

この追加により、アプリケーションを windows.ContactPanel コントラクトから起動できるようになり、連絡先パネルで操作できるようになります。

連絡先に注釈を付ける

アプリケーションの連絡先が [マイ連絡先] ウィンドウ経由でタスクバーに表示されるようにするには、連絡先を Windows 連絡先ストアに書き込む必要があります。連絡先を書き込む方法については、「連絡先カードのサンプル」を参照してください。

アプリケーションで、各連絡先に注釈を書き込む必要もあります。注釈は、アプリケーションからのデータの一部であり、連絡先に関連付けられます。注釈では、目的のビューに対応するアクティブ化可能なクラスを ProviderProperties メンバーに含め、ContactProfile 操作のサポートを宣言する必要があります。

アプリの実行中はいつでも連絡先に注釈を付けることができますが、一般的には、連絡先が Windows 連絡先ストアに追加されたらすぐに注釈を付けることをお勧めします。

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
	// Create a new contact annotation
	ContactAnnotation annotation = new ContactAnnotation();
	annotation.ContactId = myContact.Id;

	// Add appId and contact panel support to the annotation
	String appId = "MyApp_vqvv5s4y3scbg!App";
	annotation.ProviderProperties.Add("ContactPanelAppID", appId);
	annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

	// Save annotation to contact annotation list
	// Windows.ApplicationModel.Contacts.ContactAnnotationList 
	await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

「appId」はパッケージファミリ名の後に、「!」とアクティブ化可能なクラス ID を付けたものです。パッケージファミリ名を見つけるには、既定のエディターを使用して Package.appxmanifest を開き、[パッケージ化] タブを確認します。ここで、「App」はアプリケーション起動ビューに対応するアクティブ化可能なクラスです。

連絡先に新しい連絡先候補ユーザーの招待を許可する

既定では、アプリケーションは、特別に注釈を付けた連絡先の連絡先パネルにのみ表示されます。これは、アプリから操作ができない連絡先との混同を避けるためです。アプリケーションが認識していない連絡先にもアプリケーションが表示されるようにする場合 (ユーザーを招待してその連絡先を各自のアカウントに追加してもらうためなど)、マニフェストに次の内容を追加できます。

前

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
    	<uap4:Extension Category="windows.contactPanel" />
	  </Extensions>
	</Application>
</Applications>

後

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
		<uap4:Extension Category="windows.contactPanel">
	    	<uap4:ContactPanel SupportsUnknownContacts="true" />
		</uap4:Extension>
	  </Extensions>
	</Application>
</Applications>

この変更により、アプリケーションは、ユーザーがピン留めしたすべての連絡先の連絡先パネルに、利用可能なオプションとして表示されるようになります。連絡先パネルコントラクトを使用してアプリケーションがアクティブ化されるとき、その連絡先をアプリケーションが認識しているかどうかを確認する必要があります。認識していない場合は、その連絡先にアプリの新しいユーザーエクスペリエンスを表示する必要があります。

マイ連絡先の連絡先パネル

Email アプリのサポート

Email アプリを作成する場合は、すべての連絡先に手動で注釈を付ける必要はありません。連絡先ウィンドウと mailto: プロトコルのサポートを宣言すると、メールアドレスを持つユーザーにアプリケーションが自動的に表示されます。

連絡先パネルで実行する

アプリケーションが一部またはすべてのユーザーの連絡先パネルに表示されるようになったところで、連絡先パネルコントラクトでのアクティブ化を処理する必要があります。

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

このコントラクトでアプリケーションがアクティブ化されると、ContactPanelActivatedEventArgs オブジェクトが渡されます。これには、アプリケーションが起動時に操作を試みる連絡先の ID と、ContactPanel オブジェクトが含まれています。この ContactPanel オブジェクトへの参照を保持する必要があります。これにより、パネルを操作できるようになります。

ContactPanel オブジェクトには、アプリケーションがリッスンする必要がある 2 つのイベントがあります。

LaunchFullAppRequested イベントが送信されるのは、ユーザーがアプリケーションの起動を要求する UI 要素を呼び出したときです。アプリケーションは、必要なコンテキストをすべて渡して、自らを起動します。これを行う方法は自由です (プロトコルの起動を通じてなど)。
Closing イベントは、アプリケーションが閉じられるときに送信されて、コンテキストをすべて保存できます。

ContactPanel オブジェクトでは、連絡先パネルのヘッダーの背景色を設定したり、プログラムによって連絡先パネルを閉じたりすることもできます。

通知バッジのサポート

タスクバーにピン留めした連絡先に、アプリからその人に関連する新しい通知が届いたときにバッジが表示されるようにする場合は、トースト通知と表現力豊かなマイ連絡先の通知に hint-people パラメーターを含める必要があります。

ユーザー通知の不正使用

連絡先にバッジを表示するには、最上位のトーストノードに、送信元連絡先または関連連絡先を指定する hint-people パラメーターを含める必要があります。このパラメーターには、次のいずれかの値を指定できます。

メールアドレス
- 例: johndoe@mydomain.com
電話番号
- 例: 888-888-8888
リモート ID
- 例: remoteid: 1234

トースト通知が特定の人に関連していることを識別する方法の例を次に示します。

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

Note

ContactStore API を利用するアプリで、StoredContact.RemoteId プロパティを使用して、PC に保存されている連絡先とリモートに保存されている連絡先とを関連付ける場合は、RemoteId プロパティの値が一定かつ一意であることが重要です。つまり、リモート ID は単一のユーザーアカウントを一貫して識別する必要があり、PC 上の他の連絡先 (他のアプリが所有する連絡先を含む) のリモート ID と競合しないように一意のタグを含む必要があります。アプリで使用されるリモート ID が一定かつ一意でない場合は、リモート ID をシステムに追加する前に、このトピックで後で示す RemoteIdHelper クラスを使用して、どのリモート ID にも一意のタグを追加できます。または、RemoteId プロパティをまったく使用しないで、代わりに連絡先のリモート ID を保存するカスタム拡張プロパティを作成することもできます。

PinnedContactManager クラス

PinnedContactManager は、タスクバーにピン留めされた連絡先を管理するために使用します。このクラスを使用すると、連絡先をピン留め/ピン留め解除したり、連絡先がピン留めされているかどうかを判別したり、アプリケーションが現在実行しているシステムで特定のサーフェスへのピン留めがサポートされているかどうかを判別したりできます。

GetDefault メソッドを使用して PinnedContactManager オブジェクトを取得できます。

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

連絡先をピン留め/ピン留め解除する

作成した PinnedContactManager を使用して、連絡先をピン留めしたりピン留め解除したりできるようになりました。 RequestPinContactAsync および RequestUnpinContactAsync メソッドは、ユーザーに確認ダイアログを表示するため、アプリケーションシングルスレッドアパートメント (ASTA、つまり UI) スレッドから呼び出す必要があります。

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

同時に複数の連絡先をピン留めすることもできます。

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

Note

現在、連絡先をピン留め解除するバッチ操作はありません。

注:

次の方法で共有

アプリケーションにマイ連絡先のサポートを追加する

要件

概要

コントラクトのサポートを宣言する

連絡先に注釈を付ける

連絡先に新しい連絡先候補ユーザーの招待を許可する

Email アプリのサポート

連絡先パネルで実行する

通知バッジのサポート

PinnedContactManager クラス

連絡先をピン留め/ピン留め解除する

関連項目

フィードバック

その他のリソース