Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add installation step to extensions docs #2335

Merged
merged 1 commit into from
Jun 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions doc/Learn/Authentication/AuthenticationOverview.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,15 @@ There are two aspects to the Authentication extensions:
- Authentication: the process of authenticating the user and acquiring tokens
- Authorization: tokens (acquired via authentication) can be queried to control access to parts of the application or supplied to service call so the user can be authorized to access the back-end service

## Installation

`Authentication` is provided as an Uno Feature. To enable `Authentication` support in your application, add `Authentication` to the `<UnoFeatures>` property in the Class Library (.csproj) file. In case you are using Msal Authentication add `AuthenticationMsal`, or `AuthenticationOidc` for Oidc Authentication.

> [!IMPORTANT]
> This walkthrough assumes you created your app using the Single Project template. If you used a different template, please refer to our [Migrating Projects to Single Project](xref:Uno.Development.MigratingToSingleProject) documentation.

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## IAuthenticationService

The `IAuthenticationService` interface defines the methods that an application can call to authenticate the user.
Expand Down Expand Up @@ -64,11 +73,11 @@ The `CustomAuthenticationProvider` provides a basic implementation of the `IAuth

### MSAL

The `MsalAuthenticationProvider` (in the Uno.Extensions.Authentication.MSAL.UI or Uno.Extensions.Authentication.MSAL.WinUI packages) wraps the [MSAL library](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) from Microsoft into an implementation of `IAuthenticationProvider`. This implementation ignores any credentials passed into the `LoginAsync` method, instead invoking the web based authentication process required to authentication with Microsoft. Learn [Msal authentication](xref:Uno.Extensions.Authentication.HowToMsalAuthentication)
The `MsalAuthenticationProvider` wraps the [MSAL library](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) from Microsoft into an implementation of `IAuthenticationProvider`. This implementation ignores any credentials passed into the `LoginAsync` method, instead invoking the web based authentication process required to authentication with Microsoft. Learn [Msal authentication](xref:Uno.Extensions.Authentication.HowToMsalAuthentication)

### Oidc

The `OidcAuthenticationProvider` (in the Uno.Extensions.Authentication.Oidc.UI or Uno.Extensions.Authentication.Oidc.WinUI packages) wraps support for any [OpenID Connect](https://openid.net/connect/) backend, including [IdentityServer](https://duendesoftware.com/products/identityserver). Learn [Oidc authentication](xref:Uno.Extensions.Authentication.HowToOidcAuthentication)
The `OidcAuthenticationProvider` wraps support for any [OpenID Connect](https://openid.net/connect/) backend, including [IdentityServer](https://duendesoftware.com/products/identityserver). Learn [Oidc authentication](xref:Uno.Extensions.Authentication.HowToOidcAuthentication)

#### Platform-specific behavior

Expand Down
23 changes: 21 additions & 2 deletions doc/Learn/Authentication/HowTo-Authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,16 @@ uid: Uno.Extensions.Authentication.HowToAuthentication

### 1. Basic Credential Checking

- Install `Uno.Extensions.Authentication` into all projects
- Add `Authentication` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
+ Authentication;
Toolkit;
MVUX;
</UnoFeatures>
```

- Append `UseAuthentication` to the `IHostBuilder` instance. The `Login` callback is used to verify the credentials. If the user is authenticated, the callback needs to return a non-empty dictionary of key-value pairs (this would typically contain tokens such as an access token and/or refresh token).

Expand Down Expand Up @@ -133,7 +142,17 @@ From this walk through, you can see how the IAuthenticationService can be used t

### 2. Invoking an Authentication Service

- Add `Uno.Extensions.Http.Refit` package reference to Extensions.props
- Add `Http` to the `<UnoFeatures>` property in the Class Library (.csproj) file. This will bring the references we need to access `Refit`.

```diff
<UnoFeatures>
Material;
Authentication;
+ Http;
Toolkit;
MVUX;
</UnoFeatures>
```

