From 023ce3064ee391cff2e64ea6f0cdc8e269a6936d Mon Sep 17 00:00:00 2001 From: Dan Siegel Date: Tue, 15 Oct 2024 14:05:48 -0600 Subject: [PATCH] chore: update essentials and logging docs --- .vscode/settings.json | 3 +- docs/plugins/essentials/appcontext.md | 47 +++++++++++++++++++++ docs/plugins/essentials/battery.md | 5 +++ docs/plugins/essentials/connectivity.md | 13 ++++++ docs/plugins/essentials/index.md | 25 +++++++++-- docs/plugins/essentials/permissions.md | 2 +- docs/plugins/logging/index.md | 10 ++--- docs/plugins/logging/microsoft.md | 4 ++ docs/plugins/logging/raygun.md | 55 +++++++++++++++++++++++++ docs/plugins/logging/toc.yml | 2 +- 10 files changed, 155 insertions(+), 11 deletions(-) create mode 100644 docs/plugins/essentials/battery.md create mode 100644 docs/plugins/logging/raygun.md diff --git a/.vscode/settings.json b/.vscode/settings.json index de521b4..c9c39da 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,5 +1,6 @@ { "cSpell.words": [ - "MVVM" + "MVVM", + "Xunit" ] } \ No newline at end of file diff --git a/docs/plugins/essentials/appcontext.md b/docs/plugins/essentials/appcontext.md index 56bc979..3a9014d 100644 --- a/docs/plugins/essentials/appcontext.md +++ b/docs/plugins/essentials/appcontext.md @@ -3,3 +3,50 @@ uid: Plugins.Essentials.AppContext --- # AppContext + +The default implementation of the `IAppContext` interface is available by registering Prism Essentials or by specifically Registering the AppContext. + +```cs +containerRegistry.UsePrismEssentials(); + +// OR Specifically +containerRegistry.RegisterAppContext(); +``` + +## API + +```cs +public interface IAppContext +{ + string PackageName { get; } + + string Name { get; } + + string VersionString { get; } + + Version Version { get; } + + string BuildString { get; } + + void ShowSettingsUI(); + + AppTheme RequestedTheme { get; } + + AppPackagingModel PackagingModel { get; } + + LayoutDirection RequestedLayoutDirection { get; } +} +``` + +## Read the app information + +The IAppContext interface exposes the following properties: + +- Name — The application name. +- PackageName — The package name or application identifier, such as com.prismlibrary.myapp. +- VersionString — The application version, such as 1.0.0. +- Version — The application version, as a Version object. +- BuildString — The build number of the version, such as 1000. +- RequestedTheme — The detected theme of the system or application. +- PackagingModel — The packaging model of the application. +- RequestedLayoutDirection — The requested layout direction of the system or application. diff --git a/docs/plugins/essentials/battery.md b/docs/plugins/essentials/battery.md new file mode 100644 index 0000000..c72fc07 --- /dev/null +++ b/docs/plugins/essentials/battery.md @@ -0,0 +1,5 @@ +--- +uid: Plugins.Essentials.Battery +--- + +# Battery diff --git a/docs/plugins/essentials/connectivity.md b/docs/plugins/essentials/connectivity.md index 64cdc71..6b88311 100644 --- a/docs/plugins/essentials/connectivity.md +++ b/docs/plugins/essentials/connectivity.md @@ -3,3 +3,16 @@ uid: Plugins.Essentials.Connectivity --- # Connectivity + +## API + +```cs +public interface IConnectivity +{ + IEnumerable ConnectionProfiles { get; } + + NetworkAccess NetworkAccess { get; } + + IObservable State(); +} +``` diff --git a/docs/plugins/essentials/index.md b/docs/plugins/essentials/index.md index aa0d4f2..b35a727 100644 --- a/docs/plugins/essentials/index.md +++ b/docs/plugins/essentials/index.md @@ -8,7 +8,26 @@ Prism.Plugin.Essentials is built around the idea that you should be able to have The API is generally inspired by a combination of Xamarin/.NET MAUI Essentials and in the case of the [Stores](xref:Plugins.Essentials.Stores) is inspired by one of our favorite libraries [Shiny.NET](https://shinylib.net). -# [.NET MAUI](#tab/maui) +## [Xamarin.Forms](#tab/forms) + +Be sure to install `Prism.Plugin.Essentials.Forms` + +In PrismApplication be sure to add the following registration. + +```cs +protected override void RegisterTypes(IContainerRegistry containerRegistry) +{ + containerRegistry.UsePrismEssentials(); +} +``` + +For Android be sure to add the following to the native Android Application + +```cs +Prism.Plugin.Essentials.Platform.CurrentActivity.Init(this); +``` + +## [.NET MAUI](#tab/maui) Be sure to install `Prism.Plugin.Essentials.Maui` @@ -17,7 +36,7 @@ builder.UseMauiApp() .UsePrism(prism => prism.UsePrismEssentials()) ``` -# [WPF](#tab/wpf) +## [WPF](#tab/wpf) Be sure to install `Prism.Plugin.Essentials.Wpf` @@ -28,7 +47,7 @@ protected override void RegisterTypes(IContainerRegistry containerRegistry) } ``` -# [Uno Platform](#tab/uno-platform) +## [Uno Platform](#tab/uno-platform) Be sure to install `Prism.Plugin.Essentials.Uno.WinUI` diff --git a/docs/plugins/essentials/permissions.md b/docs/plugins/essentials/permissions.md index f447bff..077acbe 100644 --- a/docs/plugins/essentials/permissions.md +++ b/docs/plugins/essentials/permissions.md @@ -1,5 +1,5 @@ --- -uid: Plugins.Essentials.MainThread +uid: Plugins.Essentials.Permissions --- # App Permissions diff --git a/docs/plugins/logging/index.md b/docs/plugins/logging/index.md index cb1cbd5..904b90e 100644 --- a/docs/plugins/logging/index.md +++ b/docs/plugins/logging/index.md @@ -1,3 +1,7 @@ +--- +uid: Plugins.Logging +--- + # Prism.Plugin.Logging Available now to Commercial Plus license holders on the Prism NuGet feed. @@ -160,11 +164,7 @@ For more information see the [Microsoft.Extensions.Logging Interoperability docs ### Raygun -```cs -containerRegistry.UsePrismLogging(logging => { - logging.AddRaygun("RaygunApiKey"); -}); -``` +For more information see the [Prism Logging docs for Raygun](xref:Plugins.Logging.Raygun). ### Sentry diff --git a/docs/plugins/logging/microsoft.md b/docs/plugins/logging/microsoft.md index adbf688..cf4a3f4 100644 --- a/docs/plugins/logging/microsoft.md +++ b/docs/plugins/logging/microsoft.md @@ -1,3 +1,7 @@ +--- +uid: Plugins.Logging.Microsoft +--- + # Microsoft.Extensions.Logging Interop We recognize that your apps (particularly .NET MAUI and Uno Platform), may have logging that occurs internally using Microsoft.Extensions.Logging. For this reason we've taken the time to put together a logging adapter that allows the logging output from the Microsoft.Extensions.Logging.ILogger to be passed through to the configured Prism Logging Providers that you have in your application. While the exact code may vary diff --git a/docs/plugins/logging/raygun.md b/docs/plugins/logging/raygun.md new file mode 100644 index 0000000..698639e --- /dev/null +++ b/docs/plugins/logging/raygun.md @@ -0,0 +1,55 @@ +--- +uid: Plugins.Logging.Raygun +--- + +# Prism Logging with Raygun + +Raygun is a platform that offers analytics about managed and unmanaged exceptions within your app as well as user tracking. + +```cs +containerRegistry.UsePrismLogging(logging => { + logging.AddRaygun("RaygunApiKey"); +}); +``` + +## Local Development & Debugging + +Raygun offers a free Open Source version for Crash Detection that can be run in a local environment. For more information see the [Raygun Documentation](https://raygun.com/documentation/product-guides/crash-reporting/local-docker-setup/). + +To get started you can copy the following docker compose sample. You can set the localpath for the volumes to persist the crash data over time and ensure that the downloaded Ollama models are persisted and do not need to be downloaded again. + +```docker +version: '3.8' + +services: + raygun-aspire-portal: + image: raygunowner/raygun-aspire-portal:latest + container_name: raygun_local_dev + environment: + - ConnectionStrings__Ollama=http://ollama-service:11434 + ports: + - "8080:8080" + restart: always + volumes: + - /localpath/raygun/errors:/app/raygun/errors + depends_on: + - ollama-service # Ensure Ollama service starts before this container + + ollama-service: + image: ollama/ollama:latest + container_name: ollama_local_aier + restart: always + volumes: + - /localpath/ollama:/root/.ollama # Mount local directory to container for data persistence +``` + +To use Raygun for local development with your Docker image, you can use the special extension as shown below: + +```cs +container.UsePrismLogging(logging => + logging.AddLocalRaygun("http://192.168.1.11:8080/Ingestion/Entries")); +``` + +## Prism.Essentials Integration + +The Raygun Implementation of the Logger makes reference to the [Prism.Plugin.Essentials](xref:Plugins.Essentials.GettingStarted) library. This allows us to dynamically check if various Essentials interfaces have been registered. If they have we automatically tailor the Logger to include offline support with request caching. Additionally we will automatically update the configuration to make use of the [Application Context](xref:Plugins.Essentials.AppContext) from Essentials. diff --git a/docs/plugins/logging/toc.yml b/docs/plugins/logging/toc.yml index e91aef1..c3a325c 100644 --- a/docs/plugins/logging/toc.yml +++ b/docs/plugins/logging/toc.yml @@ -5,4 +5,4 @@ - name: Microsoft Extensions href: microsoft.md - name: Unit Testing - href: unit-testing.md \ No newline at end of file + href: testing.md \ No newline at end of file