diff --git a/src/Uno.Extensions.Authentication.MSAL/HostBuilderExtensions.cs b/src/Uno.Extensions.Authentication.MSAL/HostBuilderExtensions.cs index a4b4e5cedf..a7e82e0fff 100644 --- a/src/Uno.Extensions.Authentication.MSAL/HostBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.MSAL/HostBuilderExtensions.cs @@ -1,8 +1,26 @@  namespace Uno.Extensions; +/// +/// Provides extension methods for MSAL authentication to use with . +/// public static class HostBuilderExtensions { + /// + /// Adds MSAL authentication to the specified . + /// + /// + /// The to add MSAL authentication to. + /// + /// + /// A delegate which can be used to configure the MSAL authentication provider that will be built. Optional. + /// + /// + /// The name of the authentication provider. This optional parameter defaults to "Msal". + /// + /// + /// The that was passed in. + /// public static IAuthenticationBuilder AddMsal( this IAuthenticationBuilder builder, Action? configure = default, @@ -29,7 +47,8 @@ public static IAuthenticationBuilder AddMsal( .AddAuthentication( name, authBuilder.Settings, - (provider, settings) => { + (provider, settings) => + { provider = provider with { Name = name, Settings = settings }; provider.Build(); return provider; diff --git a/src/Uno.Extensions.Authentication.MSAL/IMsalAuthenticationBuilder.cs b/src/Uno.Extensions.Authentication.MSAL/IMsalAuthenticationBuilder.cs index f641607908..9c1197c1ac 100644 --- a/src/Uno.Extensions.Authentication.MSAL/IMsalAuthenticationBuilder.cs +++ b/src/Uno.Extensions.Authentication.MSAL/IMsalAuthenticationBuilder.cs @@ -1,5 +1,8 @@ namespace Uno.Extensions.Authentication.MSAL; +/// +/// Implemented by classes that are builders for the MSAL authentication provider feature. +/// public interface IMsalAuthenticationBuilder : IBuilder { } diff --git a/src/Uno.Extensions.Authentication.MSAL/MsalAuthenticationBuilderExtensions.cs b/src/Uno.Extensions.Authentication.MSAL/MsalAuthenticationBuilderExtensions.cs index e269a6435f..70d4dd47a3 100644 --- a/src/Uno.Extensions.Authentication.MSAL/MsalAuthenticationBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.MSAL/MsalAuthenticationBuilderExtensions.cs @@ -1,7 +1,22 @@ namespace Uno.Extensions.Authentication; +/// +/// Provides MSAL-related extension methods for . +/// public static class MsalAuthenticationBuilderExtensions { + /// + /// Configures the MSAL authentication feature to use a public client application builder. + /// + /// + /// The to configure. + /// + /// + /// A delegate which can be used to create the public client application builder and configure MsalAuthenticationSettings to use it. + /// + /// + /// The that was passed in. + /// public static IMsalAuthenticationBuilder Builder( this IMsalAuthenticationBuilder builder, Action build @@ -18,6 +33,18 @@ Action build return builder; } + /// + /// Configures the MSAL authentication feature to use an incremental builder for StorageCreationProperties objects. + /// + /// + /// The to configure. + /// + /// + /// A delegate which can be used to create the StorageCreationPropertiesBuilder and configure MsalAuthenticationSettings to use it. + /// + /// + /// The that was passed in. + /// public static IMsalAuthenticationBuilder Storage( this IMsalAuthenticationBuilder builder, Action store @@ -34,6 +61,18 @@ Action store return builder; } + /// + /// Configures the MSAL authentication feature to be built with the specified scopes for authentication. + /// + /// + /// The to configure. + /// + /// + /// The MSAL scopes to use for authentication. + /// + /// + /// The that was passed in. + /// public static IMsalAuthenticationBuilder Scopes( this IMsalAuthenticationBuilder builder, string[] scopes @@ -50,6 +89,16 @@ string[] scopes return builder; } + /// + /// Configures a public client application builder to create the MSAL authentication + /// feature to use the redirect Uri provided by WebAuthenticationBroker. + /// + /// + /// The to configure. + /// + /// + /// The that was passed in. + /// [MethodImpl(MethodImplOptions.NoInlining)] public static PublicClientApplicationBuilder WithWebRedirectUri(this PublicClientApplicationBuilder builder) { diff --git a/src/Uno.Extensions.Authentication.Oidc/HostBuilderExtensions.cs b/src/Uno.Extensions.Authentication.Oidc/HostBuilderExtensions.cs index 3f75a0c386..2e4a213ccd 100644 --- a/src/Uno.Extensions.Authentication.Oidc/HostBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.Oidc/HostBuilderExtensions.cs @@ -1,7 +1,25 @@ namespace Uno.Extensions; +/// +/// Provides extension methods for OIDC authentication to use with . +/// public static class HostBuilderExtensions { + /// + /// Adds OIDC authentication to the specified . + /// + /// + /// The to add OIDC authentication to. + /// + /// + /// A delegate which can be used to configure the OIDC authentication provider that will be built. Optional. + /// + /// + /// The name of the authentication provider. This optional parameter defaults to "Oidc". + /// + /// + /// The that was passed in. + /// public static IAuthenticationBuilder AddOidc( this IAuthenticationBuilder builder, Action? configure = default, @@ -32,7 +50,8 @@ public static IAuthenticationBuilder AddOidc( .AddAuthentication( name, authBuilder.Settings, - (provider, settings) => { + (provider, settings) => + { provider = provider with { Name = name, Settings = settings }; provider.Build(); return provider; diff --git a/src/Uno.Extensions.Authentication.Oidc/IOidcAuthenticationBuilder.cs b/src/Uno.Extensions.Authentication.Oidc/IOidcAuthenticationBuilder.cs index 5a92c0c60e..fbaba57b49 100644 --- a/src/Uno.Extensions.Authentication.Oidc/IOidcAuthenticationBuilder.cs +++ b/src/Uno.Extensions.Authentication.Oidc/IOidcAuthenticationBuilder.cs @@ -1,5 +1,8 @@ namespace Uno.Extensions.Authentication.Oidc; +/// +/// Implemented by classes that are builders for the OIDC authentication provider feature. +/// public interface IOidcAuthenticationBuilder : IBuilder { } diff --git a/src/Uno.Extensions.Authentication.Oidc/OidcAuthenticationBuilderExtensions.cs b/src/Uno.Extensions.Authentication.Oidc/OidcAuthenticationBuilderExtensions.cs index e68f1c7ca5..76885f973a 100644 --- a/src/Uno.Extensions.Authentication.Oidc/OidcAuthenticationBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.Oidc/OidcAuthenticationBuilderExtensions.cs @@ -1,32 +1,107 @@ namespace Uno.Extensions.Authentication; +/// +/// Provides OIDC-related extension methods for . +/// public static class OidcAuthenticationBuilderExtensions { + /// + /// Configures the OIDC authentication feature to be built with the specified authority. + /// + /// + /// The to configure. + /// + /// + /// The authority to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder Authority( this IOidcAuthenticationBuilder builder, string authority) => builder.ChangeOption(options => options.Authority = authority); + /// + /// Configures the OIDC authentication feature to be built with the specified client ID. + /// + /// + /// The to configure. + /// + /// + /// The client ID to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder ClientId( this IOidcAuthenticationBuilder builder, string clientId) => builder.ChangeOption(options => options.ClientId = clientId); + /// + /// Configures the OIDC authentication feature to be built with the specified client secret. + /// + /// + /// The to configure. + /// + /// + /// The client secret to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder ClientSecret( this IOidcAuthenticationBuilder builder, string clientSecret) => builder.ChangeOption(options => options.ClientSecret = clientSecret); + /// + /// Configures the OIDC authentication feature to be built with the specified scope. + /// + /// + /// The to configure. + /// + /// + /// The scope to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder Scope( this IOidcAuthenticationBuilder builder, string scope) => builder.ChangeOption(options => options.Scope = scope); + /// + /// Configures the OIDC authentication feature to be built with the specified redirect URI. + /// + /// + /// The to configure. + /// + /// + /// The redirect URI to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder RedirectUri( this IOidcAuthenticationBuilder builder, string redirectUri) => builder.ChangeOption(options => options.RedirectUri = redirectUri); + /// + /// Configures the OIDC authentication feature to be built with the specified post-logout redirect URI. + /// + /// + /// The to configure. + /// + /// + /// The post-logout redirect URI to use for OIDC authentication. + /// + /// + /// The that was passed in. + /// public static IOidcAuthenticationBuilder PostLogoutRedirectUri( this IOidcAuthenticationBuilder builder, string postLogoutRedirectUri) diff --git a/src/Uno.Extensions.Authentication.UI/HostBuilderExtensions.cs b/src/Uno.Extensions.Authentication.UI/HostBuilderExtensions.cs index b8abf07999..bb4081fa1a 100644 --- a/src/Uno.Extensions.Authentication.UI/HostBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.UI/HostBuilderExtensions.cs @@ -1,7 +1,25 @@ namespace Uno.Extensions; +/// +/// Provides extension methods for web authentication to use with . +/// public static class HostBuilderExtensions { + /// + /// Adds web authentication to the specified . + /// + /// + /// The to add web authentication to. + /// + /// + /// A delegate which can be used to configure the web authentication provider that will be built. Optional. + /// + /// + /// The name of the authentication provider. This optional parameter defaults to "Web". + /// + /// + /// The that was passed in. + /// public static IAuthenticationBuilder AddWeb( this IAuthenticationBuilder builder, Action? configure = default, @@ -34,6 +52,24 @@ public static IAuthenticationBuilder AddWeb( (provider, settings) => provider with { Name = name, Settings = settings }); } + /// + /// Adds web authentication to the specified . + /// + /// + /// A type of service that will be used by the web authentication provider. + /// + /// + /// The to add web authentication to. + /// + /// + /// A delegate which can be used to configure the web authentication provider that will be built. Optional. + /// + /// + /// The name of the authentication provider. This optional parameter defaults to "Web". + /// + /// + /// The that was passed in. + /// public static IAuthenticationBuilder AddWeb( this IAuthenticationBuilder builder, Action>? configure = default, diff --git a/src/Uno.Extensions.Authentication.UI/Web/IWebAuthenticationBuilder.cs b/src/Uno.Extensions.Authentication.UI/Web/IWebAuthenticationBuilder.cs index 9e1d73cd3c..e3d4dfdc1a 100644 --- a/src/Uno.Extensions.Authentication.UI/Web/IWebAuthenticationBuilder.cs +++ b/src/Uno.Extensions.Authentication.UI/Web/IWebAuthenticationBuilder.cs @@ -1,9 +1,18 @@ namespace Uno.Extensions.Authentication.Web; +/// +/// Implemented by classes that are builders for the web authentication provider feature. +/// public interface IWebAuthenticationBuilder : IBuilder { } +/// +/// Implemented by classes that are builders for the web authentication provider feature. +/// +/// +/// A service type that is used by the web authentication provider. +/// public interface IWebAuthenticationBuilder : IWebAuthenticationBuilder { } diff --git a/src/Uno.Extensions.Authentication.UI/WebAuthenticationBuilderExtensions.cs b/src/Uno.Extensions.Authentication.UI/WebAuthenticationBuilderExtensions.cs index 00b2e9205e..4f7d431f7e 100644 --- a/src/Uno.Extensions.Authentication.UI/WebAuthenticationBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication.UI/WebAuthenticationBuilderExtensions.cs @@ -1,7 +1,25 @@ namespace Uno.Extensions.Authentication; +/// +/// Provides web-related extension methods for . +/// public static class WebAuthenticationBuilderExtensions { + /// + /// Configures the web authentication feature to be built with a preference for ephemeral web browser sessions. + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A value indicating whether or not ephemeral web browser sessions should be preferred. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrefersEphemeralWebBrowserSession( this TWebAuthenticationBuilder builder, bool preferEphemeral) @@ -10,14 +28,45 @@ public static TWebAuthenticationBuilder PrefersEphemeralWebBrowserSession s with { PrefersEphemeralWebBrowserSession = preferEphemeral }); + /// + /// Configures the web authentication feature to be built with the specified login start URI. + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The login start URI to use. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder LoginStartUri( this TWebAuthenticationBuilder builder, string uri) - where TWebAuthenticationBuilder: IWebAuthenticationBuilder + where TWebAuthenticationBuilder : IWebAuthenticationBuilder => builder.Property((WebAuthenticationSettings s) => s with { LoginStartUri = uri }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that will prepare the login start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginStartUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -29,7 +78,23 @@ public static TWebAuthenticationBuilder PrepareLoginStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate, which takes a dictionary of tokens and returns a string, that will prepare the login start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginStartUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string> prepare) @@ -42,6 +107,23 @@ public static TWebAuthenticationBuilder PrepareLoginStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a service provider for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate, which takes a service provider and returns a string, that will prepare the login start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginStartUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -54,6 +136,23 @@ public static TWebAuthenticationBuilder PrepareLoginStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a service provider and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—which takes a service provider, a dictionary of tokens, and returns a string—that will prepare the login start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginStartUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string> prepare) @@ -66,6 +165,23 @@ public static TWebAuthenticationBuilder PrepareLoginStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a service provider, a token cache, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—which takes a service provider, a token cache, a dictionary of tokens, and returns a string—that will prepare the login start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginStartUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -77,6 +193,23 @@ public static TWebAuthenticationBuilder PrepareLoginStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a service of the specified type for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the login start URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type and returns a string—that will prepare the login start URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLoginStartUri( this IWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -88,6 +221,23 @@ public static IWebAuthenticationBuilder PrepareLoginStartUri prepare(service, cancellationToken) }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the login start URI. This overload allows + /// for a delegate that will use a service of the specified type, a service provider, a token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the login start URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the login start URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLoginStartUri( this IWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -98,6 +248,21 @@ public static IWebAuthenticationBuilder PrepareLoginStartUri PrepareLoginStartUri = prepare }); + /// + /// Configures the web authentication feature to be built with the specified login callback URI. + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The login callback URI to use. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder LoginCallbackUri( this TWebAuthenticationBuilder builder, string uri) @@ -106,6 +271,22 @@ public static TWebAuthenticationBuilder LoginCallbackUri s with { LoginCallbackUri = uri }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that will prepare the login callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -118,6 +299,23 @@ public static TWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate, which takes a dictionary of tokens and returns a string, that will prepare the login callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string> prepare) @@ -130,6 +328,23 @@ public static TWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a service provider for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate, which takes a service provider and returns a string, that will prepare the login callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -142,6 +357,23 @@ public static TWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a service provider and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—which takes a service provider, a dictionary of tokens, and returns a string—that will prepare the login callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -154,6 +386,23 @@ public static TWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a service provider, a token cache, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—which takes a service provider, a token cache, a dictionary of tokens, and returns a string—that will prepare the login callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLoginCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -165,6 +414,23 @@ public static TWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a service of the specified type for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the login callback URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type and returns a string—that will prepare the login callback URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLoginCallbackUri( this IWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -176,6 +442,23 @@ public static IWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the login callback URI. This overload allows + /// for a delegate that will use a service of the specified type, a service provider, a token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the login callback URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the login callback URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLoginCallbackUri( this IWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -186,6 +469,22 @@ public static IWebAuthenticationBuilder PrepareLoginCallbackUri + /// Configures the web authentication feature to be built with the specified post login callback. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that uses a dictionary of tokens and returns a dictionary of tokens (or null) that can be used for post login operations. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PostLogin( this TWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> postLogin) @@ -198,7 +497,23 @@ public static TWebAuthenticationBuilder PostLogin( postLogin(tokens, cancellationToken) }); - + /// + /// Configures the web authentication feature to be built with the specified post login callback. This overload allows + /// for a delegate that will use a service provider, a token cache reference, a dictionary of credentials, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that uses a service provider, a token cache reference, a dictionary of credentials, a dictionary of tokens, and returns a dictionary of tokens (or null) that can be used for post login operations. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PostLogin( this TWebAuthenticationBuilder builder, AsyncFunc?, IDictionary, IDictionary?> postLogin) @@ -211,7 +526,23 @@ public static TWebAuthenticationBuilder PostLogin( postLogin(services, cache, credentials, tokens, cancellationToken) }); - + /// + /// Configures the web authentication feature to be built with the specified post login callback. This overload allows + /// for a delegate that will use a service of the specified type, a dictionary of tokens, and return a dictionary of tokens (or null) for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the return value of the post login callback. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a dictionary of tokens, and returns a dictionary of tokens (or null)—that will prepare the return value of the post login callback. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PostLogin( this IWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> postLogin) @@ -223,7 +554,23 @@ public static IWebAuthenticationBuilder PostLogin( postLogin(service, tokens, cancellationToken) }); - + /// + /// Configures the web authentication feature to be built with the specified post login callback. This overload allows + /// for a delegate that will use a service of the specified type, a service provider, a token cache reference, a dictionary of credentials, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the return value of the post login callback. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of credentials, a dictionary of tokens, and returns a dictionary of tokens (or null)—that will prepare the return value of the post login callback. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PostLogin( this IWebAuthenticationBuilder builder, AsyncFunc?, string, IDictionary, IDictionary?> postLogin) @@ -231,9 +578,22 @@ public static IWebAuthenticationBuilder PostLogin( builder.Property((WebAuthenticationSettings s) => s with { PostLoginCallback = postLogin }); - - - + /// + /// Configures the web authentication feature to be built with the specified logout start URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The logout start URI to use. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder LogoutStartUri( this TWebAuthenticationBuilder builder, string uri) @@ -242,6 +602,22 @@ public static TWebAuthenticationBuilder LogoutStartUri s with { LogoutStartUri = uri }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the logout start URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that will prepare the logout start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLogoutStartUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -254,6 +630,23 @@ public static TWebAuthenticationBuilder PrepareLogoutStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the logout start URI. This overload allows + /// for a delegate that will use a service provider, token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—that takes a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the logout start URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLogoutStartUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -262,6 +655,23 @@ public static TWebAuthenticationBuilder PrepareLogoutStartUri s with { PrepareLogoutStartUri = prepare }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the logout start URI. This overload allows + /// for a delegate that will use a service of the specified type for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the logout start URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type and returns a string—that will prepare the logout start URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLogoutStartUri( this IWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -273,6 +683,23 @@ public static IWebAuthenticationBuilder PrepareLogoutStartUri + /// Configures the web authentication feature to be built with a delegate that will prepare the logout start URI. This overload allows + /// for a delegate that will use a service of the specified type, a service provider, a token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the logout start URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the logout start URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLogoutStartUri( this IWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -280,7 +707,22 @@ public static IWebAuthenticationBuilder PrepareLogoutStartUri s) => s with { PrepareLogoutStartUri = prepare }); - + /// + /// Configures the web authentication feature to be built with the specified logout callback URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The logout callback URI to use. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder LogoutCallbackUri( this TWebAuthenticationBuilder builder, string uri) @@ -289,6 +731,22 @@ public static TWebAuthenticationBuilder LogoutCallbackUri s with { LogoutCallbackUri = uri }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the logout callback URI. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that will prepare the logout callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLogoutCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -301,7 +759,23 @@ public static TWebAuthenticationBuilder PrepareLogoutCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the logout callback URI. This overload allows + /// for a delegate that will use a service provider, token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate—that takes a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the logout callback URI. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder PrepareLogoutCallbackUri( this TWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -310,6 +784,23 @@ public static TWebAuthenticationBuilder PrepareLogoutCallbackUri s with { PrepareLogoutCallbackUri = prepare }); + /// + /// Configures the web authentication feature to be built with a delegate that will prepare the logout callback URI. This overload allows + /// for a delegate that will use a service of the specified type for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the logout callback URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type and returns a string—that will prepare the logout callback URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLogoutCallbackUri( this IWebAuthenticationBuilder builder, AsyncFunc prepare) @@ -321,7 +812,23 @@ public static IWebAuthenticationBuilder PrepareLogoutCallbackUri + /// Configures the web authentication feature to be built with a delegate that will prepare the logout callback URI. This overload allows + /// for a delegate that will use a service of the specified type, a service provider, a token cache reference, and a dictionary of tokens for authentication. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to prepare the logout callback URI. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of tokens, and returns a string—that will prepare the logout callback URI. + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder PrepareLogoutCallbackUri( this IWebAuthenticationBuilder builder, AsyncFunc?, string?, string> prepare) @@ -329,6 +836,23 @@ public static IWebAuthenticationBuilder PrepareLogoutCallbackUri s) => s with { PrepareLogoutCallbackUri = prepare }); + /// + /// Configures the web authentication feature to be built with the specified refresh callback. This type of callback is used to refresh + /// the tokens that are used for authentication when they expire. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that uses a dictionary of tokens and returns a dictionary of the updated tokens (or null). + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder Refresh( this TWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -341,7 +865,24 @@ public static TWebAuthenticationBuilder Refresh( refreshCallback(tokens, cancellationToken) }); - + /// + /// Configures the web authentication feature to be built with the specified refresh callback. This type of callback is used to refresh + /// the tokens that are used for authentication when they expire. This overload allows for a delegate that will use a service provider, + /// a token cache reference, and a dictionary of existing tokens. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// A delegate that uses a service provider, a token cache reference, a dictionary of existing tokens, and returns a dictionary of the updated tokens (or null). + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder Refresh( this TWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -350,6 +891,24 @@ public static TWebAuthenticationBuilder Refresh( builder.Property((WebAuthenticationSettings s) => s with { RefreshCallback = refreshCallback }); + /// + /// Configures the web authentication feature to be built with the specified refresh callback. This type of callback is used to refresh + /// the tokens that are used for authentication when they expire. This overload allows for a delegate that will use a service of the + /// specified type and a dictionary of existing tokens. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to refresh the tokens. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type as well as a dictionary of existing tokens and returns a dictionary of the updated tokens (or null). + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder Refresh( this IWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -361,7 +920,24 @@ public static IWebAuthenticationBuilder Refresh( refreshCallback(service, tokens, cancellationToken) }); - + /// + /// Configures the web authentication feature to be built with the specified refresh callback. This type of callback is used to refresh + /// the tokens that are used for authentication when they expire. This overload allows for a delegate that will use a service of the + /// specified type, a service provider, a token cache reference, and a dictionary of existing tokens. + /// The underlying property that will be set to such delegate is located on . + /// + /// + /// The type of service that will be used by the delegate to refresh the tokens. + /// + /// + /// The instance of to configure. + /// + /// + /// A delegate—which takes a service of type , a service provider, a token cache reference, a dictionary of existing tokens, and returns a dictionary of the updated tokens (or null). + /// + /// + /// An instance of that was passed in. + /// public static IWebAuthenticationBuilder Refresh( this IWebAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -369,7 +945,23 @@ public static IWebAuthenticationBuilder Refresh( builder.Property((WebAuthenticationSettings s) => s with { RefreshCallback = refreshCallback }); - + /// + /// Configures the web authentication feature to be built with the specified access token key. This key is used to retrieve the access token + /// from the dictionary of tokens that are used for authentication. + /// The underlying property that will be set to such key is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The key to use to retrieve the access token from the dictionary of tokens that are used for authentication. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder AccessTokenKey( this TWebAuthenticationBuilder builder, string key) @@ -378,6 +970,23 @@ public static TWebAuthenticationBuilder AccessTokenKey s with { AccessTokenKey = key }); + /// + /// Configures the web authentication feature to be built with the specified refresh token key. This key is used to retrieve the refresh token + /// from the dictionary of tokens that are used for authentication. + /// The underlying property that will be set to such key is located on . + /// + /// + /// The type of implementation that will be configured. + /// + /// + /// The instance of the implementation to configure. + /// + /// + /// The key to use to retrieve the refresh token from the dictionary of tokens that are used for authentication. + /// + /// + /// An instance of the implementation that was passed in. + /// public static TWebAuthenticationBuilder RefreshTokenKey( this TWebAuthenticationBuilder builder, string key) diff --git a/src/Uno.Extensions.Authentication/AuthenticationServiceExtensions.cs b/src/Uno.Extensions.Authentication/AuthenticationServiceExtensions.cs index 4fc21cd968..09ab515d73 100644 --- a/src/Uno.Extensions.Authentication/AuthenticationServiceExtensions.cs +++ b/src/Uno.Extensions.Authentication/AuthenticationServiceExtensions.cs @@ -1,11 +1,45 @@ namespace Uno.Extensions.Authentication; +/// +/// Extension methods for . +/// public static class AuthenticationServiceExtensions { - public static ValueTask LoginAsync (this IAuthenticationService auth, IDictionary? credentials = default, string? provider = null, CancellationToken? cancellationToken = default) + /// + /// Logs in the user using the specified credentials. + /// + /// + /// The to use. + /// + /// + /// The credentials to use for the login. Optional + /// + /// + /// The authentication provider name to specify for login. Optional + /// + /// + /// A used to cancel the login operation. Optional + /// + /// + /// A that completes when the login operation is complete. + /// + public static ValueTask LoginAsync(this IAuthenticationService auth, IDictionary? credentials = default, string? provider = null, CancellationToken? cancellationToken = default) { return auth.LoginAsync(default, credentials, provider, cancellationToken); } + + /// + /// Logs out the user. + /// + /// + /// The to use. + /// + /// + /// A used to cancel the logout operation. Optional + /// + /// + /// A that completes when the logout operation is complete. + /// public static ValueTask LogoutAsync(this IAuthenticationService auth, CancellationToken? cancellationToken = default) { return auth.LogoutAsync(default, cancellationToken); diff --git a/src/Uno.Extensions.Authentication/BaseAuthenticationProvider.cs b/src/Uno.Extensions.Authentication/BaseAuthenticationProvider.cs index 2fa3bb03ed..5f229c6b49 100644 --- a/src/Uno.Extensions.Authentication/BaseAuthenticationProvider.cs +++ b/src/Uno.Extensions.Authentication/BaseAuthenticationProvider.cs @@ -1,8 +1,35 @@  namespace Uno.Extensions.Authentication; +/// +/// Base type for authentication providers. +/// +/// +/// The logger to use for recording messages produced during various authentication operations on this provider. +/// +/// +/// The name of this provider. +/// +/// +/// The token cache to use for the default behavior of getting any existing tokens. +/// public abstract record BaseAuthenticationProvider(ILogger Logger, string Name, ITokenCache Tokens) : IAuthenticationProvider { + /// + /// Logs in the user using the specified credentials. + /// + /// + /// The to use for dispatching any UI operations. + /// + /// + /// The credentials to use for the login. + /// + /// + /// A used to cancel the login operation. + /// + /// + /// A that completes when the login operation is complete. + /// public async ValueTask?> LoginAsync(IDispatcher? dispatcher, IDictionary? credentials, CancellationToken cancellationToken) { try @@ -24,12 +51,39 @@ public abstract record BaseAuthenticationProvider(ILogger Logger, string Name, I } } + /// + /// Logs in the user using the specified credentials. + /// + /// + /// The to use for dispatching any UI operations. + /// + /// + /// The credentials to use for the login. + /// + /// + /// A used to cancel the login operation. + /// + /// + /// A that completes when the login operation is complete. + /// protected virtual ValueTask?> InternalLoginAsync(IDispatcher? dispatcher, IDictionary? credentials, CancellationToken cancellationToken) { // Default behavior is to return null, which indicates unsuccessful login return default; } + /// + /// Logs out the user. + /// + /// + /// The to use for dispatching any UI operations. + /// + /// + /// A used to cancel the logout operation. + /// + /// + /// A that completes once the user is logged out. + /// public async ValueTask LogoutAsync(IDispatcher? dispatcher, CancellationToken cancellationToken) { try @@ -50,12 +104,33 @@ public async ValueTask LogoutAsync(IDispatcher? dispatcher, CancellationTo } } + /// + /// Logs out the user. + /// + /// + /// The to use for dispatching any UI operations. + /// + /// + /// A used to cancel the logout operation. + /// + /// + /// A that completes once the user is logged out. + /// protected virtual async ValueTask InternalLogoutAsync(IDispatcher? dispatcher, CancellationToken cancellationToken) { // Default implementation is to return true, which will cause the token cache to be flushed return true; } + /// + /// Refreshes the authentication tokens. + /// + /// + /// A used to cancel the refresh operation. + /// + /// + /// A that completes once the tokens have been refreshed. + /// public async ValueTask?> RefreshAsync(CancellationToken cancellationToken) { var tokens = await Tokens.GetAsync(cancellationToken); @@ -78,6 +153,15 @@ protected virtual async ValueTask InternalLogoutAsync(IDispatcher? dispatc } } + /// + /// Refreshes the authentication tokens. + /// + /// + /// A used to cancel the refresh operation. + /// + /// + /// A that completes once the tokens have been refreshed. + /// protected virtual async ValueTask?> InternalRefreshAsync(CancellationToken cancellationToken) { // Default implementation is to just return the existing tokens (ie success!) diff --git a/src/Uno.Extensions.Authentication/Custom/ICustomAuthenticationBuilder.cs b/src/Uno.Extensions.Authentication/Custom/ICustomAuthenticationBuilder.cs index c1456db5d4..bee3b0c950 100644 --- a/src/Uno.Extensions.Authentication/Custom/ICustomAuthenticationBuilder.cs +++ b/src/Uno.Extensions.Authentication/Custom/ICustomAuthenticationBuilder.cs @@ -1,9 +1,18 @@ namespace Uno.Extensions.Authentication.Custom; +/// +/// Implemented by classes that are builders for the custom authentication provider feature. +/// public interface ICustomAuthenticationBuilder : IBuilder { } +/// +/// Implemented by classes that are builders for the custom authentication provider feature. +/// +/// +/// A service type that is used by the custom authentication provider. +/// public interface ICustomAuthenticationBuilder : IBuilder { } diff --git a/src/Uno.Extensions.Authentication/CustomAuthenticationBuilderExtensions.cs b/src/Uno.Extensions.Authentication/CustomAuthenticationBuilderExtensions.cs index f027e4a846..a252e37c4c 100644 --- a/src/Uno.Extensions.Authentication/CustomAuthenticationBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication/CustomAuthenticationBuilderExtensions.cs @@ -1,8 +1,22 @@ namespace Uno.Extensions.Authentication; +/// +/// Extension methods for and . +/// public static class CustomAuthenticationBuilderExtensions { - + /// + /// Specifies a callback for login which is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The login callback to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc?> loginCallback) @@ -10,7 +24,18 @@ public static ICustomAuthenticationBuilder Login( return builder.Login((sp, dispatcher, cache, tokens, ct) => loginCallback(sp, dispatcher, ct)); } - + /// + /// Specifies a callback containing tokens for login which is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The login callback containing tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -18,7 +43,19 @@ public static ICustomAuthenticationBuilder Login( return builder.Login((sp, dispatcher, cache, tokens, ct) => loginCallback(sp, dispatcher, tokens, ct)); } - + /// + /// Specifies a login callback containing tokens and a token cache. The callback specified is + /// registered as a property value within the builder settings, if present. + /// + /// + /// The to use. + /// + /// + /// The login callback containing tokens and a token cache to be associated with the settings object of . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -34,6 +71,21 @@ public static ICustomAuthenticationBuilder Login( return builder; } + /// + /// Specifies a login callback containing a service type and tokens which is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the login callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The login callback containing a service type and tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -41,6 +93,21 @@ public static ICustomAuthenticationBuilder Login( return builder.Login((service, sp, dispatcher, cache, tokens, ct) => loginCallback(service, tokens, ct)); } + /// + /// Specifies a login callback containing a service type, UI thread dispatcher, and tokens which is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the login callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The login callback containing a service type, UI thread dispatcher, and tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -48,6 +115,21 @@ public static ICustomAuthenticationBuilder Login( return builder.Login((service, sp, dispatcher, cache, tokens, ct) => loginCallback(service, dispatcher, tokens, ct)); } + /// + /// Specifies a login callback containing a service type, UI thread dispatcher, token cache, and tokens which is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the login callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The login callback containing a service type, UI thread dispatcher, token cache, and tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -55,6 +137,23 @@ public static ICustomAuthenticationBuilder Login( return builder.Login((service, sp, dispatcher, cache, tokens, ct) => loginCallback(service, dispatcher, cache, tokens, ct)); } + /// + /// Specifies a login callback containing a service type, service provider, UI thread dispatcher, token cache, + /// and tokens which is invoked by the object building the custom authentication provider. The callback specified is + /// registered as a property value within the builder settings, if present. + /// + /// + /// A service type that is used in the login callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The login callback containing a service type, service provider, UI thread dispatcher, token cache, and tokens to be associated with the settings object of . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Login( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> loginCallback) @@ -70,6 +169,18 @@ public static ICustomAuthenticationBuilder Login( return builder; } + /// + /// Specifies a callback for refresh which is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The refresh callback to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Refresh( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -77,6 +188,20 @@ public static ICustomAuthenticationBuilder Refresh( return builder.Refresh((sp, cache, tokens, ct) => refreshCallback(sp, tokens, ct)); } + /// + /// Specifies a callback for refresh which contains tokens and a token cache which is + /// invoked by the object building the custom authentication provider. The callback specified is + /// registered as a property value within the builder settings, if present. + /// + /// + /// The to use. + /// + /// + /// The refresh callback containing tokens and a token cache to be associated with the settings object of . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Refresh( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -92,6 +217,21 @@ public static ICustomAuthenticationBuilder Refresh( return builder; } + /// + /// Specifies a callback for refresh which contains a service type and tokens which is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the refresh callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The refresh callback containing a service type and tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Refresh( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -99,6 +239,21 @@ public static ICustomAuthenticationBuilder Refresh( return builder.Refresh((service, sp, cache, tokens, ct) => refreshCallback(service, tokens, ct)); } + /// + /// Specifies a callback for refresh which contains a service type, token cache, and tokens which is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the refresh callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The refresh callback containing a service type, token cache, and tokens to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Refresh( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -106,6 +261,23 @@ public static ICustomAuthenticationBuilder Refresh( return builder.Refresh((service, sp, cache, tokens, ct) => refreshCallback(service, cache, tokens, ct)); } + /// + /// Specifies a callback for refresh which contains a service type, service provider, token cache, and tokens + /// which is invoked by the object building the custom authentication provider. The callback specified is + /// registered as a property value within the builder settings, if present. + /// + /// + /// A service type that is used in the refresh callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The refresh callback containing a service type, service provider, token cache, and tokens to be associated with the settings object of . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Refresh( this ICustomAuthenticationBuilder builder, AsyncFunc, IDictionary?> refreshCallback) @@ -121,6 +293,18 @@ public static ICustomAuthenticationBuilder Refresh( return builder; } + /// + /// Specifies a callback for logout which is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The logout callback to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc logoutCallback) @@ -128,7 +312,18 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((sp, dispatcher, cache, tokens, ct) => logoutCallback(sp, ct)); } - + /// + /// Specifies a callback for logout which contains a reference to the UI thread dispatcher and is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a reference to the UI thread dispatcher to be invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc logoutCallback) @@ -136,6 +331,18 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((sp, dispatcher, cache, tokens, ct) => logoutCallback(sp, dispatcher, ct)); } + /// + /// Specifies a callback for logout which contains a reference to the UI thread dispatcher, tokens, and is invoked by the object building the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a reference to the UI thread dispatcher, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) @@ -143,6 +350,20 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((sp, dispatcher, cache, tokens, ct) => logoutCallback(sp, dispatcher, tokens, ct)); } + /// + /// Specifies a callback for logout which contains a reference to the UI thread dispatcher, token cache, tokens, + /// and is invoked by the object building the custom authentication provider. The callback specified is + /// registered as a property value within the builder settings, if present. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a reference to the UI thread dispatcher, token cache, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) @@ -158,6 +379,21 @@ public static ICustomAuthenticationBuilder Logout( return builder; } + /// + /// Specifies a callback for logout which contains a service type, tokens, and is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the logout callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a service type, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) @@ -165,6 +401,21 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((service, sp, dispatcher, cache, tokens, ct) => logoutCallback(service, tokens, ct)); } + /// + /// Specifies a callback for logout which contains a service type, UI thread dispatcher, tokens, and is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the logout callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a service type, UI thread dispatcher, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) @@ -172,6 +423,22 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((service, sp, dispatcher, cache, tokens, ct) => logoutCallback(service, dispatcher, tokens, ct)); } + /// + /// Specifies a callback for logout which contains a service type, UI thread dispatcher, token cache, tokens, + /// and is invoked by the object building the custom authentication provider. + /// + /// + /// A service type that is used in the logout callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a service type, UI thread dispatcher, token cache, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) @@ -179,6 +446,23 @@ public static ICustomAuthenticationBuilder Logout( return builder.Logout((service, sp, dispatcher, cache, tokens, ct) => logoutCallback(service, dispatcher, cache, tokens, ct)); } + /// + /// Specifies a callback for logout which contains a service type, service provider, UI thread dispatcher, token cache, tokens, + /// and is invoked by the object building the custom authentication provider. The callback specified is registered as a property + /// value within the builder settings, if present. + /// + /// + /// A service type that is used in the logout callback for a builder. + /// + /// + /// The to use. + /// + /// + /// The logout callback containing a service type, service provider, UI thread dispatcher, token cache, tokens, and is invoked by the . + /// + /// + /// The to use for further configuration. + /// public static ICustomAuthenticationBuilder Logout( this ICustomAuthenticationBuilder builder, AsyncFunc, bool> logoutCallback) diff --git a/src/Uno.Extensions.Authentication/HandlerBuilderExtensions.cs b/src/Uno.Extensions.Authentication/HandlerBuilderExtensions.cs index e2805d3d97..88ca7e62e7 100644 --- a/src/Uno.Extensions.Authentication/HandlerBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication/HandlerBuilderExtensions.cs @@ -1,24 +1,54 @@ namespace Uno.Extensions.Authentication; +/// +/// Extension methods for . +/// public static class HandlerBuilderExtensions { + /// + /// Configures the handler settings to use cookies for authentication. + /// + /// + /// The to use. + /// + /// + /// The name of the cookie to use for the access token. + /// + /// + /// The name of the cookie to use for the refresh token. Optional + /// + /// + /// The for further configuration. + /// public static IHandlerBuilder Cookies( this IHandlerBuilder builder, string accessTokenCookie, - string? refreshTokenCookie=null) + string? refreshTokenCookie = null) { if (builder is IBuilder authBuilder) { authBuilder.Settings = authBuilder.Settings with { - CookieAccessToken= accessTokenCookie, - CookieRefreshToken= refreshTokenCookie + CookieAccessToken = accessTokenCookie, + CookieRefreshToken = refreshTokenCookie }; } return builder; } + /// + /// Configures the handler settings to use an authorization header for authentication. + /// + /// + /// The to use. + /// + /// + /// The name of the scheme to use for the authorization header. This optional parameter defaults to "Bearer". + /// + /// + /// The for further configuration. + /// public static IHandlerBuilder AuthorizationHeader( this IHandlerBuilder builder, string? scheme = "Bearer") @@ -27,13 +57,22 @@ public static IHandlerBuilder AuthorizationHeader( { authBuilder.Settings = authBuilder.Settings with { - AuthorizationHeaderScheme= scheme, + AuthorizationHeaderScheme = scheme, }; } return builder; } + /// + /// Configures the handler settings to use no handlers for authentication. + /// + /// + /// The to use. + /// + /// + /// The for further configuration. + /// public static IHandlerBuilder None( this IHandlerBuilder builder) { diff --git a/src/Uno.Extensions.Authentication/Handlers/IHandlerBuilder.cs b/src/Uno.Extensions.Authentication/Handlers/IHandlerBuilder.cs index fa7436638b..2eada5d7d6 100644 --- a/src/Uno.Extensions.Authentication/Handlers/IHandlerBuilder.cs +++ b/src/Uno.Extensions.Authentication/Handlers/IHandlerBuilder.cs @@ -1,5 +1,8 @@ namespace Uno.Extensions.Authentication.Handlers; +/// +/// Implemented by classes that are builders for a handler to be used with the authentication feature. +/// public interface IHandlerBuilder : IBuilder { } diff --git a/src/Uno.Extensions.Authentication/Headers.cs b/src/Uno.Extensions.Authentication/Headers.cs index 5dcfe70949..3757e0642f 100644 --- a/src/Uno.Extensions.Authentication/Headers.cs +++ b/src/Uno.Extensions.Authentication/Headers.cs @@ -1,7 +1,14 @@ namespace Uno.Extensions.Authentication; +/// +/// Contains values which correspond to headers commonly used by the authentication feature. +/// public static class Headers { internal const string NoRefreshKey = "No-Refresh"; + + /// + /// Defines a header value which indicates that the tokens should not be refreshed. + /// public const string NoRefresh = $"{NoRefreshKey}:true"; } diff --git a/src/Uno.Extensions.Authentication/HostBuilderExtensions.cs b/src/Uno.Extensions.Authentication/HostBuilderExtensions.cs index a730eaf0d7..5c0326eba4 100644 --- a/src/Uno.Extensions.Authentication/HostBuilderExtensions.cs +++ b/src/Uno.Extensions.Authentication/HostBuilderExtensions.cs @@ -1,7 +1,25 @@ namespace Uno.Extensions; +/// +/// Provides extension methods for custom authentication to use with . +/// public static class HostBuilderExtensions { + /// + /// Configures the authentication builder to use a custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// An action to configure the custom authentication provider. Optional + /// + /// + /// The name of the custom authentication provider. This optional parameter defaults to "Custom". + /// + /// + /// The for further configuration. + /// public static IAuthenticationBuilder AddCustom( this IAuthenticationBuilder builder, Action? configure = default, @@ -18,6 +36,25 @@ public static IAuthenticationBuilder AddCustom( (provider, settings) => provider with { Name = name, Settings = settings }); } + /// + /// Configures the authentication builder to use a custom authentication provider. + /// + /// + /// A type of service that will be used by the custom authentication provider. + /// + /// + /// The to use. + /// + /// + /// An action to configure how the custom authentication provider will be built. This often uses a + /// previously-specified service of type TService. Optional + /// + /// + /// The name of the custom authentication provider. This optional parameter defaults to "Custom". + /// + /// + /// The for further configuration. + /// public static IAuthenticationBuilder AddCustom( this IAuthenticationBuilder builder, Action>? configure = default, @@ -68,6 +105,21 @@ internal static IAuthenticationBuilder AddAuthentication + /// Configures the host builder to use a specified Action to configure how the authentication provider will be built. + /// + /// + /// The to use. + /// + /// + /// An action to configure the authentication provider. Optional + /// + /// + /// An action to configure the handlers registered for authorization. Optional + /// + /// + /// The for further configuration. + /// public static IHostBuilder UseAuthentication( this IHostBuilder builder, Action build, @@ -78,7 +130,7 @@ public static IHostBuilder UseAuthentication( build?.Invoke(authBuilder); return builder - .ConfigureServices((ctx,services) => + .ConfigureServices((ctx, services) => { if (ctx.IsRegistered(nameof(UseAuthentication))) { diff --git a/src/Uno.Extensions.Authentication/IAuthenticationBuilder.cs b/src/Uno.Extensions.Authentication/IAuthenticationBuilder.cs index 8da4739b76..b70101824b 100644 --- a/src/Uno.Extensions.Authentication/IAuthenticationBuilder.cs +++ b/src/Uno.Extensions.Authentication/IAuthenticationBuilder.cs @@ -1,4 +1,7 @@ namespace Uno.Extensions.Authentication; -public interface IAuthenticationBuilder +/// +/// Implemented by classes that are builders for the authentication feature. +/// +public interface IAuthenticationBuilder { } diff --git a/src/Uno.Extensions.Authentication/IAuthenticationService.cs b/src/Uno.Extensions.Authentication/IAuthenticationService.cs index 33544cb1e2..8d8332e071 100644 --- a/src/Uno.Extensions.Authentication/IAuthenticationService.cs +++ b/src/Uno.Extensions.Authentication/IAuthenticationService.cs @@ -1,11 +1,73 @@ namespace Uno.Extensions.Authentication; +/// +/// A service with methods for authenticating a user. +/// public interface IAuthenticationService { + /// + /// Gets the names of the authentication providers that are supported by this service. + /// string[] Providers { get; } + + /// + /// Logs in the user with the specified credentials using the specified provider name. + /// + /// + /// A dispatcher that can be used to perform operations on the UI thread. + /// + /// + /// A dictionary of credentials to use for logging in the user. Optional + /// + /// + /// The name of the authentication provider to use. Optional + /// + /// + /// A cancellation token that can be used to cancel the login operation. Optional + /// + /// + /// A task that represents the asynchronous login operation. The task result is true if the login was successful. + /// ValueTask LoginAsync(IDispatcher? dispatcher, IDictionary? credentials = default, string? provider = null, CancellationToken? cancellationToken = default); + + /// + /// Refreshes the authentication tokens for the current user. + /// + /// + /// A cancellation token that can be used to cancel the refresh operation. Optional + /// + /// + /// A task that represents the asynchronous refresh operation. The task result is true if the refresh was successful. + /// ValueTask RefreshAsync(CancellationToken? cancellationToken = default); + + /// + /// Logs out the current user. + /// + /// + /// A dispatcher that can be used to perform operations on the UI thread. + /// + /// + /// A cancellation token that can be used to cancel the logout operation. Optional + /// + /// + /// A task that represents the asynchronous logout operation. The task result is true if the logout was successful. + /// ValueTask LogoutAsync(IDispatcher? dispatcher, CancellationToken? cancellationToken = default); + + /// + /// Gets a value indicating whether the current user is authenticated. + /// + /// + /// A cancellation token that can be used to cancel the operation. Optional + /// + /// + /// A task that represents the asynchronous operation. The task result is true if the user is authenticated. + /// ValueTask IsAuthenticated(CancellationToken? cancellationToken = default); + + /// + /// Defines an event that is raised when the user is logged out. + /// event EventHandler LoggedOut; } diff --git a/src/Uno.Extensions.Authentication/ITokenCache.cs b/src/Uno.Extensions.Authentication/ITokenCache.cs index 07a52025c7..9e29852c21 100644 --- a/src/Uno.Extensions.Authentication/ITokenCache.cs +++ b/src/Uno.Extensions.Authentication/ITokenCache.cs @@ -1,12 +1,74 @@  namespace Uno.Extensions.Authentication; +/// +/// Implemented by classes that represent a cache for authentication tokens. +/// public interface ITokenCache { + /// + /// Gets the current provider which is associated with the tokens. + /// + /// + /// A which can be used to cancel the operation. + /// + /// + /// A task that represents the asynchronous operation. The task result is the name of the current provider or null. + /// ValueTask GetCurrentProviderAsync(CancellationToken ct); - ValueTask HasTokenAsync(CancellationToken cancellationToken ); + + /// + /// Gets a value indicating whether the cache has tokens for the current provider. + /// + /// + /// A which can be used to cancel the operation. + /// + /// + /// A task that represents the asynchronous operation. The task result is true if the cache has tokens for the current provider. + /// + ValueTask HasTokenAsync(CancellationToken cancellationToken); + + /// + /// Gets the tokens for the current provider. + /// + /// + /// A which can be used to cancel the operation. + /// + /// + /// A task that represents the asynchronous operation. The task result is the tokens for the current provider. + /// ValueTask> GetAsync(CancellationToken cancellationToken); + + /// + /// Saves a dictionary of tokens for the specified provider. + /// + /// + /// The name of the provider for which the tokens will be saved. + /// + /// + /// A dictionary of tokens to save. + /// + /// + /// A which can be used to cancel the operation. + /// + /// + /// A task that represents the asynchronous operation. + /// ValueTask SaveAsync(string provider, IDictionary? tokens, CancellationToken cancellationToken); + + /// + /// Clears the tokens for the current provider. + /// + /// + /// A which can be used to cancel the operation. + /// + /// + /// A task that represents the asynchronous operation. + /// ValueTask ClearAsync(CancellationToken cancellationToken); + + /// + /// Occurs when the tokens for the current provider have changed substantially. + /// event EventHandler? Cleared; } diff --git a/src/Uno.Extensions.Authentication/TokenCacheExtensions.cs b/src/Uno.Extensions.Authentication/TokenCacheExtensions.cs index fe59d5df97..c0765ddc0a 100644 --- a/src/Uno.Extensions.Authentication/TokenCacheExtensions.cs +++ b/src/Uno.Extensions.Authentication/TokenCacheExtensions.cs @@ -5,27 +5,98 @@ namespace Uno.Extensions.Authentication; +/// +/// Extension methods for . +/// public static class TokenCacheExtensions { + /// + /// Defines a key for the token cache which corresponds to an access token element. + /// public const string AccessTokenKey = "AccessToken"; + + /// + /// Defines a key for the token cache which corresponds to a refresh token element. + /// public const string RefreshTokenKey = "RefreshToken"; + /// + /// Gets the access token from the token cache. + /// + /// + /// The to use. + /// + /// + /// A which can be used to cancel the operation. Optional + /// + /// + /// A task that represents an asynchronous operation. The task result is the access token or null. + /// public static ValueTask AccessTokenAsync(this ITokenCache cache, CancellationToken? cancellation = default) { return cache.TokenAsync(AccessTokenKey, cancellation); } + /// + /// Gets the refresh token from the token cache. + /// + /// + /// The to use. + /// + /// + /// A which can be used to cancel the operation. Optional + /// + /// + /// A task that represents an asynchronous operation. The task result is the refresh token or null. + /// public static ValueTask RefreshTokenAsync(this ITokenCache cache, CancellationToken? cancellation = default) { return cache.TokenAsync(RefreshTokenKey, cancellation); } + /// + /// Gets a token which is represented by a specified key from the token cache. + /// + /// + /// The to use. + /// + /// + /// The key of the token to get. + /// + /// + /// A which can be used to cancel the operation. Optional + /// + /// + /// A task that represents an asynchronous operation. The task result is the token or null. + /// public static async ValueTask TokenAsync(this ITokenCache cache, string tokenKey, CancellationToken? cancellation = default) { var tokens = await cache.GetAsync(cancellation ?? CancellationToken.None); return tokens.FirstOrDefault(x => x.Key == tokenKey).Value; } - public static async ValueTask SaveTokensAsync(this ITokenCache cache, string provider, string? accessToken=null, string? refreshToken=null, CancellationToken? cancellation = default) + + /// + /// Saves the values provided for access and refresh tokens in the token cache. + /// + /// + /// The to use. + /// + /// + /// The name of the authentication provider for which the tokens will be saved. + /// + /// + /// The access token to save. Optional + /// + /// + /// The refresh token to save. Optional + /// + /// + /// A which can be used to cancel the operation. Optional + /// + /// + /// A task that represents an asynchronous operation. + /// + public static async ValueTask SaveTokensAsync(this ITokenCache cache, string provider, string? accessToken = null, string? refreshToken = null, CancellationToken? cancellation = default) { var ct = cancellation ?? CancellationToken.None; var dict = await cache.GetAsync(ct); @@ -40,6 +111,24 @@ public static async ValueTask SaveTokensAsync(this ITokenCache cache, string pro await cache.SaveAsync(provider, dict, ct); } + /// + /// Gets a typed entity represented by the token corresponding to a specified key from the provided dictionary. + /// + /// + /// The type of the entity to get. It should be that of the entity which is represented by the serialized token. + /// + /// + /// The dictionary of tokens to use. + /// + /// + /// The serializer to use. + /// + /// + /// The key of the token to get. + /// + /// + /// The entity or null if the token is not found or is empty. + /// public static TEntity? Get(this IDictionary tokens, ISerializer serializer, string key) { if (tokens.TryGetValue(key, out var value) && !string.IsNullOrWhiteSpace(value)) @@ -49,6 +138,25 @@ public static async ValueTask SaveTokensAsync(this ITokenCache cache, string pro return default; } + /// + /// Serializes the entity provided and sets the result as the value of a token + /// element corresponding to a specified key in the dictionary. + /// + /// + /// The type of entity to set. It should be what the serialized token will represent. + /// + /// + /// The dictionary of tokens to use. + /// + /// + /// The serializer to use. + /// + /// + /// The key of the token to set. + /// + /// + /// The entity to serialize and set. + /// public static void Set(this IDictionary tokens, ISerializer serializer, string key, TEntity entity) { tokens[key] = serializer.ToString(entity);