Skip to content

Commit

Permalink
doc updates
Browse files Browse the repository at this point in the history
  • Loading branch information
dansiegel committed Nov 27, 2019
1 parent 17ba379 commit 12acb79
Show file tree
Hide file tree
Showing 11 changed files with 209 additions and 35 deletions.
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -265,4 +265,7 @@ secrets.json
appsettings.json

# MFractor
.mfractor/
.mfractor/

# MkDocs Generated Site
site/
17 changes: 7 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)

Expand All @@ -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

Expand Down
Empty file added docs/.nojekyll
Empty file.
14 changes: 9 additions & 5 deletions docs/forms/index.md
Original file line number Diff line number Diff line change
@@ -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
<prism:PrismApplication xmlns="http://xamarin.com/schemas/2014/forms"
Expand All @@ -27,12 +27,16 @@ public partial class App
}
```

### Why use Prism.DryIoc.Forms.Extended
!!! danger "Critical Notice"
The Prism Application in `Prism.Forms.Extended` requires the use of a container implementation from the Prism.Container.Extensions project. It will automatically wire in any reference without any changes to code. You simple need to ensure that Prism.DryIoc.Extensions, Prism.Microsoft.DependencyInjection.Extensions, or Prism.Unity.Extensions is installed.

### Why use Prism.Forms.Extended

The extended PrismApplication is cross compiled for Xamarin.iOS and Xamarin.Android and provides several out of the box improvements over the normal PrismApplication.

- It includes the `ILogger` from [Prism.Plugin.Logging](https://github.com/dansiegel/Prism.Plugin.Logging)
- It has pre-wired support for logging XAML errors and other issues directly from Xamarin.Forms
- It includes the `ILogger` from [Prism.Plugin.Logging](http://logging.prismplugins.com)
- By default the Console Logger is registered and is available.
- It has pre-wired support for logging XAML errors and other issues directly from Xamarin.Forms (It will use your ILogger to log things like Bindings that cannot be resolved)
- Becase it is cross compiled, it has global Exception Handling built in for:
- AndroidEnvironment
- ObjectiveC.Runtime
Expand Down
1 change: 1 addition & 0 deletions docs/forms/navigationerrors.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Errors happen when navigating.
25 changes: 25 additions & 0 deletions docs/forms/pagebehaviorfactory.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
Prism's IPageBehaviorFactory is a great way to apply some custom behaviors on to pages either globally or with a little business logic. The Extended Prism.Forms package uses a custom PageBehaviorFactory. In addition to the normal behaviors that Prism applies to your Pages behind the scenes, the Extended version provides support for the following:

- Globally adding Platform Specifics on:
- SetToolbarPlacement on Android TabbedPage
- Use Safe Area on iOS
- PreferLargeTitles on iOS
- A custom behavior that changes the Title of a TabbedPage to always match the actively selected Tab

To control these features you simply need to register an implementation of `IPageBehaviorFactoryOptions`.

!!! note "Note"
A default instance is provided automatically that enables all of these features.

```c#
internal class MyPageBehaviorFactoryOptions : IPageBehaviorFactoryOptions
{
public bool UseBottomTabs => true;

public bool UseSafeArea => true;

public bool UseChildTitle => true;

public bool PreferLargeTitles => true;
}
```
13 changes: 7 additions & 6 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand Down
52 changes: 52 additions & 0 deletions docs/registerdelegates.md
Original file line number Diff line number Diff line change
@@ -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<IOptions>();
return containerProvider.Resolve<IBackendService>((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<IFoo>(FooFactory);
containerRegistry.RegisterDelegate<IBar>(BarFactory);
}

private static IFoo FooFactory() => new Foo();

private static IBar BarFactory(IContainerProvider container)
{
var options = container.Resolve<IOptions>();
return new Bar { HasCode = options.HasCode };
}

private static IBar BarFactory(IServiceProvider serviceProvider)
{
var options = serviceProvider.GetService<IOptions>();
return new Bar { HasCode = options.HasCode };
}
```
72 changes: 72 additions & 0 deletions docs/registermany.md
Original file line number Diff line number Diff line change
@@ -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<IFoo, FooBar>();
containerRegistry.Register<IBar, FooBar>();
```

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<IFoo, FooBar>();
containerRegistry.RegisterSingleton<IBar, FooBar>();
```

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<IFoo>() == Container.Resolve<IBar>())
{
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<FooBar>();

// Explicitly registers implemented interfaces
containerRegistry.RegisterManySingleton<FooBar>(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.
3 changes: 3 additions & 0 deletions docs/scoping.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Scoping

TODO
42 changes: 29 additions & 13 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ theme:
favicon: assets/favicon.ico
language: en
feature:
tabs: false
tabs: true
palette:
primary: 'white'
accent: 'cyan'
Expand Down Expand Up @@ -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
- 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']

0 comments on commit 12acb79

Please sign in to comment.