diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json new file mode 100644 index 000000000..62d981484 --- /dev/null +++ b/.openpublishing.redirection.json @@ -0,0 +1,29 @@ +{ + "redirections": [ + { + "source_path": "archive/graph/providers/InteractiveProviderBehavior.md", + "redirect_url": "/graph/providers/interactiveproviderbehavior", + "redirect_document_id": true + }, + { + "source_path": "archive/graph/providers/MockProviderBehavior.md", + "redirect_url": "/graph/providers/mockproviderbehavior", + "redirect_document_id": true + }, + { + "source_path": "graph/authentication/msal.md", + "redirect_url": "/graph/authentication/msalprovider", + "redirect_document_id": true + }, + { + "source_path": "graph/authentication/windows.md", + "redirect_url": "/graph/authentication/windowsprovider", + "redirect_document_id": true + }, + { + "source_path": "graph/authentication/custom.md", + "redirect_url": "/graph/authentication/iprovider", + "redirect_document_id": true + } + ] +} \ No newline at end of file diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md index 537527b59..9b65b8762 100644 --- a/docs/Getting-Started.md +++ b/docs/Getting-Started.md @@ -14,7 +14,7 @@ The toolkit is available as NuGet packages that can be added to any existing or > [!NOTE] > Visual Studio 2015 is not supported with the Windows Community Toolkit 2.0 or higher -2. Open an existing project, or create a new project using the Blank App template under Visual C# -> Windows -> Universal. **Important**: Build 16299 or higher is supported by current version of the Toolkit. +2. Open an existing project, or create a new project using the Blank App template under Visual C# -> Windows -> Universal. **Important**: Version 1809 (Build 17763) or higher is supported by current version of the Toolkit. 3. In Solution Explorer panel, right click on your project name and select **Manage NuGet Packages**. Search for **Microsoft.Toolkit.UWP**, and choose your desired [NuGet Packages](Nuget-Packages.md) from the list. diff --git a/docs/graph/providers/InteractiveProviderBehavior.md b/docs/archive/graph/providers/InteractiveProviderBehavior.md similarity index 97% rename from docs/graph/providers/InteractiveProviderBehavior.md rename to docs/archive/graph/providers/InteractiveProviderBehavior.md index dfa6507e5..e607af663 100644 --- a/docs/graph/providers/InteractiveProviderBehavior.md +++ b/docs/archive/graph/providers/InteractiveProviderBehavior.md @@ -10,7 +10,7 @@ dev_langs: # InteractiveProviderBehavior XAML Behavior > [!WARNING] -> This API has been removed. For the latest guidance on using the Microsoft Graph in the Toolkit check out the [Windows Community Toolkit - Graph Helpers and Controls](../overview.md). +> This API has been removed. For the latest guidance on using the Microsoft Graph in the Toolkit check out the [Windows Community Toolkit - Graph Helpers and Controls](../../../graph/overview.md). The [InteractiveProviderBehavior](/dotnet/api/microsoft.toolkit.graph.providers.interactiveproviderbehavior) provides a quick and easy way to connect to the Microsoft Identity platform and Microsoft Graph. It is built on top of the Graph SDK's authentication providers, but allows usage from XAML. diff --git a/docs/graph/providers/MockProviderBehavior.md b/docs/archive/graph/providers/MockProviderBehavior.md similarity index 95% rename from docs/graph/providers/MockProviderBehavior.md rename to docs/archive/graph/providers/MockProviderBehavior.md index 4b64a3454..de06b7dcd 100644 --- a/docs/graph/providers/MockProviderBehavior.md +++ b/docs/archive/graph/providers/MockProviderBehavior.md @@ -10,7 +10,7 @@ dev_langs: # MockProviderBehavior XAML Behavior > [!WARNING] -> This API has been removed. For the latest guidance on using the Microsoft Graph in the Toolkit check out the [Windows Community Toolkit - Graph Helpers and Controls](../overview.md). +> This API has been removed. For the latest guidance on using the Microsoft Graph in the Toolkit check out the [Windows Community Toolkit - Graph Helpers and Controls](../../../graph/overview.md). The [MockProviderBehavior](/dotnet/api/microsoft.toolkit.graph.providers.mockproviderbehavior) provides sample data from the Microsoft Graph for demonstration and learning purposes only. diff --git a/docs/docfx.json b/docs/docfx.json index 4fbcbae9a..a89596106 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -43,6 +43,7 @@ "uhfHeaderId": "MSDocsHeader-UWP-Community", "ms.topic": "article", "ms.prod": "community-toolkit", + "products": ["https://authoring-docs-microsoft.poolparty.biz/devrel/bcbcbad5-4208-4783-8035-8481272c98b8"], "keywords": "windows uwp community toolkit", "author": "michael-hawker", "ms.author": "mhawker", diff --git a/docs/extensions/OnDeviceExtension.md b/docs/extensions/OnDeviceExtension.md index 6aae939d9..6a228546f 100644 --- a/docs/extensions/OnDeviceExtension.md +++ b/docs/extensions/OnDeviceExtension.md @@ -19,7 +19,3 @@ Here is how the property can be used in XAML: Text="{ui:OnDevice Default=Hi, Desktop=Hello, Xbox=World}"/> ``` - -## Examples - -You can find more examples in the [unit tests](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.0.0/UnitTests). diff --git a/docs/graph/authentication/MsalProvider.md b/docs/graph/authentication/MsalProvider.md deleted file mode 100644 index 2ff9e25a7..000000000 --- a/docs/graph/authentication/MsalProvider.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: MsalProvider -author: shweaver-MSFT -description: Authentication provider based on the official Microsoft Authentication Library (MSAL). -keywords: uwp, wpf, netstandard, windows, community, toolkit, graph, login, authentication, provider, providers, identity, msal -dev_langs: - - csharp ---- - -# MsalProvider - -The MsalProvider is an [IProvider](./IProvider.md) implementation built on the official Microsoft Authentication Library (MSAL). It is NetStandard 2.0 so it works in both UWP and WPF apps. - -> Available in the `CommunityToolkit.Authentication.Msal` package. - -> [!IMPORTANT] -> Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). - -```csharp -using CommunityToolkit.Authentication; - -string clientId = "YOUR-CLIENT-ID-HERE"; -string[] scopes = new string[] { "User.Read" }; - -ProviderManager.Instance.GlobalProvider = new MsalProvider(clientId, scopes); -``` - -## Prerequisite Configure Client Id in Partner Center - -If your product integrates with Azure AD and calls APIs that request either application permissions or delegated permissions that require administrator consent, you will also need to enter your Azure AD Client ID in Partner Center: - -`https://partner.microsoft.com/dashboard/products/<YOUR-APP-ID>/administrator-consent` - -This lets administrators who acquire the app for their organization grant consent for your product to act on behalf of all users in the tenant. - -> [!NOTE] -> You only need to specify the client id if you need admin consent for delegated permissions from your AAD app registration. Simple authentication for public accounts does not require a client id or any additional configuration. - -> [!IMPORTANT] -> Be sure to Register Client Id in Azure first following the guidance here: [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app) -> -> After finishing the initial registration page, you will also need to add an additional redirect URI. Click on "Add a Redirect URI" and add the value retrieved from running `WindowsProvider.RedirectUri`. -> -> You'll also want to set the toggle to true for "Allow public client flows". -> -> Then click "Save". - -## Properties - -| Property | Type | Description | -| -- | -- | -- | -| State | [ProviderState](./IProvider.md) | Gets the current authentication state of the provider. | - -## Events - -| Event | Type | Description | -| -- | -- | -- | -| StateChanged | EventHandler<[ProviderStateChangedEventArgs](./IProvider.md)> | Event called when the provider state changes. | - -## Methods - -| Method | Arguments | Returns | Description | -| -- | -- | -- | -- | -| GetTokenAsync | bool silentOnly = true | Task<string> | Retrieve a token for the authenticated user. | -| AuthenticateRequestAsync | HttpRequestMessage | Task | Authenticate an outgoing request. | -| SignInAsync | | Task | Sign in a user. | -| SignOutAsync | | Task | Sign out the current user. | -| TrySilentSignInAsync | | Task<bool> | Try signing in silently, without prompts. | diff --git a/docs/graph/authentication/ProviderManager.md b/docs/graph/authentication/ProviderManager.md index e675f8696..34ea2f7ad 100644 --- a/docs/graph/authentication/ProviderManager.md +++ b/docs/graph/authentication/ProviderManager.md @@ -9,42 +9,13 @@ dev_langs: # ProviderManager -The ProviderManager manages access to the globally configured [IProvider](./IProvider.md) instance and any state change events as users sign in and out. +The ProviderManager manages access to the globally configured [IProvider](./custom.md) instance and any state change events as users sign in and out. > Available in the `CommunityToolkit.Authentication` package. > [!IMPORTANT] > Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). -## Set the GlobalProvider - -```csharp -using CommunityToolkit.Authentication; - -ProviderManager.Instance.GlobalProvider = new WindowsProvider(); -``` - -## Listen for changes to the GlobalProvider - -```csharp -using CommunityToolkit.Authentication; - -ProviderManager.Instance.ProviderUpdated += OnProviderUpdated; - -void OnProviderUpdated(object sender, ProviderUpdatedEventArgs e) -{ - if (e.Reason == ProviderManagerChangedState.ProviderUpdated) - { - // The GlobalProvider has been set. - } - - if (e.Reason == ProviderManagerChangedState.ProviderStateChanged) - { - // The GlobalProvider state has changed. - } -} -``` - ## Properties | Property | Type | Description | @@ -55,27 +26,20 @@ void OnProviderUpdated(object sender, ProviderUpdatedEventArgs e) | Event | Type | Description | | -- | -- | -- | -| ProviderUpdated | EventHandler<ProviderUpdatedEventArgs> | Event called when the IProvider changes. | - -## Methods - -| Method | Arguments | Returns | Description | -| -- | -- | -- | -- | -| AuthenticateRequestAsync | HttpRequestMessage | Task | Authenticate an outgoing request. | -| GetTokenAsync | bool silentOnly = true | Task<string> | Retrieve a token for the authenticated user. | -| SignInAsync | | Task | Sign in a user. | -| SignOutAsync | | Task | Sign out the current user. | -| TrySilentSignInAsync | | Task<bool> | Try signing in silently, without prompts. | +| ProviderUpdated | EventHandler<IProvider> | Event called when the IProvider changes. | +| ProviderStateChanged | EventHandler<ProviderStateChangedEventArgs> | Event called when the IProvider changes. | -## ProviderUpdatedEventArgs Object +## ProviderStateChangedEventArgs Object | Property | Type | Description | | -- | -- | -- | -| Reason | ProviderManagerChangedState | Gets the reason for the provider update. | +| OldState | ProviderState | Gets the previous state of the IProvider. +| NewState | ProviderState | Gets the new state of the IProvider. -## ProviderManagerChangedState Enum +## ProviderState Enum | Name | Description | | -- | -- | -| ProviderStateChanged | The [IProvider](./IProvider.md) state has changed.| -| ProviderUpdated | The [IProvider](./IProvider.md) itself has changed. | +| Loading | The user's status is not known. | +| SignedOut | The user is signed-out. | +| SignedIn | The user is signed-in. | diff --git a/docs/graph/authentication/IProvider.md b/docs/graph/authentication/custom.md similarity index 58% rename from docs/graph/authentication/IProvider.md rename to docs/graph/authentication/custom.md index d13397837..8321aeb21 100644 --- a/docs/graph/authentication/IProvider.md +++ b/docs/graph/authentication/custom.md @@ -7,9 +7,13 @@ dev_langs: - csharp --- -# IProvider +# Custom provider -The IProvider is the base interface for creating authentication providers that work with the various controls and helpers in the toolkit. +If you have existing authentication code in your application, you can create a custom provider to enable authentication and access to Microsoft Graph for the toolkit's Graph based controls and helpers. To bring your own authentication provider logic, start by extending `IProvider`. + +## IProvider + +`IProvider` is the base interface for creating authentication providers that work with the various controls and helpers in the toolkit. Handle authenticaiton with one of our premade `IProvider` implementations or create your own. > Available in the `CommunityToolkit.Authentication` package. @@ -19,47 +23,31 @@ The IProvider is the base interface for creating authentication providers that w ```csharp using CommunityToolkit.Authentication; -IProvider provider = ProviderManager.Instance.GlobalProvider; +// Create an instance of your custom IProvider implementation. +IProvider customProvider = new CustomProvider(); -if (provider?.State == ProviderState.SignedIn) -{ - // You are now signed in and can request access tokens. -} +// Set the global provider using the custom instance. +ProviderManager.Instance.GlobalProvider = customProvider; ``` -## Properties +### Properties | Property | Type | Description | | -- | -- | -- | | State | ProviderState | Gets the current authentication state of the provider. | -## Events +### Events | Event | Type | Description | | -- | -- | -- | | StateChanged | EventHandler<ProviderStateChangedEventArgs> | An event that is called whenever the login state changes. -## Methods +### Methods | Method | Arguments | Returns | Description | | -- | -- | -- | -- | | AuthenticateRequestAsync | HttpRequestMessage | Task | Authenticate an outgoing request. | -| GetTokenAsync | bool silentOnly = true | Task<string> | Retrieve a token for the authenticated user. | +| GetTokenAsync | bool silentOnly = false, string[] scopes = null | Task<string> | Retrieve a token for the authenticated user. | | SignInAsync | | Task | Sign in a user. | | SignOutAsync | | Task | Sign out the current user. | | TrySilentSignInAsync | | Task<bool> | Try signing in silently, without prompts. | - -## ProviderStateChangedEventArgs Object - -| Property | Type | Description | -| -- | -- | -- | -| OldState | ProviderState | Gets the previous state of the IProvider. -| NewState | ProviderState | Gets the new state of the IProvider. - -## ProviderState Enum - -| Name | Description | -| -- | -- | -| Loading | The user's status is not known. | -| SignedOut | The user is signed-out. | -| SignedIn | The user is signed-in. | diff --git a/docs/graph/authentication/msal.md b/docs/graph/authentication/msal.md new file mode 100644 index 000000000..2a6b7e2ba --- /dev/null +++ b/docs/graph/authentication/msal.md @@ -0,0 +1,64 @@ +--- +title: MsalProvider +author: shweaver-MSFT +description: Authentication provider based on the official Microsoft Authentication Library (MSAL). +keywords: uwp, wpf, netstandard, windows, community, toolkit, graph, login, authentication, provider, providers, identity, msal +dev_langs: + - csharp +--- + +# MsalProvider + +The MsalProvider is an [IProvider](./custom.md) implementation built on the official Microsoft Authentication Library (MSAL). It is NetStandard 2.0 so it works in both UWP and WPF apps. + +> Available in the `CommunityToolkit.Authentication.Msal` package. + +> [!IMPORTANT] +> Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). + +```csharp +using CommunityToolkit.Authentication; + +string clientId = "YOUR-CLIENT-ID-HERE"; +string[] scopes = new string[] { "User.Read" }; + +ProviderManager.Instance.GlobalProvider = new MsalProvider(clientId, scopes); +``` + +## Prerequisite Configure Client Id in Partner Center + +> [!IMPORTANT] +> To obtain a Client Id, first register your app in Azure following the guidance here: [Quickstart: Register an application with the Microsoft identity platform](/azure/active-directory/develop/quickstart-register-app) +> +> After finishing the initial registration, you will also need to add an additional redirect URI. Click on "Authentication -> Add a Platform", select "Mobile and desktop applications", and check the "https://login.microsoftonline.com/common/oauth2/nativeclient" checkbox on that page. Then click "Configure". + +## Constructor + +| Parameter | Type | Default | Description | +| -- | -- | -- | -- | +| clientId | string | | Registered client id. | +| scopes | string[] | null | Listof scopes to initially request. | +| redirectUri | string | `https://login.microsoftonline.com/common/oauth2/nativeclient` | Redirect URI for authentication response. | +| autoSignIn | bool | true | Determines whether the provider attempts to silently log in upon instantiation. | + +## Properties + +| Property | Type | Description | +| -- | -- | -- | +| State | ProviderState | Gets the current authentication state of the provider. | + +## Events + +| Event | Type | Description | +| -- | -- | -- | +| StateChanged | EventHandler<ProviderStateChangedEventArgs> | Event called when the provider state changes. | + +## Methods + +| Method | Arguments | Returns | Description | +| -- | -- | -- | -- | +| GetTokenAsync | bool silentOnly = false, string[] scopes = null | Task<string> | Retrieve a token for the authenticated user. | +| AuthenticateRequestAsync | HttpRequestMessage | Task | Authenticate an outgoing request. | +| SignInAsync | | Task | Sign in a user. | +| SignOutAsync | | Task | Sign out the current user. | +| TrySilentSignInAsync | | Task<bool> | Try signing in silently, without prompts. | diff --git a/docs/graph/authentication/overview.md b/docs/graph/authentication/overview.md index 8cea22433..fdd09cf86 100644 --- a/docs/graph/authentication/overview.md +++ b/docs/graph/authentication/overview.md @@ -9,67 +9,118 @@ dev_langs: # Authentication Providers Overview -Authentication is always the first step to working with Microsoft Graph. -The toolkit offers a lightweight system for authenticating users, managing access tokens, and making Graph calls. - > [!IMPORTANT] > Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). -## ProviderManager and the GlobalProvider +Authentication is always the first step to working with Microsoft Graph. The toolkit providers enable your application to authenticate with Microsoft Identity and access Microsoft Graph in only few lines of code. Each provider handles user authentication and acquiring access tokens to call Microsoft Graph APIs, so that you don't have to write this code yourself. + +You can use the providers on their own, without components, to quickly implement authentication for your app and make calls to Microsoft Graph via the Microsoft Graph .NET SDK. + +The providers are required when using the Microsoft Graph Toolkit helpers and controls so they can access Microsoft Graph APIs. If you already have your own authentication and want to use the helpers and controls, you can use a [custom provider](./custom.md) instead. + +The toolkit includes the following providers: -The [ProviderManager](./ProviderManager.md) is the singleton that stores the globally accessible [IProvider](./IProvider.md) implementation and signals events in response to authentication state changes. -Set the `GlobalProvider` property at app startup and any other Graph based code will respond to any changes as users login and logout. +| Providers | Description | +| -- | -- | +| [Msal](./msal.md) | Uses MSAL for .NET to sign in users and acquire tokens to use with Microsoft Graph in a NetStandard 2.0 application. | +| [Windows](./windows.md) | Uses native WebAccountManager (WAM) APIs to sign in users and acquire tokens to use with Microsoft Graph in a UWP application. | +| [Custom](./custom.md)Custom | Create a custom provider to enable authentication and access to Microsoft Graph with your application's existing authentication code. | + +## Initializing the GlobalProvider + +To use an authentication provider in your app, you need to set it as the global provider. The [ProviderManager](./ProviderManager.md) is the singleton that stores the globally accessible [IProvider](./custom.md) implementation and signals events in response to authentication state changes. +Set the `GlobalProvider` property at app startup and any other Graph based code will respond to any changes as users sign in and out. ```csharp using CommunityToolkit.Authentication; // Set the GlobalProvider to an IProvider implementation. -ProviderManager.Instance.GlobalProvider = new WindowsPRovider(); +ProviderManager.Instance.GlobalProvider = new WindowsProvider(); ``` -Invoke the ProviderManager anywhere you need to make Graph calls. -Listen for State changes on the GlobalProvider using the `ProviderChanged` event. +### Permission scopes + +We recommend adding all the permission scopes your application may need when initializing your provider. This is optional, but will improve your user experience by presenting a single consent screen to the user with an aggregated list of permissions requested by all components in your app, rather than presenting separate prompts per scope as requested by the helpers and controls. The following example shows how to do this with the WindowsProvider. ```csharp + using CommunityToolkit.Authentication; -ProviderManager.Instance.GlobalProvider.ProviderChanged += OnProviderChanged; +string[] scopes = new string[] { "User.Read", "People.Read" }; -void OnProviderChanged (object sender, ProviderUpdatedEventArgs args) +ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes); +``` + +### ProviderState + +The providers keeps track of the user's authentication state and communicate it outwards. For example, when a user successfully signs in, the `ProviderState` is updated to `SignedIn`, signaling to the application that it is now able to make calls to Microsoft Graph. + +```csharp +public enum ProviderState { - // Check the State property of the GlobalProvider to determine if a user is signed in or not. - if (ProviderManager.Instance.GlobalProvider?.State == ProviderState.SignedIn) - { - // Signed in. - // You can now make Graph calls. - } - else - { - // Signed out or loading. - // Graph calls will fail. - } + // The user's status is not known. + Loading, + + // The user is signed-out. + SignedOut, + + // The user is signed-in. + SignedIn, } ``` -### MsalProvider +In some scenarios, you will want to show certain functionality or perform an action only after a user has successfully signed in. You can access and check the provider state as shown in the following example: + +```csharp +using CommunityToolkit.Authentication; + +if (ProviderManager.Instance.GlobalProvider?.State === ProviderState.SignedIn) { + // your code here +} +``` + +You can also use the `ProviderUpdated` and `ProviderStateChanged` events to get notified whenever provider is set or changes state. + +```csharp +using CommunityToolkit.Authentication; + +ProviderManager.Instance.ProviderUpdated += OnProviderUpdated; +ProviderManager.Instance.ProviderStateChanged += OnProviderStateChanged; + +void OnProviderUpdated(object sender, IProvider provider) +{ + // The global provider has been set. +} + +void OnProviderStateChanged(object sender, ProviderUpdatedEventArgs args) +{ + // The state of the global provider has changed. +} +``` -An [IProvider](./IProvider.md) implementation built on the official Microsoft Authentication Library (MSAL). -The [MsalProvider](./MsalProvider.md) is NetStandard and supports any NetStandard 2.0 applications. +## Getting an access token -Available in the `CommunityToolkit.Authentication.Msal` package. +Each provider exposes a function called `getTokenAsync` that can retrieve the current access token or retrieve a new access token for the provided scopes. The following example shows how to get a new access token or the currently signed in user: -### WindowsProvider +```csharp +using CommunityToolkit.Authentication; -A lightweight [IProvider](./IProvider.md) implementation built directly on the native Windows Account Manager (WAM) APIs. -The [WindowsProvider](./WindowsProvider.md) enables authentication of consumer MSA accounts without any Azure AAD config and only requires a Microsoft Store App registration to use. +// Assuming a provider has already been initialized +IProvider provider = ProviderManager.Instance.GlobalProvider; -Available in the `CommunityToolkit.Authentication.Uwp` package. +string token = await provider.GetTokenAsync(silentOnly: false); +``` ## Call Microsoft Graph APIs -Once authenticated, you can now make API calls to Microsoft Graph using a preconfigured GraphServiceClient. -Access to the client is enabled through an extension method on IProvider called, `GetClient()`. -See [ProviderExtensions](../helpers/ProviderExtensions.md) for more details. +Once authenticated, you can now make API calls to Microsoft Graph using the Graph SDK or without. + +### Use the Graph SDK + +Access APIs using the Graph SDK through a preconfigured `GraphServiceClient` available through an extension method on `IProvider` called, `GetClient()`. +See [Microsoft Graph Extensions](../helpers/extensions.md) for more details. + +This is the easiest way to get started because all of the Graph types are available and the `GraphServiceClient` offers a convenient way of building requests. Available in the `CommunityToolkit.Graph` package. @@ -82,3 +133,50 @@ GraphServiceClient graphClient = provider.GetClient(); var me = await graphClient.Me.Request().GetAsync(); ``` + +### Handle Graph requests manually + +Access APIs by managing requests to Microsoft Graph yourself. This is helpful for projects with existing systems for managing web requests, or for keeping package sizes minimal by excluding the Graph SDK. + +To make Graph API calls manually, use the `IProvider.AuthenticateRequestAsync(HttpRequestMessage)` method to authenticate an outgoing request. + +```csharp +using CommunityToolkit.Authentication; +using Newtonsoft.Json; +using Newtonsoft.Json.Linq; + +private async Task> GetDefaultTaskListAsync() +{ + return await GetResponseAsync>("https://graph.microsoft.com/v1.0/me/todo/lists/tasks/tasks"); +} + +private async Task GetResponseAsync(string requestUri) +{ + // Build the request + HttpRequestMessage getRequest = new HttpRequestMessage(HttpMethod.Get, requestUri); + + // Authenticate the request + await ProviderManager.Instance.GlobalProvider.AuthenticateRequestAsync(getRequest); + + var httpClient = new HttpClient(); + using (httpClient) + { + // Send the request + var response = await httpClient.SendAsync(getRequest); + + if (response.IsSuccessStatusCode) + { + // Handle the request response + var jsonResponse = await response.Content.ReadAsStringAsync(); + var jObject = JObject.Parse(jsonResponse); + if (jObject.ContainsKey("value")) + { + var result = JsonConvert.DeserializeObject(jObject["value"].ToString()); + return result; + } + } + } + + return default; +} +``` diff --git a/docs/graph/authentication/WindowsProvider.md b/docs/graph/authentication/windows.md similarity index 87% rename from docs/graph/authentication/WindowsProvider.md rename to docs/graph/authentication/windows.md index d20d4bed8..3510765cb 100644 --- a/docs/graph/authentication/WindowsProvider.md +++ b/docs/graph/authentication/windows.md @@ -10,7 +10,7 @@ dev_langs: # WindowsProvider The WindowsProvider is an authentication provider for accessing locally configured accounts on Windows. -It extends [IProvider](./IProvider.md) and uses the native Windows AccountManager (WAM) APIs and AccountsSettingsPane for sign in. +It extends [IProvider](./custom.md) and uses the native Windows AccountManager (WAM) APIs and AccountsSettingsPane for sign in. > Available in the `CommunityToolkit.Authentication.Uwp` package. @@ -61,7 +61,7 @@ using CommunityToolkit.Authentication; // Easily create a new WindowsProvider instance and set the GlobalProvider. // Don't forget to associate your app with the Microsoft Store before attempting sign in. -ProviderManager.Instance.GlobalProvider = new WindowsProvider(new string[] { "User.Read", "Task.ReadWrite" }); +ProviderManager.Instance.GlobalProvider = new WindowsProvider(new string[] { "User.Read", "Tasks.ReadWrite" }); ``` The WindowsProvider can also be configured to disabled auto-signin or show custom content in the `AccountsSettingsPane`. @@ -102,11 +102,20 @@ bool autoSignIn = false; ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes, accountsSettingsPaneConfig, webAccountProviderConfig, autoSignIn); ``` +## Constructor + +| Parameter | Type | Default | Description | +| -- | -- | -- | -- | +| scopes | string[] | null | List of scopes to initially request. | +| webAccountProviderConfig | WebAccountProviderConfig? | null | Configuration value for determining the available web account providers. | +| accountsSettingsPaneConfig | AccountsSettingsPaneConfig? | null | Configuration values for the AccountsSettingsPane. | +| autoSignIn | bool | true | Determines whether the provider attempts to silently log in upon instantiation. | + ## Properties | Property | Type | Description | | -- | -- | -- | -| State | [ProviderState](./IProvider.md) | Gets the current authentication state of the provider. | +| State | ProviderState | Gets the current authentication state of the provider. | | Scopes | string[] | List of scopes to pre-authorize on the user during authentication. | | WebAccountsProviderConfig | WebAccountProviderConfig | configuration values for determining the available web account providers. | | AccountsSettingsPaneConfig | AccountsSettingsPaneConfig | Configuration values for the AccountsSettingsPane, shown during authentication. | @@ -116,14 +125,14 @@ ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes, accountsSe | Event | Type | Description | | -- | -- | -- | -| StateChanged | EventHandler<[ProviderStateChangedEventArgs](./IProvider.md)> | Event called when the provider state changes. | +| StateChanged | EventHandler<ProviderStateChangedEventArgs> | Event called when the provider state changes. | ## Methods | Method | Arguments | Returns | Description | | -- | -- | -- | -- | | AuthenticateRequestAsync | HttpRequestMessage | Task | Authenticate an outgoing request. | -| GetTokenAsync | bool silentOnly = true | Task<string> | Retrieve a token for the authenticated user. | +| GetTokenAsync | bool silentOnly = true, string[] scopes = null | Task<string> | Retrieve a token for the authenticated user. | | SignInAsync | | Task | Sign in a user. | | SignOutAsync | | Task | Sign out the current user. | | TrySilentSignInAsync | | Task<bool> | Try signing in silently, without prompts. | diff --git a/docs/graph/controls/LoginButton.md b/docs/graph/controls/LoginButton.md index 64f187977..7a04eb2ef 100644 --- a/docs/graph/controls/LoginButton.md +++ b/docs/graph/controls/LoginButton.md @@ -9,14 +9,11 @@ dev_langs: # (Preview) LoginButton XAML Control -The [LoginButton](/dotnet/api/microsoft.toolkit.graph.controls.loginbutton) is both a button and flyout control to facilitate Microsoft identity platform authentication. It provides two states: +The LoginButton is both a button and flyout control to facilitate Microsoft identity platform authentication. It provides two states: * When the user is not signed in, the control is a simple button to initiate the sign in process. * When the user is signed in, the control displays the current signed in user name, profile image, and email. When clicked, a flyout is opened with a command to sign out. -> [!div class="nextstepaction"] -> [Try it in the sample app](uwpct://controls?sample=LoginButton) - > Available in the `CommunityToolkit.Graph.Uwp` package. > [!IMPORTANT] @@ -24,8 +21,10 @@ The [LoginButton](/dotnet/api/microsoft.toolkit.graph.controls.loginbutton) is b ## Syntax -```xaml - +```xml + + + ``` ## Sample Output @@ -49,20 +48,16 @@ The [LoginButton](/dotnet/api/microsoft.toolkit.graph.controls.loginbutton) is b | LogoutInitiated | The user started to logout. | | LogoutCompleted | The user signed out. | -## Sample Project - -[LoginButton sample page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.0.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/LoginButton). You can [see this in action](uwpct://Controls?sample=LoginButton) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). - ## Requirements | Device family | Universal, MinVersion or higher | | -- | -- | -| Namespace | Microsoft.Toolkit.Graph.Controls | -| NuGet package | [Microsoft.Toolkit.Graph.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Graph.Controls) | +| Namespace | CommunityToolkit.Graph.Uwp.Controls | +| NuGet package | [CommunityToolkit.Graph.Uwp](https://www.nuget.org/packages/CommunityToolkit.Graph.Uwp) | ## API -* [LoginButton source code](https://github.com/windows-toolkit/Graph-Controls/tree/rel/7.0.0/Microsoft.Toolkit.Graph.Controls/Controls/LoginButton) +* [LoginButton source code](https://github.com/windows-toolkit/Graph-Controls/tree/dev/7.1.0/CommunityToolkit.Graph.Uwp/Controls/LoginButton) ## Related Topics diff --git a/docs/graph/controls/PeoplePicker.md b/docs/graph/controls/PeoplePicker.md index ebd2e679c..dc0b15a98 100644 --- a/docs/graph/controls/PeoplePicker.md +++ b/docs/graph/controls/PeoplePicker.md @@ -9,10 +9,7 @@ dev_langs: # (Preview) PeoplePicker XAML Control -The [PeoplePicker](/dotnet/api/microsoft.toolkit.graph.controls.peoplepicker) searches for people and renders the list of results from Microsoft Graph. By default, the component will search across all people. - -> [!div class="nextstepaction"] -> [Try it in the sample app](uwpct://controls?sample=PeoplePicker) +The PeoplePicker searches for people and renders the list of results from Microsoft Graph. By default, the component will search across all people. > Available in the `CommunityToolkit.Graph.Uwp` package. @@ -21,8 +18,10 @@ The [PeoplePicker](/dotnet/api/microsoft.toolkit.graph.controls.peoplepicker) se ## Syntax -```xaml - +```xml + + + ``` ## Sample Output @@ -33,23 +32,19 @@ The [PeoplePicker](/dotnet/api/microsoft.toolkit.graph.controls.peoplepicker) se | Property | Type | Description | | -- | -- | -- | -| PickedPeople | ObservableCollection\ | Gets the set of Person objects chosen by the user. | -| SuggestedPeople | ObservableCollection\ | Gets or sets collection of people suggested by the graph from the user's query. | - -## Sample Project - -[PeoplePicker sample page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.0.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/PeoplePicker). You can [see this in action](uwpct://Controls?sample=PeoplePicker) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). +| PickedPeople | ObservableCollection<Person> | Gets the set of Person objects chosen by the user. | +| SuggestedPeople | ObservableCollection<Person> | Gets or sets collection of people suggested by the graph from the user's query. | ## Requirements | Device family | Universal, MinVersion or higher | | -- | -- | -| Namespace | Microsoft.Toolkit.Graph.Controls | -| NuGet package | [Microsoft.Toolkit.Graph.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Graph.Controls) | +| Namespace | CommunityToolkit.Graph.Uwp.Controls | +| NuGet package | [CommunityToolkit.Graph.Uwp](https://www.nuget.org/packages/CommunityToolkit.Graph.Uwp) | ## API -* [PeoplePicker source code](https://github.com/windows-toolkit/Graph-Controls/tree/rel/7.0.0/Microsoft.Toolkit.Graph.Controls/Controls/PeoplePicker) +* [PeoplePicker source code](https://github.com/windows-toolkit/Graph-Controls/tree/dev/7.1.0/CommunityToolkit.Graph.Uwp/Controls/PeoplePicker) ## Related Topics diff --git a/docs/graph/controls/PersonView.md b/docs/graph/controls/PersonView.md index 1923ecae1..91e41b20f 100644 --- a/docs/graph/controls/PersonView.md +++ b/docs/graph/controls/PersonView.md @@ -9,10 +9,7 @@ dev_langs: # (Preview) PersonView XAML Control -The [PersonView](/dotnet/api/microsoft.toolkit.graph.controls.personview) is used to display a person or contact by using their photo, name, and/or email address. - -> [!div class="nextstepaction"] -> [Try it in the sample app](uwpct://controls?sample=PersonView) +The PersonView control is used to display a person or contact by using their photo, name, and/or email address. > Available in the `CommunityToolkit.Graph.Uwp` package. @@ -21,8 +18,10 @@ The [PersonView](/dotnet/api/microsoft.toolkit.graph.controls.personview) is use ## Syntax -```xaml - +```xml + + + ``` ## Sample Output @@ -37,25 +36,20 @@ The [PersonView](/dotnet/api/microsoft.toolkit.graph.controls.personview) is use | IsLargeImage | bool | Value indicating if the image/circle size should be larger. | | PersonDetails | Person | Details about this person retrieved from the graph or provided by the developer. | | PersonQuery | string | Automatically retrieve data on the specified query from the graph. Use 'me' to retrieve info about the current user. Otherwise, it's best to use an e-mail address as a query. | -| ShowEmail | bool | Value indicating whether the user's email address should be displayed. | -| ShowName | bool | Value indicating whether the user's name should be displayed. | +| PersonViewType | PersonViewType | Value indicating what type of details should be displayed: `Avatar`, `OneLine`, `TwoLine` | | UserId | string | Gets or sets the UserId of the displayed person. | | UserPhoto | BitmapImage | Gets or sets the displayed photo. | -## Sample Project - -[PersonView sample page Source](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/rel/7.0.0/Microsoft.Toolkit.Uwp.SampleApp/SamplePages/PersonView). You can [see this in action](uwpct://Controls?sample=PersonView) in [Windows Community Toolkit Sample App](https://aka.ms/windowstoolkitapp). - ## Requirements | Device family | Universal, MinVersion or higher | | -- | -- | -| Namespace | Microsoft.Toolkit.Graph.Controls | -| NuGet package | [Microsoft.Toolkit.Graph.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Graph.Controls) | +| Namespace | CommunityToolkit.Graph.Uwp.Controls | +| NuGet package | [CommunityToolkit.Graph.Uwp](https://www.nuget.org/packages/CommunityToolkit.Graph.Uwp) | ## API -* [PersonView source code](https://github.com/windows-toolkit/Graph-Controls/tree/rel/7.0.0/Microsoft.Toolkit.Graph.Controls/Controls/PersonView) +* [PersonView source code](https://github.com/windows-toolkit/Graph-Controls/tree/dev/7.1.0/CommunityToolkit.Graph.Uwp/Controls/PersonView) ## Related Topics diff --git a/docs/graph/getting-started.md b/docs/graph/getting-started.md new file mode 100644 index 000000000..32ff15d3e --- /dev/null +++ b/docs/graph/getting-started.md @@ -0,0 +1,131 @@ +--- +title: Getting started with WCT Graph Helpers and Controls +author: shweaver-MSFT +description: Get started using authentication providers and Graph powered helpers from the Windows Community Toolkit. +keywords: uwp, wpf, netstandard, windows, community, toolkit, graph, login, authentication, provider, providers, identity +dev_langs: + - csharp +--- + +# Getting Started + +To get started using Graph data in your application, you'll first need to enable authentication. + +> [!IMPORTANT] +> These packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). + +## Set the global authentication provider + +### Authenticate with MSAL + +Leverage the official Microsoft Authentication Library (MSAL) to enable authentication in NetStandard 2.0 applications using [MsalProvider](./authentication/msal.md). + +1. Register your app in Azure AAD + + Before requesting data from [Microsoft Graph](https://graph.microsoft.com), you will need to [register your application](/azure/active-directory/develop/quickstart-register-app) to get a **ClientID**. + + > After finishing the initial registration page, you will also need to add an additional redirect URI. Click on "Add a Redirect URI", then "Add a platform", and then on "Mobile and desktop applications". Check the `https://login.microsoftonline.com/common/oauth2/nativeclient` checkbox on that page. Then click "Configure". +1. Install the `CommunityToolkit.Authentication.Msal` package. +1. Set the [ProviderManager](./authentication/ProviderManager.md).GlobalProvider to a new instance of [MsalProvider](./authentication/msal.md) with clientId and pre-configured scopes: + + ```csharp + using CommunityToolkit.Authentication; + + string clientId = "YOUR-CLIENT-ID-HERE"; + string[] scopes = new string[] { "User.Read" }; + + ProviderManager.Instance.GlobalProvider = new MsalProvider(clientId, scopes); + ``` + +> Note: You can use the `Scopes` property to preemptively request permissions from the user of your app for data your app needs to access from Microsoft Graph. + +### Authenticate with WindowsProvider + +Try out the [WindowsProvider](./authentication/windows.md) to enable authentication based on the native Windows Account Manager (WAM) APIs in your UWP apps, without requiring a dependency on MSAL. + +1. Associate your app with the Microsoft Store. The app association will act as our minimal app registration for authenticating consumer MSAs. See [WindowsProvider](./authentication/windows.md) for more details. +1. Install the `CommunityToolkit.Authentication.Uwp` package +1. Set the [ProviderManager](./authentication/ProviderManager.md).GlobalProvider to a new instance of [WindowsProvider](./authentication/windows.md) with pre-configured scopes: + + ```csharp + using CommunityToolkit.Authentication; + + string[] scopes = new string[] { "User.Read" }; + + ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes); + ``` + +## Sign in a user + +Call `SignInAsync` to initiate the login process. This will prompt the user to specify an account or provide credentials. + + ```csharp +using CommunityToolkit.Authentication; + +await ProviderManager.Instance.GlobalProvider.SignInAsync(); +``` + +You can also use the [LoginButton](./controls/LoginButton.md) control in UWP XAML apps to support the full sign in/out lifecycle and even display the user's photo and name when signed in. + +```xml + + + +``` + +## Make a Graph call + +Once you are authenticated, you can then make requests to the Graph using the GraphServiceClient instance via [extensions](./helpers/extensions.md). + +> Install the `CommunityToolkit.Graph` package. + +```csharp +using CommunityToolkit.Authentication; +using CommunityToolkit.Graph.Extensions; + +ProviderManager.Instance.ProviderStateChanged += (s, e) +{ + IProvider provider = ProviderManager.Instance.GlobalProvider; + if (provider?.State == ProviderState.SignedIn) + { + var graphClient = provider.GetClient(); + var me = await graphClient.Me.Request().GetAsync(); + } +} +``` + +### Use the Beta API + +You can use the `ProviderManager.Instance` to listen to changes in authentication status with the `ProviderUpdated` event or get direct access to the [.NET Graph Beta API](https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet) through `ProviderManager.Instance.GlobalProvider.GetBetaClient()`, just be sure to check if the `GlobalProvider` has been set first and its `State` is `SignedIn`: + +```csharp +using CommunityToolkit.Authentication; +using CommunityToolkit.Graph.Extensions; + +public ImageSource GetMyPhoto() +{ + IProvider provider = ProviderManager.Instance.GlobalProvider; + + if (provider?.State == ProviderState.SignedIn) + { + // Get the beta client + GraphServiceClient betaGraphClient = provider.GetBetaClient(); + + try + { + // Make a request to the beta endpoint for the current user's photo. + var photoStream = await betaGraphClient.Me.Photo.Content.Request().GetAsync(); + + using var ras = photoStream.AsRandomAccessStream(); + var bitmap = new BitmapImage(); + await bitmap.SetSourceAsync(ras); + + return bitmap; + } + catch + { + return null; + } + } +} +``` diff --git a/docs/graph/helpers/ProviderExtensions.md b/docs/graph/helpers/extensions.md similarity index 77% rename from docs/graph/helpers/ProviderExtensions.md rename to docs/graph/helpers/extensions.md index ac3d0ce71..9bb08f748 100644 --- a/docs/graph/helpers/ProviderExtensions.md +++ b/docs/graph/helpers/extensions.md @@ -1,24 +1,22 @@ --- -title: ProviderExtensions +title: Microsoft Graph Extensions author: shweaver-MSFT -description: Extension methods on IProvider that enable access to the pre-configured GraphServiceClient instance. +description: Extension methods that enable Graph API calls using the global authentication provider. keywords: uwp, wpf, netstandard, windows, community, toolkit, graph, provider, providers, extensions dev_langs: - csharp --- -# ProviderExtensions +# Microsoft Graph Extensions -The `ProviderExtensions` static class is available in the `CommunityToolkit.Graph` package. These extensions help you make calls to various Graph APIs. - -> Available in the `CommunityToolkit.Graph` package. +Use toolkit extensions to help you make calls to Graph APIs using the global authentication provider. Available in the `CommunityToolkit.Graph` package, `CommunityToolkit.Graph.Extensions` namespace. > [!IMPORTANT] > Windows Community Toolkit - Graph Controls and Helpers packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). ## Call Microsoft Graph APIs -Once authenticated, you can make API calls to Microsoft Graph using a preconfigured GraphServiceClient instance. Access to the client is enabled through an extension method on [IProvider](../authentication/IProvider.md) called, `GetClient()`. +Once authenticated, you can make API calls to Microsoft Graph using a preconfigured `GraphServiceClient` instance. Access to the client is enabled through an extension method on [IProvider](../authentication/custom.md) called, `GetClient()`. ```csharp using CommunityToolkit.Authentication; @@ -73,7 +71,9 @@ public ImageSource GetMyPhoto() } ``` -## Methods +## Extension methods + +The following extension methods are available on `IProvider` via the `CommunityToolkit.Graph.Extensions` namespace. | Method | Arguments | Returns | Description | | -- | -- | -- | -- | diff --git a/docs/graph/overview.md b/docs/graph/overview.md index 12531ed72..f7b788d62 100644 --- a/docs/graph/overview.md +++ b/docs/graph/overview.md @@ -36,103 +36,20 @@ For more info on our roadmap, check out the current [Release Plan](https://githu | `CommunityTookit.Graph` | NetStandard 2.0 | | `CommunityToolkit.Graph.Uwp` | UWP Windows 10 17763 | -## Getting Started +## Getting Started -To get started using Graph data in your application, you'll first need to enable authentication. +Check out the [Getting Started](./getting-started.md) guide for details on how to get authenticated and start calling Graph APIs. -> [!IMPORTANT] -> These packages are in preview. To get started using WCT preview packages visit the [WCT Preview Packages wiki page](https://aka.ms/wct/wiki/previewpackages). +## Learn More -### 1A. Setup authentication with MSAL +### Authentication Providers -Leverage the official Microsoft Authentication Library (MSAL) to enable authentication in any NetStandard application. +Hook into a lightweight framework for authenticating users and responding to login state changes: [Authentication Providers Overview](./authentication/overview.md) -1. Register your app in Azure AAD +### Graph Helpers - Before requesting data from [Microsoft Graph](https://graph.microsoft.com), you will need to [register your application](/azure/active-directory/develop/quickstart-register-app) to get a **ClientID**. +See [Microsoft Graph Extensions](./helpers/extensions.md) to learn how to get access to a preconfigured GraphServiceClient and make adhoc API calls using the Graph SDK. - > After finishing the initial registration page, you will also need to add an additional redirect URI. Click on "Add a Redirect URI", then "Add a platform", and then on "Mobile and desktop applications". Check the `https://login.microsoftonline.com/common/oauth2/nativeclient` checkbox on that page. Then click "Configure". -1. Install the `CommunityToolkit.Authentication.Msal` package. -1. Set the [ProviderManager](./authentication/ProviderManager.md).GlobalProvider to a new instance of [MsalProvider](./authentication/MsalProvider.md) with clientId and pre-configured scopes: +### Graph Controls - ```csharp - using CommunityToolkit.Authentication; - - string clientId = "YOUR-CLIENT-ID-HERE"; - string[] scopes = new string[] { "User.Read" }; - - ProviderManager.Instance.GlobalProvider = new MsalProvider(clientId, scopes); - ``` - -> Note: You can use the `Scopes` property to preemptively request permissions from the user of your app for data your app needs to access from Microsoft Graph. - -### 1B. Setup authentication with WindowsProvider - -Try out the [WindowsProvider](./authentication/WindowsProvider.md) to enable authentication based on the native Windows Account Manager (WAM) APIs in your UWP apps, without requiring a dependency on MSAL. - -1. Associate your app with the Microsoft Store. The app association will act as our minimal app registration for authenticating consumer MSAs. See the [WindowsProvider docs](https://github.com/windows-toolkit/Graph-Controls/edit/main/Docs/WindowsProvider.md) for more details. -1. Install the `CommunityToolkit.Authentication.Uwp` package -1. Set the [ProviderManager](./authentication/ProviderManager.md).GlobalProvider to a new instance of [WindowsProvider](./authentication/WindowsProvider.md) with pre-configured scopes: - - ```csharp - using CommunityToolkit.Authentication; - - string[] scopes = new string[] { "User.Read" }; - - ProviderManager.Instance.GlobalProvider = new WindowsProvider(scopes); - ``` - -### 2. Make a Graph call - -Once you are authenticated, you can then make requests to the Graph using the GraphServiceClient instance via [ProviderExtensions](./helpers/ProviderExtensions.md). - -> Install the `CommunityToolkit.Graph` package. - -``` -using CommunityToolkit.Authentication; -using CommunityToolkit.Graph.Extensions; - -var provider = ProviderManager.Instance.GlobalProvider; - -if (provider != null && provider.State == ProviderState.SignedIn) -{ - var graphClient = provider.GetClient(); - var me = await graphClient.Me.Request().GetAsync(); -} -``` - -**That's all you need to get started!** - -You can use the `ProviderManager.Instance` to listen to changes in authentication status with the `ProviderUpdated` event or get direct access to the [.NET Graph Beta API](https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet) through `ProviderManager.Instance.GlobalProvider.GetBetaClient()`, just be sure to check if the `GlobalProvider` has been set first and its `State` is `SignedIn`: - -```csharp -using CommunityToolkit.Authentication; -using CommunityToolkit.Graph.Extensions; - -public ImageSource GetMyPhoto() -{ - IProvider provider = ProviderManager.Instance.GlobalProvider; - - if (provider?.State == ProviderState.SignedIn) - { - // Get the beta client - GraphServiceClient betaGraphClient = provider.GetBetaClient(); - - try - { - // Make a request to the beta endpoint for the current user's photo. - var photoStream = await betaGraphClient.Me.Photo.Content.Request().GetAsync(); - - using var ras = photoStream.AsRandomAccessStream(); - var bitmap = new BitmapImage(); - await bitmap.SetSourceAsync(ras); - - return bitmap; - } - catch - { - return null; - } - } -} -``` +Build Graph experiences with XAML controls and helpers made for UWP, such as [LoginButton](./controls/LoginButton.md) or [PersonView](./controls/PersonView.md). diff --git a/docs/toc.md b/docs/toc.md index d8cab71f8..79b1e7bc4 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -77,27 +77,29 @@ ## [Overview](graph/overview.md) +## [Getting Started](graph/getting-started.md) + ## Authentication ### [Authentication Overview](graph/authentication/overview.md) -### [IProvider](graph/authentication/IProvider.md) - ### [ProviderManager](graph/authentication/ProviderManager.md) -### [MsalProvider](graph/authentication/MsalProvider.md) +### [MSAL provider](graph/authentication/msal.md) + +### [Windows provider](graph/authentication/windows.md) -### [WindowsProvider](graph/authentication/WindowsProvider.md) +### [Custom provider](graph/authentication/custom.md) ## Helpers -### [ProviderExtensions](graph/helpers/ProviderExtensions.md) +### [Microsoft Graph Extensions](graph/helpers/extensions.md) -### RoamingSettingsHelper (Coming soon!) + ## Controls -### GraphPresenter (Coming soon!) + ### [LoginButton (Preview)](graph/controls/LoginButton.md) @@ -489,9 +491,9 @@ ### [SharePointFileList](archive/graph/SharePointFileList.md) -### [InteractiveProviderBehavior](graph/providers/InteractiveProviderBehavior.md) +### [InteractiveProviderBehavior](archive/graph/providers/InteractiveProviderBehavior.md) -### [MockProviderBehavior](graph/providers/MockProviderBehavior.md) +### [MockProviderBehavior](archive/graph/providers/MockProviderBehavior.md) ## Parsers diff --git a/dotnet/docfx.json b/dotnet/docfx.json index a63c5c018..c7991b8b3 100644 --- a/dotnet/docfx.json +++ b/dotnet/docfx.json @@ -49,7 +49,8 @@ "extendBreadcrumb": true, "apiPlatform": "dotnet", "ms.topic": "managed-reference", - "ms.prod": "windows", + "ms.prod": "community-toolkit", + "products": ["https://authoring-docs-microsoft.poolparty.biz/devrel/bcbcbad5-4208-4783-8035-8481272c98b8"], "ms.technology": "windows-toolkit", "ms.author": "nikolame", "author": "dotnet-bot"