From 5bad5d606c0320fccfb8c27ac43903012c253203 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Tue, 15 Nov 2022 15:15:32 +0100 Subject: [PATCH 1/2] Update Essentials AppInfo API Docs --- .../Microsoft.Maui.Essentials/AppInfo.xml | 145 ------------------ .../Microsoft.Maui.Essentials/AppTheme.xml | 69 --------- .../src/AppInfo/AppInfo.netstandard.cs | 1 - src/Essentials/src/AppInfo/AppInfo.shared.cs | 83 +++++++++- src/Essentials/src/AppInfo/AppInfo.uwp.cs | 29 ++++ src/Essentials/src/AppInfo/AppTheme.shared.cs | 12 +- .../src/AppInfo/LayoutDirection.shared.cs | 8 + 7 files changed, 120 insertions(+), 227 deletions(-) delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/AppInfo.xml delete mode 100644 src/Essentials/docs/Microsoft.Maui.Essentials/AppTheme.xml diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/AppInfo.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/AppInfo.xml deleted file mode 100644 index 165e50a913ee..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/AppInfo.xml +++ /dev/null @@ -1,145 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Object - - - - Represents information about the application. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets the application build number. - The application build number. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets the application name. - The application name. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets the application package name or identifier. - The package name or identifier. - On Android and iOS, this is the application package name. On UWP, this is the application GUID. - - - - - - - Property - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.AppTheme - - - Gets the detected Theme of the system or application. - The Theme. - For platforms or platform versions which aren't supported, Unspecified is returned. - - - - - - - Method - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Void - - - - Open the settings menu or page for the application. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.Version - - - Gets the application version. - The application version. - - - - - - - - Property - - 1.0.0.0 - Microsoft.Maui.Essentials - - - System.String - - - Gets the application version. - The application version. - - - - - diff --git a/src/Essentials/docs/Microsoft.Maui.Essentials/AppTheme.xml b/src/Essentials/docs/Microsoft.Maui.Essentials/AppTheme.xml deleted file mode 100644 index e829c9e364c4..000000000000 --- a/src/Essentials/docs/Microsoft.Maui.Essentials/AppTheme.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - Microsoft.Maui.Essentials - 1.0.0.0 - - - System.Enum - - - Application Theme Type - - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.AppTheme - - 2 - - Dark Theme - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.AppTheme - - 1 - - Light Theme - - - - - - - Field - - Microsoft.Maui.Essentials - 1.0.0.0 - - - Microsoft.Maui.Essentials.AppTheme - - 0 - - Default, Unknown or Unspecified Theme - - - - diff --git a/src/Essentials/src/AppInfo/AppInfo.netstandard.cs b/src/Essentials/src/AppInfo/AppInfo.netstandard.cs index 988852093c31..6e73c70dae4e 100644 --- a/src/Essentials/src/AppInfo/AppInfo.netstandard.cs +++ b/src/Essentials/src/AppInfo/AppInfo.netstandard.cs @@ -1,6 +1,5 @@ namespace Microsoft.Maui.ApplicationModel { - /// class AppInfoImplementation : IAppInfo { public string PackageName => throw ExceptionUtils.NotSupportedOrImplementedException; diff --git a/src/Essentials/src/AppInfo/AppInfo.shared.cs b/src/Essentials/src/AppInfo/AppInfo.shared.cs index 0d9d00b0c244..01dfcdce52d0 100644 --- a/src/Essentials/src/AppInfo/AppInfo.shared.cs +++ b/src/Essentials/src/AppInfo/AppInfo.shared.cs @@ -3,57 +3,118 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Represents information about the application. + /// public interface IAppInfo { + /// + /// Gets the application package name or identifier. + /// + /// On Android and iOS, this is the application package name. On Windows, this is the application GUID. string PackageName { get; } + /// + /// Gets the application name. + /// string Name { get; } + /// + /// Gets the application version as a string representation. + /// string VersionString { get; } + /// + /// Gets the application version as a object. + /// Version Version { get; } + /// + /// Gets the application build number. + /// string BuildString { get; } + /// + /// Open the settings menu or page for this application. + /// void ShowSettingsUI(); + /// + /// Gets the detected theme of the system or application. + /// + /// For platforms or platform versions which do not support themes, is returned. AppTheme RequestedTheme { get; } + /// + /// Gets whether this app is distributed as packaged or unpackaged. + /// + /// On other platforms than Windows, this will always return . AppPackagingModel PackagingModel { get; } + /// + /// Gets the requested layout direction of the system or application. + /// LayoutDirection RequestedLayoutDirection { get; } } - /// + /// + /// Represents information about the application. + /// public static class AppInfo { - /// + /// + /// Gets the application package name or identifier. + /// + /// On Android and iOS, this is the application package name. On Windows, this is the application GUID. public static string PackageName => Current.PackageName; - /// + /// + /// Gets the application name. + /// public static string Name => Current.Name; - /// + /// + /// Gets the application version as a string representation. + /// public static string VersionString => Current.VersionString; - /// + /// + /// Gets the application version as a object. + /// public static Version Version => Current.Version; - /// + /// + /// Gets the application build number. + /// public static string BuildString => Current.BuildString; - /// + /// + /// Open the settings menu or page for this application. + /// public static void ShowSettingsUI() => Current.ShowSettingsUI(); - /// + /// + /// Gets the detected theme of the system or application. + /// + /// For platforms or platform versions which do not support themes, is returned. public static AppTheme RequestedTheme => Current.RequestedTheme; + /// + /// Gets whether this app is distributed as packaged or unpackaged. + /// + /// On other platforms than Windows, this will always return . public static AppPackagingModel PackagingModel => Current.PackagingModel; + /// + /// Gets the requested layout direction of the system or application. + /// public static LayoutDirection RequestedLayoutDirection => Current.RequestedLayoutDirection; static IAppInfo? currentImplementation; + /// + /// Provides the default implementation for static usage of this API. + /// public static IAppInfo Current => currentImplementation ??= new AppInfoImplementation(); @@ -61,9 +122,15 @@ internal static void SetCurrent(IAppInfo? implementation) => currentImplementation = implementation; } + /// + /// Enumerates values that describe how a Windows app is packaged. + /// public enum AppPackagingModel { + /// The app is packaged and can be distributed through an MSIX or the store. Packaged, + + /// The app is unpcakged and can be distributed as a collection of executable files. Unpackaged, } } diff --git a/src/Essentials/src/AppInfo/AppInfo.uwp.cs b/src/Essentials/src/AppInfo/AppInfo.uwp.cs index fe438daa1894..525df3828d30 100644 --- a/src/Essentials/src/AppInfo/AppInfo.uwp.cs +++ b/src/Essentials/src/AppInfo/AppInfo.uwp.cs @@ -17,6 +17,9 @@ class AppInfoImplementation : IAppInfo readonly ActiveWindowTracker _activeWindowTracker; + /// + /// Intializes a new object with default values. + /// public AppInfoImplementation() { _activeWindowTracker = new(WindowStateManager.Default); @@ -107,11 +110,25 @@ static class AppInfoUtils return false; }); + /// + /// Gets if this app is a packaged app. + /// public static bool IsPackagedApp => _isPackagedAppLazy.Value; + /// + /// Converts a object to a object. + /// + /// The to convert. + /// A new object with the version information of this app. public static Version ToVersion(this PackageVersion version) => new Version(version.Major, version.Minor, version.Build, version.Revision); + /// + /// Gets the version information for this app. + /// + /// The assembly to retrieve the version information for. + /// The key that is used to retrieve the version information from the metadata. + /// if is or empty, or no version information could be found with the value of . public static Version GetAppInfoVersionValue(this Assembly assembly, string name) { if (assembly.GetAppInfoValue(name) is string value && !string.IsNullOrEmpty(value)) @@ -120,9 +137,21 @@ public static Version GetAppInfoVersionValue(this Assembly assembly, string name return null; } + /// + /// Gets the app info from this apps' metadata. + /// + /// The assembly to retrieve the app info for. + /// The key of the metadata to be retrieved (e.g. PackageName, PublisherName or Name). + /// The value that corresponds to the given key in . public static string GetAppInfoValue(this Assembly assembly, string name) => assembly.GetMetadataAttributeValue("Microsoft.Maui.ApplicationModel.AppInfo." + name); + /// + /// Gets the value for a given key from the assembly metadata. + /// + /// The assembly to retrieve the information for. + /// The key of the metadata to be retrieved (e.g. PackageName, PublisherName or Name). + /// The value that corresponds to the given key in . public static string GetMetadataAttributeValue(this Assembly assembly, string key) { foreach (var attr in assembly.GetCustomAttributes()) diff --git a/src/Essentials/src/AppInfo/AppTheme.shared.cs b/src/Essentials/src/AppInfo/AppTheme.shared.cs index e77f0306feaf..00e1e085f71e 100644 --- a/src/Essentials/src/AppInfo/AppTheme.shared.cs +++ b/src/Essentials/src/AppInfo/AppTheme.shared.cs @@ -1,13 +1,17 @@ namespace Microsoft.Maui.ApplicationModel { - /// + /// + /// Enumerates different themes an operating system or application can show. + /// public enum AppTheme { - /// + /// Default, unknown or unspecified theme. Unspecified, - /// + + /// Light theme. Light, - /// + + /// Dark theme. Dark } } diff --git a/src/Essentials/src/AppInfo/LayoutDirection.shared.cs b/src/Essentials/src/AppInfo/LayoutDirection.shared.cs index 65a08c53a33a..a912ebef6f1c 100644 --- a/src/Essentials/src/AppInfo/LayoutDirection.shared.cs +++ b/src/Essentials/src/AppInfo/LayoutDirection.shared.cs @@ -4,10 +4,18 @@ namespace Microsoft.Maui.ApplicationModel { + /// + /// Enumerates possible layout directions. + /// public enum LayoutDirection { + /// The requested layout direction is unknown. Unknown, + + /// The requested layout direction is left-to-right. LeftToRight, + + /// The requested layout direction is right-to-left. RightToLeft } } From 871c03453c1ce05d796a819fc5243887f3a22211 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Thu, 17 Nov 2022 09:42:23 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: E.Z. Hart --- src/Essentials/src/AppInfo/AppInfo.shared.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Essentials/src/AppInfo/AppInfo.shared.cs b/src/Essentials/src/AppInfo/AppInfo.shared.cs index 01dfcdce52d0..badcde29d1c8 100644 --- a/src/Essentials/src/AppInfo/AppInfo.shared.cs +++ b/src/Essentials/src/AppInfo/AppInfo.shared.cs @@ -46,7 +46,7 @@ public interface IAppInfo AppTheme RequestedTheme { get; } /// - /// Gets whether this app is distributed as packaged or unpackaged. + /// Gets the packaging model of this application. /// /// On other platforms than Windows, this will always return . AppPackagingModel PackagingModel { get; } @@ -100,7 +100,7 @@ public static class AppInfo public static AppTheme RequestedTheme => Current.RequestedTheme; /// - /// Gets whether this app is distributed as packaged or unpackaged. + /// Gets the packaging model of this application. /// /// On other platforms than Windows, this will always return . public static AppPackagingModel PackagingModel => Current.PackagingModel; @@ -123,7 +123,7 @@ internal static void SetCurrent(IAppInfo? implementation) => } /// - /// Enumerates values that describe how a Windows app is packaged. + /// Describes packaging options for a Windows app. /// public enum AppPackagingModel {