- Add POCO objects to working with [dummyjson.com](https://dummyjson.com)

Expand Down
11 changes: 10 additions & 1 deletion doc/Learn/Authentication/HowTo-MsalAuthentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,16 @@ uid: Uno.Extensions.Authentication.HowToMsalAuthentication

- The identity provider will provider you with a client ID and guidance on scopes to use.

- Make sure `Uno.Extensions.Authentication.MSAL.WinUI` NuGet package is installed in your solution.
- Add `AuthenticationMsal` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
+ AuthenticationMsal;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Set up MSAL authentication

Expand Down
11 changes: 10 additions & 1 deletion doc/Learn/Authentication/HowTo-OidcAuthentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,16 @@ uid: Uno.Extensions.Authentication.HowToOidcAuthentication

- A client id (and client secret) will be provided to you.

- Make sure `Uno.Extensions.Authentication.Oidc.WinUI` NuGet package is installed in your solution.
- Add `AuthenticationOidc` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
+ AuthenticationOidc;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Set up OIDC authentication

Expand Down
19 changes: 14 additions & 5 deletions doc/Learn/Authentication/HowTo-WebAuthentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,16 @@ uid: Uno.Extensions.Authentication.HowToWebAuthentication

- A client id (and client secret) will be provided to you.

- Make sure `Uno.Extensions.Authentication.WinUI` NuGet package is installed in your solution.
- Add `Authentication` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
+ Authentication;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Set up web authentication

Expand Down Expand Up @@ -72,10 +81,10 @@ uid: Uno.Extensions.Authentication.HowToWebAuthentication

```json
{
"Web": {
"LoginStartUri": "URI_TO_LOGIN",
"LogoutStartUri": "URI_TO_LOGOUT"
}
"Web": {
"LoginStartUri": "URI_TO_LOGIN",
"LogoutStartUri": "URI_TO_LOGOUT"
}
}
```

Expand Down
12 changes: 12 additions & 0 deletions doc/Learn/Configuration/ConfigurationOverview.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ uid: Uno.Extensions.Configuration.Overview

This feature uses [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) for any configuration related work. For more documentation on configuration, read the references listed at the bottom.

## Installation

> [!NOTE]
> If you already have `Extensions` in `<UnoFeatures>`, then `Configuration` is already installed, as its dependencies are included with the `Extensions` feature.

`Configuration` is provided as an Uno Feature. To enable `Configuration` support in your application, add `Configuration` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

> [!IMPORTANT]
> This walkthrough assumes you created your app using the Single Project template. If you used a different template, please refer to our [Migrating Projects to Single Project](xref:Uno.Development.MigratingToSingleProject) documentation.

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Using Configuration

The `IConfiguration` interface is registered as a service when the `UseConfiguration()` extension method is used.
Expand Down
21 changes: 17 additions & 4 deletions doc/Learn/Configuration/HowTo-Configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,20 @@ uid: Uno.Extensions.Configuration.HowToConfiguration
> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [Creating an application with Uno.Extensions article](xref:Uno.Extensions.HowToGettingStarted) for creating an application from the template.

### 1. Specify configuration information to load on `IConfigBuilder`
### 1. Installation

* Add `Configuration` to the `<UnoFeatures>` property in the Class Library (.csproj) file. If you already have `Extensions` in `<UnoFeatures>`, then `Configuration` is already installed, as its dependencies are included with the `Extensions` feature.

```diff
<UnoFeatures>
Material;
+ Configuration;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Specify configuration information to load on `IConfigBuilder`

* Uno.Extensions apps specify which configuration information to load by calling the `UseConfiguration()` extension method for `IHostBuilder`.

Expand Down Expand Up @@ -50,7 +63,7 @@ uid: Uno.Extensions.Configuration.HowToConfiguration
}
```

### 2. Define a class to model the configuration section
### 3. Define a class to model the configuration section

* Your JSON file(s) will consist of a serialized representation of multiple properties and their values. Hence, configuration sections allow you to programmatically read a specific subset of these properties from the instantiated class that represents them.

Expand All @@ -66,7 +79,7 @@ uid: Uno.Extensions.Configuration.HowToConfiguration
}
```

### 3. Load a specific configuration section
### 4. Load a specific configuration section

* You can now use the `Section<T>()` extension method on `IConfigBuilder` to load configuration information for class or record of the type argument you specify:

Expand All @@ -89,7 +102,7 @@ uid: Uno.Extensions.Configuration.HowToConfiguration
}
```

