// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System.Collections.Generic;
 
#nullable disable
 
namespace Microsoft.Build.Framework
{
    /// <summary>
    /// Interface that a task factory Instance should implement if it wants to be able to
    /// use new UsingTask parameters such as Runtime and Architecture.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Before implementing a custom task factory, consider whether your scenario can be addressed by MSBuild's built-in 
    /// task factories (such as AssemblyTaskFactory for tasks in compiled assemblies, TaskHostFactory for inline tasks, 
    /// or RoslynCodeTaskFactory for C# code tasks). Custom task factories add complexity and maintenance burden, and 
    /// most scenarios can be handled by the existing MSBuild infrastructure.
    /// </para>
    /// <para>
    /// If you have an existing custom task factory implementation, we recommend evaluating whether migrating to 
    /// MSBuild's built-in task factories would be feasible for your use case.
    /// </para>
    /// </remarks>
    public interface ITaskFactory3 : ITaskFactory2
    {
        /// <summary>
        /// Initializes this factory for instantiating tasks with a particular inline task block and a set of UsingTask parameters.  MSBuild
        /// provides an implementation of this interface, TaskHostFactory, that uses "Runtime", with values "CLR2", "CLR4", "CurrentRuntime",
        /// and "*" (Any); and "Architecture", with values "x86", "x64", "CurrentArchitecture", and "*" (Any).  An implementer of ITaskFactory2
        /// can choose to use these pre-defined Runtime and Architecture values, or can specify new values for these parameters.
        /// </summary>
        /// <param name="taskName">Name of the task.</param>
        /// <param name="factoryIdentityParameters">Special parameters that the task factory can use to modify how it executes tasks,
        /// such as Runtime and Architecture.  The key is the name of the parameter and the value is the parameter's value. This
        /// is the set of parameters that was set on the UsingTask using e.g. the UsingTask Runtime and Architecture parameters.</param>
        /// <param name="parameterGroup">The parameter group.</param>
        /// <param name="taskBody">The task body.</param>
        /// <param name="taskFactoryLoggingHost">The task factory logging host.</param>
        /// <returns>A value indicating whether initialization was successful.</returns>
        /// <remarks>
        /// <para>MSBuild engine will call this to initialize the factory. This should initialize the factory enough so that the
        /// factory can be asked whether or not task names can be created by the factory.  If a task factory implements ITaskFactory2,
        /// this Initialize method will be called in place of ITaskFactory.Initialize.</para>
        /// <para>
        /// The taskFactoryLoggingHost will log messages in the context of the target where the task is first used.
        /// </para>
        /// </remarks>
        bool Initialize(string taskName, TaskHostParameters factoryIdentityParameters, IDictionary<string, TaskPropertyInfo> parameterGroup, string taskBody, IBuildEngine taskFactoryLoggingHost);
 
        /// <summary>
        /// Create an instance of the task to be used, with an optional set of "special" parameters set on the individual task invocation using
        /// the MSBuildRuntime and MSBuildArchitecture default task parameters.  MSBuild provides an implementation of this interface,
        /// TaskHostFactory, that uses "MSBuildRuntime", with values "CLR2", "CLR4", "CurrentRuntime", and "*" (Any); and "MSBuildArchitecture",
        /// with values "x86", "x64", "CurrentArchitecture", and "*" (Any).  An implementer of ITaskFactory2 can choose to use these pre-defined
        /// MSBuildRuntime and MSBuildArchitecture values, or can specify new values for these parameters.
        /// </summary>
        /// <param name="taskFactoryLoggingHost">
        /// The task factory logging host will log messages in the context of the task.
        /// </param>
        /// <param name="taskIdentityParameters">
        /// Special parameters that the task factory can use to modify how it executes tasks, such as Runtime and Architecture.
        /// The key is the name of the parameter and the value is the parameter's value.  This is the set of parameters that was
        /// set to the task invocation itself, via e.g. the special MSBuildRuntime and MSBuildArchitecture parameters.
        /// </param>
        /// <remarks>
        /// If a task factory implements ITaskFactory2, MSBuild will call this method instead of ITaskFactory.CreateTask.
        /// </remarks>
        /// <returns>
        /// The generated task, or <c>null</c> if the task failed to be created.
        /// </returns>
        ITask CreateTask(IBuildEngine taskFactoryLoggingHost, TaskHostParameters taskIdentityParameters);
    }
}