From 12acb797917da602a2837a6a6fa48947ed3c8db9 Mon Sep 17 00:00:00 2001 From: Dan Siegel Date: Tue, 26 Nov 2019 19:56:55 -0800 Subject: [PATCH] doc updates --- .gitignore | 5 ++- README.md | 17 +++----- docs/.nojekyll | 0 docs/forms/index.md | 14 +++--- docs/forms/navigationerrors.md | 1 + docs/forms/pagebehaviorfactory.md | 25 +++++++++++ docs/index.md | 13 +++--- docs/registerdelegates.md | 52 ++++++++++++++++++++++ docs/registermany.md | 72 +++++++++++++++++++++++++++++++ docs/scoping.md | 3 ++ mkdocs.yml | 42 ++++++++++++------ 11 files changed, 209 insertions(+), 35 deletions(-) create mode 100644 docs/.nojekyll create mode 100644 docs/forms/navigationerrors.md create mode 100644 docs/forms/pagebehaviorfactory.md create mode 100644 docs/registerdelegates.md create mode 100644 docs/registermany.md create mode 100644 docs/scoping.md diff --git a/.gitignore b/.gitignore index e164477..a4a15c9 100644 --- a/.gitignore +++ b/.gitignore @@ -265,4 +265,7 @@ secrets.json appsettings.json # MFractor -.mfractor/ \ No newline at end of file +.mfractor/ + +# MkDocs Generated Site +site/ \ No newline at end of file diff --git a/README.md b/README.md index 6f7ee53..e004d5e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Prism.Container.Extensions -The Prism Container Extensions provide various additional extensions making the Prism Container easier to use with Splat, IServiceCollection/IServiceProvider and in scenarios where you may require a Singleton container that may need to be initialized from Platform specific code prior to PrismApplication being created. Note that both the Prism.Container.Extensions and Prism.DryIoc.Extensions are platform agnostic meaning you can use them on WPF or Xamarin Forms. +The Prism Container Extensions provide various additional extensions making the Prism Container easier to use with IServiceCollection/IServiceProvider and in scenarios where you may require a Singleton container that may need to be initialized from Platform specific code prior to PrismApplication being created. Note that both the Prism.Container.Extensions and Prism.DryIoc.Extensions are platform agnostic meaning you can use them on WPF or Xamarin Forms. For more information be sure to check out the docs at [prismplugins.com](https://prismplugins.com) @@ -18,15 +18,12 @@ You can add the MyGet CI feed to nuget by adding it as a source in Visual Studio | Package | NuGet | MyGet | |-------|:-----:|:------:| -| Prism.Container.Extensions | [![ContainerExtensionsShield]][ContainerExtensionsNuGet] | [![ContainerExtensionsMyGetShield]][ContainerExtensionsMyGet] | -| Prism.Forms.Extended | [![PrismFormsExtendedShield]][PrismFormsExtendedNuGet] | [![PrismFormsExtendedMyGetShield]][PrismFormsExtendedMyGet] | -| Prism.DryIoc.Extensions | [![DryIocExtensionsShield]][DryIocExtensionsNuGet] | [![DryIocExtensionsMyGetShield]][DryIocExtensionsMyGet] | -| Prism.DryIoc.Forms.Extended | [![DryIocFormsExtendedShield]][DryIocFormsExtendedNuGet] | [![DryIocFormsExtendedMyGetShield]][DryIocFormsExtendedMyGet] | -| Prism.Microsoft.DependencyInjection.Extensions | [![MsftDependencyInjectionExtensionsShield]][MsftDependencyInjectionExtensionsNuGet] | [![MsftDependencyInjectionExtensionsMyGetShield]][MsftDependencyInjectionExtensionsMyGet] | -| Prism.Microsoft.DependencyInjection.Forms.Extended | [![MsftDependencyInjectionFormsExtendedShield]][MsftDependencyInjectionFormsExtendedNuGet] | [![MsftDependencyInjectionFormsExtendedMyGetShield]][MsftDependencyInjectionFormsExtendedMyGet] | -| Prism.Unity.Extensions | [![UnityExtensionsShield]][UnityExtensionsNuGet] | [![UnityExtensionsMyGetShield]][UnityExtensionsMyGet] | -| Prism.Unity.Forms.Extended | [![UnityFormsExtendedShield]][UnityFormsExtendedNuGet] | [![UnityFormsExtendedMyGetShield]][UnityFormsExtendedMyGet] | -| Shiny.Prism | [![ShinyPrismShield]][ShinyPrismNuGet] | [![ShinyPrismMyGetShield]][ShinyPrismMyGet] | +| Prism.Container.Extensions | [![Latest NuGet][ContainerExtensionsShield]][ContainerExtensionsNuGet] | [![Latest CI Package][ContainerExtensionsMyGetShield]][ContainerExtensionsMyGet] | +| Prism.Forms.Extended | [![Latest NuGet][PrismFormsExtendedShield]][PrismFormsExtendedNuGet] | [![Latest CI Package][PrismFormsExtendedMyGetShield]][PrismFormsExtendedMyGet] | +| Prism.DryIoc.Extensions | [![Latest NuGet][DryIocExtensionsShield]][DryIocExtensionsNuGet] | [![Latest CI Package][DryIocExtensionsMyGetShield]][DryIocExtensionsMyGet] | +| Prism.Microsoft.DependencyInjection.Extensions | [![Latest NuGet][MsftDependencyInjectionExtensionsShield]][MsftDependencyInjectionExtensionsNuGet] | [![Latest CI Package][MsftDependencyInjectionExtensionsMyGetShield]][MsftDependencyInjectionExtensionsMyGet] | +| Prism.Unity.Extensions | [![Latest NuGet][UnityExtensionsShield]][UnityExtensionsNuGet] | [![Latest CI Package][UnityExtensionsMyGetShield]][UnityExtensionsMyGet] | +| Shiny.Prism | [![Latest NuGet][ShinyPrismShield]][ShinyPrismNuGet] | [![Latest CI Package][ShinyPrismMyGetShield]][ShinyPrismMyGet] | ## Support diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/forms/index.md b/docs/forms/index.md index 6828a84..39801c3 100644 --- a/docs/forms/index.md +++ b/docs/forms/index.md @@ -1,6 +1,6 @@ -## Using the Prism.DryIoc.Forms.Extended +## Using the Prism.Forms.Extended -The Prism.DryIoc.Forms.Extended package is designed to make it even easier for you to integrate these fantastic packages. As you'll see using it is identical in every way to creating a typical Prism Application. The only difference is that you are installing the Prism.DryIoc.Forms.Extended package instead of Prism.DryIoc.Forms. +The Prism.Forms.Extended package is designed to make it even easier for you to integrate these fantastic packages. As you'll see using it is identical in every way to creating a typical Prism Application. The only difference is that you are installing the Prism.Forms.Extended package instead of Prism.Forms, Prism.DryIoc.Forms or Prism.Unity.Forms. ```xml true; + + public bool UseSafeArea => true; + + public bool UseChildTitle => true; + + public bool PreferLargeTitles => true; +} +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index e279d32..c0e945d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,16 @@ # Prism.Container.Extensions -The Prism Container Extensions provide various additional extensions making the Prism Container easier to use with Splat, IServiceCollection/IServiceProvider and in scenarios where you may require a Singleton container that may need to be initialized from Platform specific code prior to PrismApplication being created. Note that both the Prism.Container.Extensions and Prism.DryIoc.Extensions are platform agnostic meaning you can use them on WPF or Xamarin Forms. +The Prism Container Extensions provide various additional extensions making the Prism Container easier to use with IServiceCollection/IServiceProvider and in scenarios where you may require a Singleton container that may need to be initialized from Platform specific code prior to PrismApplication being created. Note that both the Prism.Container.Extensions and Prism.DryIoc.Extensions are platform agnostic meaning you can use them on WPF or Xamarin Forms. ## Support -This project is maintained by Dan Siegel. If this project or others maintained by Dan have helped you please help support the project by [sponsoring Dan](https://xam.dev/sponsor-prism-logging) on GitHub! +This project is maintained by Dan Siegel. If this project or others maintained by Dan have helped you please help support the project by [sponsoring Dan](https://xam.dev/sponsor-container-extensions) on GitHub! -[![GitHub Sponsors](https://github.blog/wp-content/uploads/2019/05/mona-heart-featured.png?fit=600%2C315)](https://xam.dev/sponsor-prism-logging) +[![GitHub Sponsors](https://github.blog/wp-content/uploads/2019/05/mona-heart-featured.png?fit=600%2C315)](https://xam.dev/sponsor-container-extensions) + +## Why use the Container Extensions? + +While the Container abstractions provided by `IContainerRegistry` will give you what you need at least 95% of the time, there are still a number of times that you need to be able to do some more advanced registrations for your services. While adding these additional methods may confuse the average developer who is still struggling to understand "What is a Transient, what is a Singleton, when do I use each?". The extensions give you exactly what you need in order to write extremely loosely coupled code that can be reused from one project to another regardless of whether you are developing for Prism for WPF, Prism for Xamarin.Forms or just doing your own thing with Prism.Core. ## NuGet @@ -15,11 +19,8 @@ This project is maintained by Dan Siegel. If this project or others maintained b | Prism.Container.Extensions | [![Latest NuGet][ContainerExtensionsShield]][ContainerExtensionsNuGet] | [![Latest CI Package][ContainerExtensionsMyGetShield]][ContainerExtensionsMyGet] | | Prism.Forms.Extended | [![Latest NuGet][PrismFormsExtendedShield]][PrismFormsExtendedNuGet] | [![Latest CI Package][PrismFormsExtendedMyGetShield]][PrismFormsExtendedMyGet] | | Prism.DryIoc.Extensions | [![Latest NuGet][DryIocExtensionsShield]][DryIocExtensionsNuGet] | [![Latest CI Package][DryIocExtensionsMyGetShield]][DryIocExtensionsMyGet] | -| Prism.DryIoc.Forms.Extended | [![Latest NuGet][DryIocFormsExtendedShield]][DryIocFormsExtendedNuGet] | [![Latest CI Package][DryIocFormsExtendedMyGetShield]][DryIocFormsExtendedMyGet] | | Prism.Microsoft.DependencyInjection.Extensions | [![Latest NuGet][MsftDependencyInjectionExtensionsShield]][MsftDependencyInjectionExtensionsNuGet] | [![Latest CI Package][MsftDependencyInjectionExtensionsMyGetShield]][MsftDependencyInjectionExtensionsMyGet] | -| Prism.Microsoft.DependencyInjection.Forms.Extended | [![Latest NuGet][MsftDependencyInjectionFormsExtendedShield]][MsftDependencyInjectionFormsExtendedNuGet] | [![Latest CI Package][MsftDependencyInjectionFormsExtendedMyGetShield]][MsftDependencyInjectionFormsExtendedMyGet] | | Prism.Unity.Extensions | [![Latest NuGet][UnityExtensionsShield]][UnityExtensionsNuGet] | [![Latest CI Package][UnityExtensionsMyGetShield]][UnityExtensionsMyGet] | -| Prism.Unity.Forms.Extended | [![Latest NuGet][UnityFormsExtendedShield]][UnityFormsExtendedNuGet] | [![Latest CI Package][UnityFormsExtendedMyGetShield]][UnityFormsExtendedMyGet] | | Shiny.Prism | [![Latest NuGet][ShinyPrismShield]][ShinyPrismNuGet] | [![Latest CI Package][ShinyPrismMyGetShield]][ShinyPrismMyGet] | ### CI NuGet Feed diff --git a/docs/registerdelegates.md b/docs/registerdelegates.md new file mode 100644 index 0000000..4acfd86 --- /dev/null +++ b/docs/registerdelegates.md @@ -0,0 +1,52 @@ +# Delegate Registration + +Sometimes you really need a bit more power behind constructing a service. For these times you may find yourself in one of the following scenarios: + +- You just need to perform some Action like: + +```c# +public static IBackendService CreateBackendService() +{ + return new BackendService + { + Uri = Constants.BackendUri + }; +} +``` + +- You need to resolve something to do a more complex look up and properly construct your type: + +```c# +public static IBackendService CreateBackendService(IContainerProvider containerProvider) +{ + var options = containerProvider.Resolve(); + return containerProvider.Resolve((typeof(Uri), options.BackendUri)); +} +``` + +!!! note "Note" + This supports both Delegates with `IContainerProvider` and `IServiceProvider` + +Regardless of which way you need to resolve service the Delegate Registration extensions really help out for those scenarios where you can't just simply pass a raw implementing type. + +```c# +protected override void RegisterTypes(IContainerRegistry containerRegistry) +{ + containerRegistry.RegisterDelegate(FooFactory); + containerRegistry.RegisterDelegate(BarFactory); +} + +private static IFoo FooFactory() => new Foo(); + +private static IBar BarFactory(IContainerProvider container) +{ + var options = container.Resolve(); + return new Bar { HasCode = options.HasCode }; +} + +private static IBar BarFactory(IServiceProvider serviceProvider) +{ + var options = serviceProvider.GetService(); + return new Bar { HasCode = options.HasCode }; +} +``` \ No newline at end of file diff --git a/docs/registermany.md b/docs/registermany.md new file mode 100644 index 0000000..6767d7c --- /dev/null +++ b/docs/registermany.md @@ -0,0 +1,72 @@ +# RegisterMany + +One of the very powerful new methods provided by the Container Extensions is the `RegisterMany` and `RegisterManySingleton` method. This really can help you reduce how much boilerplate code you need to write and provide some advanced scenarios. So what is it? + +```c# +public interface IFoo +{ + void DoFoo(); +} + +public interface IBar +{ + void DoBar(); +} +``` + +To start let's assume that you have 2 interfaces like the ones above `IFoo` and `IBar`. Now let's assume that you have a single implementing type like: + +```c# +public class FooBar : IFoo, IBar +{ + + public void DoFoo() + { + Console.WriteLine("Doing foo"); + } + + public void DoBar() + { + Console.WriteLine("Doing Bar"); + } +} +``` + +Without the Container Extensions you might have a transient registration like: + +```c# +containerRegistry.Register(); +containerRegistry.Register(); +``` + +While this may not be such a big deal, it suddenly starts making more sense when we expect the use of a singleton. The issue here is that if we were to do something similar to this to register a Singleton traditionally like: + +```c# +containerRegistry.RegisterSingleton(); +containerRegistry.RegisterSingleton(); +``` + +We are under the impression that we have a singleton here. The issue of course is that if you check for equality like: + +```c# +if(Container.Resolve() == Container.Resolve()) +{ + Console.WriteLine("Foo and Bar are the same instance"); +} +else +{ + Console.WriteLine("Foo and Bar are difference instances"); +} +``` + +We might expect that the first case would evaluate to true that Foo and Bar are the same instance, but in reality they are two different instances. The issue isn't that we somehow didn't register them as a singleton because if you resolve IFoo twice and do the same equality check it will actually evaluate to true because they would be the same instance. However, Foo and Bar are different instances because they were registered separately. This is where `RegisterManySingleton` really shines. If we were to update our registration like: + +```c# +// Implicitly registers any implemented interfaces +containerRegistry.RegisterManySingleton(); + +// Explicitly registers implemented interfaces +containerRegistry.RegisterManySingleton(typeof(IFoo), typeof(IBar)) +``` + +We can now perform the same equality check above only this time `IFoo` and `IBar` would equal one another because they would both have been resolved from the same instance of the `FooBar` implementation. diff --git a/docs/scoping.md b/docs/scoping.md new file mode 100644 index 0000000..e44eee2 --- /dev/null +++ b/docs/scoping.md @@ -0,0 +1,3 @@ +# Scoping + +TODO \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c8f0aa1..9126e7e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,7 @@ theme: favicon: assets/favicon.ico language: en feature: - tabs: false + tabs: true palette: primary: 'white' accent: 'cyan' @@ -50,15 +50,31 @@ markdown_extensions: permalink: true nav: - - Getting Started: index.md - - Containers: - - Basics: containers/index.md - - DryIoc: containers/dryioc.md - - Microsoft D.I. Extensions: containers/microsoft-extensions-dependencyinjection.md - - Unity: containers/unity.md - - Prism.Forms Extended: - - Intro: forms/index.md - - Shiny Support: - - Intro: shiny/index.md - - Modularity: shiny/modularity.md - - Navigation: shiny/navigation.md \ No newline at end of file + - Prism: + - Prism Library: http://prismlibrary.github.io/docs + - Logging: + - Logging: http://logging.prismplugins.com + - Popups: + - Popups: http://popups.prismplugins.com + - Container Extensions: + - Getting Started: index.md + - RegisterMany: registermany.md + - Delegate Registration: registerdelegates.md + - Scoped Services: scoping.md + - Containers: + - Basics: containers/index.md + - DryIoc: containers/dryioc.md + - Microsoft D.I. Extensions: containers/microsoft-extensions-dependencyinjection.md + - Unity: containers/unity.md + - Prism.Forms Extended: + - Intro: forms/index.md + - Page Behavior Factory: forms/pagebehaviorfactory.md + - Global Navigation Error: forms/navigationerrors.md + - Shiny Support: + - Intro: shiny/index.md + - Modularity: shiny/modularity.md + - Navigation: shiny/navigation.md + - Mobile.BuildTools: + - Mobile.BuildTools: http://mobilebuildtools.com + +google_analytics: ['UA-153405647-1', 'Prism.Container.Extensions'] \ No newline at end of file