### 4. Read configuration section values from a registered service
### 5. Read configuration section values from a registered service

* To access the instantiated representation of the configuration section you registered above, complete with values populated from the `appsettings.json` file, you'll need to add a new constructor parameter for it to one of your application's services.

Expand Down
11 changes: 10 additions & 1 deletion doc/Learn/Configuration/HowTo-WritableConfiguration.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,16 @@ A special interface called `IWritableOptions<T>` is registered as a service when

### 1. Prepare for writing configuration values

* Ensure your project has `Uno.Extensions.Configuration` installed as a NuGet [package](https://www.nuget.org/packages/Uno.Extensions.Configuration/).
* Add `Configuration` to the `<UnoFeatures>` property in the Class Library (.csproj) file. If you already have `Configuration` in `<UnoFeatures>`, then `Configuration` is already installed, as its dependencies are included with the `Extensions` feature.

```diff
<UnoFeatures>
Material;
+ Configuration;
Toolkit;
MVUX;
</UnoFeatures>
```

* To enable configuration, you first need to call `UseConfiguration()` on the `IHostBuilder` instance:

Expand Down
13 changes: 11 additions & 2 deletions doc/Learn/DependencyInjection/HowTo-CommunityToolkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,18 @@ This tutorial will walk you through how to set up this feature and use it to man
> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [Creating an application with Uno.Extensions article](xref:Uno.Extensions.HowToGettingStarted) for creating an application from the template.

### 1. Add the CommunityToolkit.Mvvm package to your project
### 1. Add CommunityToolkit.Mvvm to your project

* Add the [CommunityToolkit.Mvvm](https://www.nuget.org/packages/CommunityToolkit.Mvvm) package to your project.
* Add `Mvvm` to the `<UnoFeatures>` property in the Class Library (.csproj) file. This will add the [CommunityToolkit.Mvvm](https://www.nuget.org/packages/CommunityToolkit.Mvvm) package to your project.

```diff
<UnoFeatures>
Material;
Extensions;
+ Mvvm;
Toolkit;
</UnoFeatures>
```

### 2. Register services with the DI container

Expand Down
12 changes: 12 additions & 0 deletions doc/Learn/Http/HowTo-EndpointOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,18 @@ It's often necessary to include an API key alongside requests to a web API. This

### 2. Defining the endpoint

* Add `Http` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
Extensions;
+ Http;
Toolkit;
MVUX;
</UnoFeatures>
```

* Enable HTTP by calling the `UseHttp()` method to register a HTTP client with the `IHostBuilder`:

```csharp
Expand Down
20 changes: 17 additions & 3 deletions doc/Learn/Http/HowTo-Http.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,21 @@ When working with a complex application, centralized registration of your API en
> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [Creating an application with Uno.Extensions article](xref:Uno.Extensions.HowToGettingStarted) for creating an application from the template.

### 1. Enable HTTP
### 1. Installation

* Add `Http` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
Extensions;
+ Http;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Enable HTTP

* Call the `UseHttp()` method to register a HTTP client with the `IHostBuilder` which implements `IHttpClient`:

Expand All @@ -26,7 +40,7 @@ When working with a complex application, centralized registration of your API en
}
```

### 2. Register Endpoints
### 3. Register Endpoints

* The `AddClient` extension method is used to register a client with the service collection.

Expand Down Expand Up @@ -66,7 +80,7 @@ When working with a complex application, centralized registration of your API en
}
```

### 3. Use the Service to Request Data
### 4. Use the Service to Request Data

* Since you registered the service with the service collection, you can now inject the `IShowService` implementation into your view models and use it to request information about a show from the endpoint:

Expand Down
24 changes: 19 additions & 5 deletions doc/Learn/Http/HowTo-Refit.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,21 @@ When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/p
> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [Creating an application with Uno.Extensions article](xref:Uno.Extensions.HowToGettingStarted) for creating an application from the template.

### 1. Enable HTTP
### 1. Installation

* Add `Http` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

```diff
<UnoFeatures>
Material;
Extensions;
+ Http;
Toolkit;
MVUX;
</UnoFeatures>
```

### 2. Enable HTTP

* When working with a complex application, centralized registration of your API endpoints is a good practice. This allows you to easily change the endpoint for a given service. It also reduces the complexity to adding new services which can then have their `HttpClient` instance reused across multiple instances of view models or other services.

Expand All @@ -30,7 +44,7 @@ When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/p

* This feature requires the [Uno.Extensions.Http.WinUI](https://www.nuget.org/packages/Uno.Extensions.Http.WinUI) package. It uses [Microsoft Extensions](https://www.nuget.org/packages/Microsoft.Extensions.Http) for any HTTP-related [work](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#benefits-of-using-ihttpclientfactory) such as naming or configuring the `HttpClient` instance associated with your endpoints.

### 2. Define the live interface
### 3. Define the live interface

* For the purposes of this tutorial, we will create and register an interface for the Chuck Norris facts web API which is documented [here](https://api.chucknorris.io/)

Expand All @@ -54,7 +68,7 @@ When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/p

* `ApiResponse<T>` is used to deserialize the response from the API. It is defined in the `Refit` package.

### 3. Generate a data model from the API response
### 4. Generate a data model from the API response

* The next step is to generate a data model from the response we will get from the API. This will be used to deserialize the response which we'll learn is a JSON object with a `total` property and `result` that contains an array of Chuck Norris data objects.

Expand Down Expand Up @@ -153,7 +167,7 @@ When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/p

* Rename the partial classes `Welcome` to `ChuckNorrisData` and `Result` to `ChuckNorrisDataResult`

### 4. Register the endpoint
### 5. Register the endpoint

* Unlike standard HTTP endpoints, Refit endpoints you define will be registered as a service with the `AddRefitClient<T>()` extension method, where the type argument `T` corresponds to an interface you define.

Expand Down Expand Up @@ -217,7 +231,7 @@ When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/p

* Observe that the name of the configuration section is similar to that of the endpoint interface we defined earlier. By default, the interface name without the leading `I` prefix is assumed to be the section name. This can be overridden by specifying a name while registering the service. The name you use should be the second argument to `AddRefitClient<T>()`.

### 5. Use the endpoint
### 6. Use the endpoint

* `IChuckNorrisEndpoint` can now be used in a service implementation by injecting it into the constructor. This interface will be used to make requests to the web service and deserialize responses.

Expand Down
9 changes: 9 additions & 0 deletions doc/Learn/Http/HttpOverview.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ Uno.Extensions.Http allows for the registration of API **endpoints** as multiple

For additional documentation on HTTP requests, read the references listed at the bottom.

## Installation

`Http` is provided as an Uno Feature. To enable `Http` support in your application, add `Http` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

> [!IMPORTANT]
> This walkthrough assumes you created your app using the Single Project template. If you used a different template, please refer to our [Migrating Projects to Single Project](xref:Uno.Development.MigratingToSingleProject) documentation.

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Register Endpoints

Web resources exposed through an API are defined in the application as clients. These client registrations include type arguments and endpoints to be used for the client. The endpoint is defined in the `EndpointOptions` class. While it uses the platform-native HTTP handler by default, this value can be configured.
Expand Down
Loading
Loading