必須の引数とオーバーロード グループ

アクティビティは、アクティビティの実行を有効にするためには特定の引数をバインドする必要があるように構成できます。 RequiredArgument 属性は、アクティビティの特定の引数が必須であることを示す場合に使用します。また、OverloadGroup 属性は、必須の引数のカテゴリをグループ化する場合に使用します。 これらの属性を使用することで、アクティビティ作成者は、単純なアクティビティ検証の構成も複雑な構成も適用できます。

必須の引数の使用

アクティビティで RequiredArgument 属性を使用するためには、RequiredArgumentAttribute を使用して目的の引数を指定します。 次の例では、2 つの必須引数がある Add アクティビティが定義されています。

public sealed class Add : CodeActivity<int>  
{  
    [RequiredArgument]  
    public InArgument<int> Operand1 { get; set; }  
  
    [RequiredArgument]  
    public InArgument<int> Operand2 { get; set; }  
  
    protected override int Execute(CodeActivityContext context)  
    {  
        return Operand1.Get(context) + Operand2.Get(context);  
    }  
}  

また、XAML では、必須引数の指定に RequiredArgumentAttribute も使用されます。 この例では、3 つの引数を使用して Add アクティビティを定義し、Assign<T> アクティビティを使用して追加操作を実行します。

<Activity x:Class="ValidationDemo.Add" ...>  
  <x:Members>  
    <x:Property Name="Operand1" Type="InArgument(x:Int32)">  
      <x:Property.Attributes>  
        <RequiredArgumentAttribute />  
      </x:Property.Attributes>  
    </x:Property>  
    <x:Property Name="Operand2" Type="InArgument(x:Int32)">  
      <x:Property.Attributes>  
        <RequiredArgumentAttribute />  
      </x:Property.Attributes>  
    </x:Property>  
    <x:Property Name="Result" Type="OutArgument(x:Int32)" />  
  </x:Members>  
  <Assign>  
    <Assign.To>  
      <OutArgument x:TypeArguments="x:Int32">[Result]</OutArgument>  
    </Assign.To>  
    <Assign.Value>  
      <InArgument x:TypeArguments="x:Int32">[Operand1 + Operand2]</InArgument>  
    </Assign.Value>  
  </Assign>  
</Activity>  

アクティビティが使用され、いずれかの必須引数がバインドされていない場合は、次の検証エラーが返されます。

必須のアクティビティ引数 'Operand1' の値が指定されませんでした。

オーバーロード グループの使用

オーバーロード グループには、あるアクティビティ内で有効である引数の組み合わせを示すメソッドが用意されています。 引数は OverloadGroupAttribute を使用してグループ化されます。 各グループには、OverloadGroupAttribute によって指定される名前が付けられます。 アクティビティが有効なのは、オーバーロード グループ内の引数のセットが 1 つだけバインドされている場合です。 次の例では、CreateLocation クラスを定義します。

class CreateLocation: Activity  
{  
    [RequiredArgument]  
    public InArgument<string> Name { get; set; }  
  
    public InArgument<string> Description { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G1")]  
    public InArgument<int> Latitude { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G1")]  
    public InArgument<int> Longitude { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G2")]  
    [OverloadGroup("G3")]  
    public InArgument<string> Street { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G2")]  
    public InArgument<string> City { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G2")]  
    public InArgument<string> State { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("G3")]  
    public InArgument<int> Zip { get; set; }
}  

このアクティビティの目的は、米国内の場所を指定することです。 これを行うために、アクティビティのユーザーは、3 つある引数グループの 1 つを使用して場所を指定できます。 有効な組み合わせで引数を指定するために、3 種類のオーバーロード グループを定義しています。 G1 含む、 Latitude と Longitude 引数。 G2 には Street、City、および State が含まれます。 G3 には Street および Zip が含まれます。 Name も必要な引数ですが、オーバーロード グループの一部ではありません。 このアクティビティが有効であるためには、Name が、1 つのオーバーロード グループのみに含まれるすべての引数とバインドされている必要があります。

次の例 (「データベース アクセス アクティビティ」のサンプルからの抜粋) では、ConnectionString と ConfigFileSectionName の 2 つのオーバーロード グループがあります。 このアクティビティが有効であるためには、引数 ProviderName および ConnectionString がバインドされているか、または引数 ConfigName がバインドされている必要があります。両方がバインドされている場合は無効です。

public class DbUpdate: AsyncCodeActivity  
{  
    [RequiredArgument]  
    [OverloadGroup("ConnectionString")]  
    [DefaultValue(null)]  
    public InArgument<string> ProviderName { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("ConnectionString")]  
    [DependsOn("ProviderName")]  
    [DefaultValue(null)]  
    public InArgument<string> ConnectionString { get; set; }  
  
    [RequiredArgument]  
    [OverloadGroup("ConfigFileSectionName")]  
    [DefaultValue(null)]  
    public InArgument<string> ConfigName { get; set; }  
  
    [DefaultValue(null)]  
    public CommandType CommandType { get; set; }  
  
    [RequiredArgument]  
    public InArgument<string> Sql { get; set; }  
  
    [DependsOn("Sql")]  
    [DefaultValue(null)]  
    public IDictionary<string, Argument> Parameters { get; }  
  
    [DependsOn("Parameters")]  
    public OutArgument<int> AffectedRecords { get; set; }
}  

オーバーロード グループを定義するときは次の点に注意してください。

• オーバーロード グループを別のオーバーロード グループのサブセットまたは等価セットにすることはできません。

  注意

  この規則には例外が 1 つあります。 オーバーロード グループが別のオーバーロード グループのサブセットであり、サブセットに RequiredArgument が false である引数のみが含まれている場合、オーバーロード グループは有効です。

• 複数のオーバーロード グループが重なり合うように定義することは可能です。ただし、グループの共通部分には、一方または両方のオーバーロード グループの必須引数すべてを含めることはできません。 前の例では、オーバーロード グループ G2 および G3 が重なり合っていますが、共通部分に一方または両方のグループの引数すべてを含めてはいないため、有効です。

オーバーロード グループの引数をバインドするときは次の点に注意してください。

• オーバーロード グループ内の RequiredArgument 引数すべてがバインドされている場合、そのグループはバインドされていると見なされます。

• グループに RequiredArgument 引数がなく、1 つ以上の引数がバインドされている場合、そのグループはバインドされていると見なされます。

• バインドされているオーバーロード グループが 1 つもない状態は、検証エラーになります。ただし、RequiredArgument 引数を 1 つも含まないオーバーロード グループが 1 つある場合は有効です。

• 複数のオーバーロード グループをバインドすることはできません。つまり、1 つのオーバーロード グループの必須引数すべてをバインドしているのに加えて、別のオーバーロード グループのいずれかの引数もバインドしている場合は、エラーになります。