Merge pull request #4 from MindscapeHQ/ht/extending-environment-message

[PS-97]: Extend RaygunEnvironmentMessage to add Maui specific information.

README.md

@@ -6,7 +6,7 @@ Raygun's Crash Reporting provider for .NET MAUI
 
 ### Step 1 - Install Raygun4Maui
 
-#### Nuget Package manager
+#### NuGet Package manager
 The best way to install Raygun is to use the NuGet package manager. Right-click on your project and select "**Manage NuGet Packages....**". Navigate to the Browse tab, then use the search box to find **Raygun4Maui** and install it.
 
 #### .NET Cli
@@ -16,9 +16,9 @@ To install the latest version:
 dotnet add package Raygun4Maui
 ```
 
-Alternatively you can specify a version tag to install a specific version of the package, see [Raygun4Maui NuGet Gallery page](https://nuget.org/packages/Raygun4Maui) for information of versions. 
+Alternatively, you can specify a version tag to install a specific version of the package. See [Raygun4Maui NuGet Gallery page](https://nuget.org/packages/Raygun4Maui) for information on available versions.
 ```
-dotnet add package Raygun4Maui --version 1.0.0
+dotnet add package Raygun4Maui --version 1.2.1
 ```
 
 ### Step 2 - Add Raygun4Maui to your MauiApp builder
@@ -54,10 +54,10 @@ To use these additional configurations, create and initialize a new `RaygunMauiS
 ``` csharp
 Raygun4MauiSettings raygunMauiSettings = new Raygun4MauiSettings {
     ApiKey = "paste_your_api_key_here",
-    SendDefaultTags = true, // Default value
-    SendDefaultCustomData = true, // Default value
-    MinLogLevel = LogLevel.Debug, // Default value
-    MaxLogLevel = LogLevel.Critical // Default value
+    SendDefaultTags = true, // defaults to true
+    SendDefaultCustomData = true, // defaults to true
+    MinLogLevel = LogLevel.Debug, // defaults to true
+    MaxLogLevel = LogLevel.Critical // defaults to true
 };
 ```
 
@@ -76,17 +76,17 @@ builder
 
 Unhandled exceptions will be sent to Raygun automatically.
 
