class/System.ComponentModel.Composition/src/ComponentModel/System/ComponentModel/Composition/ImportAttribute.cs

   1 // -----------------------------------------------------------------------
   2 // Copyright (c) Microsoft Corporation.  All rights reserved.
   3 // -----------------------------------------------------------------------
   4 using System;
   5 using System.ComponentModel.Composition.Hosting;
   6 using System.ComponentModel.Composition.Primitives;
   7 using System.Diagnostics.CodeAnalysis;
   8
   9 namespace System.ComponentModel.Composition
  10 {
  11     /// <summary>
  12     ///     Specifies that a property, field, or parameter imports a particular export.
  13     /// </summary>
  14     [SuppressMessage("Microsoft.Performance", "CA1813:AvoidUnsealedAttributes")]
  15     [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter,
  16                     AllowMultiple = false, Inherited = false)]
  17     public class ImportAttribute : Attribute, IAttributedImport
  18     {
  19         /// <summary>
  20         ///     Initializes a new instance of the <see cref="ImportAttribute"/> class, importing the
  21         ///     export with the default contract name.
  22         /// </summary>
  23         /// <remarks>
  24         ///     <para>
  25         ///         The default contract name is the result of calling
  26         ///         <see cref="AttributedModelServices.GetContractName(Type)"/> on the property, field,
  27         ///         or parameter type that this is marked with this attribute.
  28         ///     </para>
  29         ///     <para>
  30         ///         The contract name is compared using a case-sensitive, non-linguistic comparison
  31         ///         using <see cref="StringComparer.Ordinal"/>.
  32         ///     </para>
  33         /// </remarks>
  34         public ImportAttribute()
  35             : this((string)null)
  36         {
  37         }
  38
  39         /// <summary>
  40         ///     Initializes a new instance of the <see cref="ImportAttribute"/> class, importing the
  41         ///     export with the contract name derived from the specified type.
  42         /// </summary>
  43         /// <param name="contractType">
  44         ///     A <see cref="Type"/> of which to derive the contract name of the export to import, or
  45         ///     <see langword="null"/> to use the default contract name.
  46         /// </param>
  47         /// <remarks>
  48         ///     <para>
  49         ///         The contract name is the result of calling
  50         ///         <see cref="AttributedModelServices.GetContractName(Type)"/> on
  51         ///         <paramref name="contractType"/>.
  52         ///     </para>
  53         ///     <para>
  54         ///         The default contract name is the result of calling
  55         ///         <see cref="AttributedModelServices.GetContractName(Type)"/> on the property, field,
  56         ///         or parameter type that is marked with this attribute.
  57         ///     </para>
  58         ///     <para>
  59         ///         The contract name is compared using a case-sensitive, non-linguistic comparison
  60         ///         using <see cref="StringComparer.Ordinal"/>.
  61         ///     </para>
  62         /// </remarks>
  63         public ImportAttribute(Type contractType)
  64             : this((string)null, contractType)
  65         {
  66         }
  67
  68         /// <summary>
  69         ///     Initializes a new instance of the <see cref="ImportAttribute"/> class, importing the
  70         ///     export with the specified contract name.
  71         /// </summary>
  72         /// <param name="contractName">
  73         ///      A <see cref="String"/> containing the contract name of the export to import, or
  74         ///      <see langword="null"/> or an empty string ("") to use the default contract name.
  75         /// </param>
  76         /// <remarks>
  77         ///     <para>
  78         ///         The default contract name is the result of calling
  79         ///         <see cref="AttributedModelServices.GetContractName(Type)"/> on the property, field,
  80         ///         or parameter type that is marked with this attribute.
  81         ///     </para>
  82         ///     <para>
  83         ///         The contract name is compared using a case-sensitive, non-linguistic comparison
  84         ///         using <see cref="StringComparer.Ordinal"/>.
  85         ///     </para>
  86         /// </remarks>
  87         public ImportAttribute(string contractName)
  88             : this(contractName, (Type)null)
  89         {
  90         }
  91
  92         public ImportAttribute(string contractName, Type contractType)
  93         {
  94             this.ContractName = contractName;
  95             this.ContractType = contractType;
  96         }
  97
  98         /// <summary>
  99         ///     Gets the contract name of the export to import.
 100         /// </summary>
 101         /// <value>
 102         ///      A <see cref="String"/> containing the contract name of the export to import. The
 103         ///      default value is an empty string ("").
 104         /// </value>
 105         public string ContractName { get; private set; }
 106
 107         /// <summary>
 108         ///     Get the contract type of the export to import.
 109         /// </summary>
 110         /// <value>
 111         ///     A <see cref="Type"/> of the export that this import is expecting. The default value is
 112         ///     <see langword="null"/> which means that the type will be obtained by looking at the type on
 113         ///     the member that this import is attached to. If the type is <see cref="object"/> then the
 114         ///     importer is delaring they can accept any exported type.
 115         /// </value>
 116         public Type ContractType { get; private set; }
 117
 118         /// <summary>
 119         ///     Gets or sets a value indicating whether the property, field or parameter will be set
 120         ///     to its type's default value when an export with the contract name is not present in
 121         ///     the container.
 122         /// </summary>
 123         /// <value>
 124         ///     <see langword="true"/> if the property, field or parameter will be set
 125         ///     its type's default value when an export with the <see cref="ContractName"/> is not
 126         ///     present in the <see cref="CompositionContainer"/>; otherwise, <see langword="false"/>.
 127         ///     The default value is <see langword="false"/>.
 128         /// </value>
 129         /// <remarks>
 130         ///     <para>
 131         ///         The default value of a property's, field's or parameter's type is
 132         ///         <see langword="null"/> for reference types and 0 for numeric value types. For
 133         ///         other value types, the default value will be each field of the value type
 134         ///         initialized to zero, if the field is a value type or <see langword="null"/> if
 135         ///         the field is a reference type.
 136         ///     </para>
 137         /// </remarks>
 138         public bool AllowDefault { get; set; }
 139
 140         /// <summary>
 141         ///     Gets or sets a value indicating whether the property or field will be recomposed
 142         ///     when exports that provide the same contract that this import expects, have changed
 143         ///     in the container.
 144         /// </summary>
 145         /// <value>
 146         ///     <see langword="true"/> if the property or field allows for recomposition when exports
 147         ///     that provide the same <see cref="ContractName"/> are added or removed from the
 148         ///     <see cref="CompositionContainer"/>; otherwise, <see langword="false"/>.
 149         ///     The default value is <see langword="false"/>.
 150         /// </value>
 151         public bool AllowRecomposition { get; set; }
 152
 153         /// <summary>
 154         ///     Gets or sets a value indicating that the importer requires a specific
 155         ///     <see cref="CreationPolicy"/> for the exports used to satisfy this import. T
 156         /// </summary>
 157         /// <value>
 158         ///     <see cref="CreationPolicy.Any"/> - default value, used if the importer doesn't
 159         ///         require a specific <see cref="CreationPolicy"/>.
 160         ///
 161         ///     <see cref="CreationPolicy.Shared"/> - Requires that all exports used should be shared
 162         ///         by everyone in the container.
 163         ///
 164         ///     <see cref="CreationPolicy.NonShared"/> - Requires that all exports used should be
 165         ///         non-shared in a container and thus everyone gets their own instance.
 166         /// </value>
 167         public CreationPolicy RequiredCreationPolicy { get; set; }
 168
 169         ImportCardinality IAttributedImport.Cardinality
 170         {
 171             get
 172             {
 173                 if (this.AllowDefault == true)
 174                 {
 175                     return ImportCardinality.ZeroOrOne;
 176                 }
 177                 return ImportCardinality.ExactlyOne;
 178             }
 179         }
 180     }
 181 }