======================
**collection** element
======================

Collection element is used to specify collection values.

Based on the context, in which **collection** element is used, it might use **collectionType** and **itemType** attributes to specify collection type and collection items type, or these values will be derived by **IoC.Configuration**.

.. note::
    The possible values of **collectionType** attribute currently are **enumerable**, **list**, **readOnlyList**, and **array**.

For example, if **collection** is used to specified as a constructor parameter, or injected property value, **collectionType** and **itemType** attributes are required, along with the **name** attribute.

On the other hand, if **collection** is used to provide a return value in **autoProperty** or **autoMethod** elements, this attributes are not used, and **IoC.Configuration** determines the type of the collection from the auto-generated property or method return type.

.. note::
    Refer to :doc:`../../sample-files/IoCConfiguration_collection.generated` for more examples on **collection** element.


Example 1: Using **collection** element to specify constructed parameter value in service implementation
========================================================================================================

.. code-block:: xml
    :linenos:

    <services>
        <selfBoundService
            type="IoC.Configuration.Tests.Collection.Services.CollectionsTestClass1"
            scope="singleton" >

            <parameters>
                <!--Demo of collection element used as a constructor parameter.-->
                <collection name="readOnlyListParam"
                            collectionType="readOnlyList"
                            itemType="System.Int32">
                  <int32 value="17"/>
                  <int32 value="24"/>
                  <int32 value="27"/>
                </collection>

                <!--Demo of collection element used as a constructor parameter.-->
                <collection name="arrayParam"
                            collectionType="array"
                            itemTypeRef="IInterface1">
                  <injectedObject typeRef="IInterface1"/>
                  <constructedValue typeRef="Interface1_Impl">
                    <parameters>
                      <int32 name="param1" value="29"/>
                    </parameters>
                  </constructedValue>
                </collection>
            </parameters>
        </selfBoundService>
    <services>

Example 2: Using **collection** element to specify injected property value
==========================================================================

.. code-block:: xml
    :linenos:

    <services>
        <selfBoundService
            type="IoC.Configuration.Tests.Collection.Services.CollectionsTestClass1"
            scope="singleton" >

            <injectedProperties>
                <!--Demo of collection element used to initialize
                    the value of injected property.-->
                <collection name="EnumerableValues"
                            collectionType="enumerable"
                            itemType="SharedServices.Interfaces.IInterface1" >
                  <constructedValue typeRef="Interface1_Impl">
                    <parameters>
                      <int32 name="param1" value="18"/>
                    </parameters>
                  </constructedValue>
                  <settingValue settingName="DefaultInterface1Value"/>
                  <injectedObject typeRef="IInterface1"/>
                </collection>

                <!--Demo of collection element used to initialize
                    the value of injected property.-->
                <collection name="ListValues"
                            collectionType="list"
                            itemTypeRef="IInterface1">
                  <injectedObject typeRef="IInterface1"/>
                  <settingValue settingName="DefaultInterface1Value"/>
                  <constructedValue typeRef="Interface1_Impl">
                    <parameters>
                      <int32 name="param1" value="139"/>
                    </parameters>
                  </constructedValue>
                </collection>
            </injectedProperties>
        </selfBoundService>
    <services>

Example 3: Using **collection** element to specify a returned value for auto-generated method
=============================================================================================

.. code-block:: xml
    :linenos:

    <autoGeneratedServices>
        <!--Demo of collection element used in auto-implemented method and property
            return values.-->
        <autoService interface="IoC.Configuration.Tests.Collection.Services.IAutoService1">
            <autoMethod name="GetAllActionIds"
                        returnType="System.Collections.Generic.IReadOnlyList[System.Int32]">
                <methodSignature>
                    <int32 paramName="appId"/>
                </methodSignature>
                <if parameter1="3">
                    <collection>
                        <int32 value="27"/>
                        <int32 value="17"/>
                    </collection>
                </if>
                <default>
                  <collection>
                    <int32 value="13"/>
                    <int32 value="27"/>
                    <int32 value="17"/>
                  </collection>
                </default>
            </autoMethod>
        </autoService>
    </autoGeneratedServices>

Example 4: Using **collection** element to provide a service implementation
===========================================================================

.. code-block:: xml
    :linenos:

    <service type="System.Collections.Generic.IReadOnlyList[SharedServices.Interfaces.IDbConnection]">
        <valueImplementation scope="singleton">
            <collection>
                <settingValue settingName="DefaultDBConnection"/>

                <constructedValue type="SharedServices.Implementations.SqlServerDbConnection">
                    <parameters>
                        <string name="serverName" value="SQLSERVER2012"/>
                        <string name="databaseName" value="DB1"/>
                        <string name="userName" value="user1"/>
                        <string name="password" value="password123"/>
                    </parameters>
                </constructedValue>

                <constructedValue type="SharedServices.Implementations.SqlServerDbConnection">
                    <parameters>
                        <string name="serverName" value="SQLSERVER2016"/>
                        <string name="databaseName" value="DB2"/>
                        <string name="userName" value="user2"/>
                        <string name="password" value="password456"/>
                    </parameters>
                </constructedValue>

                <constructedValue type="TestPluginAssembly1.Implementations.MySqlDbConnection">
                    <parameters>
                        <string name="connectionString" value="user=User1;password=123"/>
                    </parameters>
                </constructedValue>
            </collection>
        </valueImplementation>
    </service>