-Raygun4Maui stores an instance of a [Raygun4Net](https://github.com/MindscapeHQ/raygun4net/tree/master/Mindscape.Raygun4Net.NetCore). `RaygunClient` object, this can be accessed through the following code:
+Raygun4Maui stores an instance of a `RaygunMauiClient` object that is initialized by the Maui builder, this can be accessed through the following code:
 ``` csharp
 RaygunMauiClient.Current
 ```
 
-Any features supported by the Raygun4Net Client are accessible here
+This client extends the Raygun4Net.NetCore `RaygunClient`, as a result any features supported by the Raygun4Net.NetCore Client are supported here. 
 
 ---
 
 ### Manually sending exceptions
-Raygun4Maui automatically sends unhandled exceptions. For manual sending, use Send or SendInBackground methods, as shown below:
+Raygun4Maui automatically sends unhandled exceptions. For manual sending, use `Send` or `SendInBackground` methods, as shown below:
 
 ``` csharp
 try {   
@@ -101,26 +101,26 @@ try {
 An exception needs to be thrown in order for its stack trace to be populated. If the exception is created manually no stack trace data is collected. 
 
 ### Other examples
-For aditional examples on how to use the Raygun4Net client object refer to its deticated instructions [here](https://github.com/MindscapeHQ/raygun4net/tree/master/Mindscape.Raygun4Net.NetCore)
-
+For additional examples on how to use the `RaygunMauiClient` object refer to the [Raygun4Net.NetCore  documentation](https://raygun.com/documentation/language-guides/dotnet/crash-reporting/net-core/)
 ## ILogger logging
+Raygun4Maui will automatically send any logger logs to Raygun.
 
-To make a log entry, acquire the reference to the ILogger services that your MAUI app maintains:
+To make a log entry, obtain the reference to the ILogger services that your MAUI app maintains:
 
-``` c#
+``` csharp
 ILogger logger = Handler.MauiContext.Services.GetService<ILogger<MainPage>>();
 ```
 
-You may now invoke the various ILogger log methods from the logger object accordingly. This uses the same `RaygunClient` object accessible from RaygunMauiClient.Current
+You may now use the appropriate ILogger log method from the logger object. This uses the same `RaygunMauiClient` object accessible from `RaygunMauiClient.Current`
 
-```c#
+```csharp
 logger.LogInformation("Raygun4Maui.SampleApp.TestLoggerErrorsSent: {MethodName} @ {Timestamp}", "TestLogInformation", DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss"));
 logger.LogCritical("Raygun4Maui.SampleApp.TestLoggerErrorsSent: {MethodName} @ {Timestamp}", "TestLogCritical", DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss"));
 ```
 
-With this functionality, you can also manually catch-and-log exceptions as follows:
+This functionality also allows you to manually catch and log exceptions as shown below:
 
-``` c#
+``` csharp
 try {
     // Code that throws exception
 } catch (Exception e) {
@@ -130,7 +130,20 @@ try {
 ```
 
 ---
+## Platform specific information
+Raygun4Maui will automatically collect information specific to the environment the application is being run in. However, there are inconsistencies between certain values across platforms.
+- on iOS, Raygun4Maui cannot obtain the device's name. This is a privacy restriction put in place by Apple. If you would like this information to be collected and sent with crash reports you will have to [request for permission from apple](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_device-information_user-assigned-device-name?language=objc).
+- The `Total physical memory` and `Available physical memory` properties mean different things across platforms. Below is a table explaining the differences for each platform.  
 
+| Platform | Total physical memory | Available physical memory |
+| ----- | ---- | ------- |
+| Mac  | Total installed ram | Total memory available for user-level processes  |
+| iOS | Total installed ram | Total memory available for user-level processes |
+| Windows |Total installed ram | Total amount of private memory used by the process at the time of the measurement. For a number of reasons this might not be the actual total memory usage |
+| Android |Total amount of memory that the JVM has allocated for the application | Total amount of free memory that the JVM has available for the application to use | 
+
+
+---
 ## Development Instructions
 
 ### To build a local nuget package

Raygun4Maui.SampleApp/MauiProgram.cs

@@ -1,12 +1,11 @@
 using Microsoft.Extensions.Configuration;
-using Raygun4Maui;
 
 namespace Raygun4Maui.SampleApp;
 
 public static class MauiProgram
 {
-	public static MauiApp CreateMauiApp()
-	{
+    public static MauiApp CreateMauiApp()
+    {
         var configuration = new ConfigurationBuilder()
        .AddUserSecrets<MainPage>()
        .Build();
@@ -22,8 +21,7 @@ public static MauiApp CreateMauiApp()
             {
                 fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                 fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
-            }).AddRaygun4Maui(apiKey) ;
-
-        return builder.Build();
-	}
+            }).AddRaygun4Maui(apiKey);
+        return builder.Build();    
+    }
 }

Raygun4Maui.SampleApp/Raygun4Maui.SampleApp.csproj

@@ -85,7 +85,10 @@
 	  <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="7.0.0" />
 	  <PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.1" />
 	  <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="7.0.0" />
-	  <PackageReference Include="Raygun4Maui" Version="1.1.0" />
+	</ItemGroup>
+
+	<ItemGroup>
+	  <ProjectReference Include="..\Raygun4Maui\Raygun4Maui.csproj" />
 	</ItemGroup>
 
 </Project>

Raygun4Maui.Test/AppShell.xaml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<Shell
+    x:Class="Raygun4Maui.testtest.AppShell"
+    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+    xmlns:local="clr-namespace:Raygun4Maui.testtest"
+    Shell.FlyoutBehavior="Disabled">
+
+    <ShellContent
+        Title="Home"
+        ContentTemplate="{DataTemplate local:MainPage}"
+        Route="MainPage" />
+
+</Shell>

Raygun4Maui.Test/AppShell.xaml.cs

@@ -0,0 +1,10 @@
+namespace Raygun4Maui.testtest
+{
+    public partial class AppShell : Shell
+    {
+        public AppShell()
+        {
+            InitializeComponent();
+        }
+    }
+}

Raygun4Maui.Test/MainPage.xaml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+             x:Class="Raygun4Maui.testtest.MainPage">
+
+    <ScrollView>
+        <VerticalStackLayout
+            Spacing="25"
+            Padding="30,0"
+            VerticalOptions="Center">
+
+            <Image
+                Source="dotnet_bot.png"
+                SemanticProperties.Description="Cute dot net bot waving hi to you!"
+                HeightRequest="200"
+                HorizontalOptions="Center" />
+
+            <Label
+                Text="Hello, World!"
+                SemanticProperties.HeadingLevel="Level1"
+                FontSize="32"
+                HorizontalOptions="Center" />
+
+            <Label
+                Text="Welcome to .NET Multi-platform App UI"
+                SemanticProperties.HeadingLevel="Level2"
+                SemanticProperties.Description="Welcome to dot net Multi platform App U I"
+                FontSize="18"
+                HorizontalOptions="Center" />
+
+            <Button
+                x:Name="CounterBtn"
+                Text="Click me"
+                SemanticProperties.Hint="Counts the number of times you click"
+                Clicked="OnCounterClicked"
+                HorizontalOptions="Center" />
+
+        </VerticalStackLayout>
+    </ScrollView>
+
+</ContentPage>

