annotate Implab.ServiceHost/docs/XmlConfiguration.md @ 278:6691aff01de1 v3

Implab: added XmlDefaultSeializer (SerializersPool is now obsolete) Implab.ServiceHost: rewritten TypeReference (added support for nested types), stable API
author cin
date Thu, 03 May 2018 09:59:44 +0300
parents 963b17c275be
children e0916ddc9950
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
276
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
1 # XML Конфигурация IoC контейнера
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
2
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
3 Данная библиоетка создавалась для загрузки и применения конфигурации к IoC контейнеру, она не предназначена для конфигурирования
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
4 контейнера во время выполнения, большинство контейнеров уже обладают данным функционалом.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
5
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
6 На данный момент поддерживается единственный вид контейнера - [Unity Container](https://unitycontainer.github.io/)
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
7
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
8 Unity уже обладает средствами загрузки конфигурации из XML, данная библиотека позволяет решать следующие задачи
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
9
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
10 - Конфигурация является простым Xml документом, который можно получить из любого источика и не ограничивается `.config` файлами приложения
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
11 - Включение существующе конфигурации `<include href='config.xml'/>` в текущую
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
12 - Поддержка сериализованных объектов в качестве регистраций сервисов и параметров
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
13 - Описание зависимостей может быть расширено собсвтенными элементами с произвольной структурой
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
14 - Поддержка специфиакции генериков любой вложенности `Dictionary{Foo,Bar{Int32}}`
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
15
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
16 ## Общая архитектура
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
17
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
18 `Implab.ServiceHost.Unity` содержит в себе классы для загрузки и применения XML конфигурации к IoC контейнеру, в частности к Unity.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
19
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
20 1. Настраивается схема `ContainerConfigurationSchema`
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
21 2. Загружается документ и десереализуется в виде `ContainerElement`
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
22 3. Создается `ContainerBuilder` при помощи которого применяются настройки из `ContainerElement`
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
23
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
24 `ContainerConfigurationSchema` - определяет элементы которые могут быть использованы в конфигурации контейнера, предоставляет настроенный `XmlSerializer`.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
25
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
26 `ContainerBuilder` - основной класс, который используется для применения конфигурации к контейнеру, добавляет записи регистрации сервисов.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
27
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
28 `ContainerElement` - Корневой элемент конфигурации, который загружается из документа.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
29
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
30 Классы заканчивающиеся словом `Builder` используются для применения конфигурации к контейнеру,
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
31 классы заканчивающиеся на `Element` содержат информацию о конфигурации и десериализуются из исходного документа.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
32
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
33 ## Структура конфигурации контейнера
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
34
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
35 Элемент верхнего уровня всегда `ContainerElemnt`, он используется для хранения набора элеметов, которые распознаются и выполняются `ContainerBuilder`.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
36
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
37 Все элементы, входящие в контейнер наследуются от абстрактного класса `ContainerItemElement`,
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
38 который позволяет получить текущий `ContainerBuilder` и выполнить над ним какие-либо действия.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
39
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
40 Примерами элементов контейнера могут быть
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
41
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
42 - `<include href='config.xml'/>` - включение конфигурации из указанного места
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
43 - `<namespace name='My.App'/>` - добавление пространства имен для поиска типов
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
44 - `<register type='MyGenericType{}'/>` - добавление в контейнер регистрации типа ``My.App.MyGenericType`1``
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
45
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
46 Полный набор элементов, доступных для использования в контейнере определяет схема `ContainerConfigurationSchema`,
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
47 разработчик может расширить контейнер совими собственными элементами зарегистрировав их в схеме.
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
48
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
49 Например, мы используем компоненту `MyHttpClient` для загрузки данных
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
50
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
51 ```xml
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
52 <register type="IClient" mapTo="MyHttpClient">
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
53 <property name="proxy">
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
54 <value>socks5://proxy1.my.company</value>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
55 </property>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
56 </register>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
57 ```
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
58
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
59 При частом использовании можно сделать описание конфигурации несколько проще,
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
60 описав новый эелемент конфигурации
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
61
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
62 ```csharp
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
63 public class MyHttpClientElement : ContainerItemElement {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
64
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
65 public string Proxy { get; set; }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
66
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
67 public override void Visit(ContainerBuilder builder) {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
68 // создаем описание элемента
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
69 var registration = new RegistrationElement {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
70 RegistrationType = "IClient",
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
71 ImplementationType = "My.App.MyHttpClient",
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
72 Injectors = new [] {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
73 new PropertyInjectionElement {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
74 Name = "Proxy",
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
75 Value = ValueParameterElement {
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
76 Value = Proxy
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
77 }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
78 }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
79 }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
80 };
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
81
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
82 // применяем созданное описание к контейнеру
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
83 builder.Visit(registration)
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
84 }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
85 }
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
86 ```
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
87
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
88 Регистрируем новый элемент в схеме
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
89
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
90 ```csharp
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
91 schema.RegisterContainerElement<MyHttpClientElement>("http");
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
92 ```
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
93
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
94 Используем новый элемент в конфигурации
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
95
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
96 ```xml
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
97 <http>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
98 <proxy>socks5://proxy1.my.company</propxy>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
99 </http>
b4e0f81c7425 container configuration docs
cin
parents:
diff changeset
100 ```