Raygun4Maui.Test/MainPage.xaml.cs

@@ -0,0 +1,24 @@
+namespace Raygun4Maui.testtest
+{
+    public partial class MainPage : ContentPage
+    {
+        int count = 0;
+
+        public MainPage()
+        {
+            InitializeComponent();
+        }
+
+        private void OnCounterClicked(object sender, EventArgs e)
+        {
+            count++;
+
+            if (count == 1)
+                CounterBtn.Text = $"Clicked {count} time";
+            else
+                CounterBtn.Text = $"Clicked {count} times";
+
+            SemanticScreenReader.Announce(CounterBtn.Text);
+        }
+    }
+}

Raygun4Maui.Test/MauiProgram.cs

@@ -0,0 +1,19 @@
+using Xunit.Runners.Maui;
+
+namespace Raygun4Maui.testtest
+{
+    public static class MauiProgram
+    {
+        public static MauiApp CreateMauiApp() => MauiApp
+             .CreateBuilder()
+             .ConfigureTests(new TestOptions
+             {
+                 Assemblies =
+                 {
+                    typeof(MauiProgram).Assembly
+                 }
+             })
+             .UseVisualRunner()
+             .Build();
+    }
+}

Raygun4Maui.Test/Platforms/Android/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+	<application android:allowBackup="true" android:icon="@mipmap/appicon" android:roundIcon="@mipmap/appicon_round" android:supportsRtl="true"></application>
+	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+	<uses-permission android:name="android.permission.INTERNET" />
+</manifest>

Raygun4Maui.Test/Platforms/Android/MainActivity.cs

@@ -0,0 +1,11 @@
+using Android.App;
+using Android.Content.PM;
+using Android.OS;
+
+namespace Raygun4Maui.testtest
+{
+    [Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
+    public class MainActivity : MauiAppCompatActivity
+    {
+    }
+}

Raygun4Maui.Test/Platforms/Android/MainApplication.cs

@@ -0,0 +1,16 @@
+using Android.App;
+using Android.Runtime;
+
+namespace Raygun4Maui.testtest
+{
+    [Application]
+    public class MainApplication : MauiApplication
+    {
+        public MainApplication(IntPtr handle, JniHandleOwnership ownership)
+            : base(handle, ownership)
+        {
+        }
+
+        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
+    }
+}

Raygun4Maui.Test/Platforms/Android/Resources/values/colors.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="colorPrimary">#512BD4</color>
+    <color name="colorPrimaryDark">#2B0B98</color>
+    <color name="colorAccent">#2B0B98</color>
+</resources>

Raygun4Maui.Test/Platforms/MacCatalyst/AppDelegate.cs

@@ -0,0 +1,10 @@
+using Foundation;
+
+namespace Raygun4Maui.testtest
+{
+    [Register("AppDelegate")]
+    public class AppDelegate : MauiUIApplicationDelegate
+    {
+        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
+    }
+}

Raygun4Maui.Test/Platforms/MacCatalyst/Info.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>UIDeviceFamily</key>
+	<array>
+		<integer>1</integer>
+		<integer>2</integer>
+	</array>
+	<key>UIRequiredDeviceCapabilities</key>
+	<array>
+		<string>arm64</string>
+	</array>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+	<key>UISupportedInterfaceOrientations~ipad</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+	<key>XSAppIconAssets</key>
+	<string>Assets.xcassets/appicon.appiconset</string>
+</dict>
+</plist>

Raygun4Maui.Test/Platforms/MacCatalyst/Program.cs

@@ -0,0 +1,16 @@
+using ObjCRuntime;
+using UIKit;
+
+namespace Raygun4Maui.testtest
+{
+    public class Program
+    {
+        // This is the main entry point of the application.
+        static void Main(string[] args)
+        {
+            // if you want to use a different Application Delegate class from "AppDelegate"
+            // you can specify it here.
+            UIApplication.Main(args, null, typeof(AppDelegate));
+        }
+    }
+}

Raygun4Maui.Test/Platforms/Tizen/Main.cs

@@ -0,0 +1,17 @@
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+using System;
+
+namespace Raygun4Maui.testtest
+{
+    internal class Program : MauiApplication
+    {
+        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
+
+        static void Main(string[] args)
+        {
+            var app = new Program();
+            app.Run(args);
+        }
+    }
+}