Sviluppo di un'interfaccia utente per un componente del flusso di datiDeveloping a User Interface for a Data Flow Component

Gli sviluppatori di componenti possono fornire un'interfaccia utente personalizzata per un componente, che viene visualizzata in SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT) quando il componente viene modificato.Component developers can provide a custom user interface for a component, which is displayed in SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT) when the component is edited. L'implementazione di un'interfaccia utente personalizzata fornisce notifiche quando il componente viene aggiunto o eliminato da un'attività Flusso di dati e quando per il componente è richiesta la Guida.Implementing a custom user interface provides you with notification when the component is added to or deleted from a data flow task, and when help is requested for the component.

Se non si fornisce un'interfaccia utente personalizzata per il componente, gli utenti possono comunque configurare il componente e le relative proprietà personalizzate utilizzando l'editor avanzato.If you do not provide a custom user interface for your component, users can still configure the component and its custom properties by using the Advanced Editor. È possibile assicurarsi che l'editor avanzato consenta agli utenti di modificare in modo appropriato i valori delle proprietà personalizzate tramite le proprietà TypeConverter e UITypeEditor di IDTSCustomProperty100, a seconda dei casi.You can ensure that the Advanced Editor allows users to edit custom property values appropriately by using the TypeConverter and UITypeEditor properties of the IDTSCustomProperty100 when appropriate. Per ulteriori informazioni, vedere "Creazione di proprietà personalizzate" in metodi della fase di progettazione di un componente flusso di dati.For more information, see "Creating Custom Properties" in Design-time Methods of a Data Flow Component.

Impostazione della proprietà UITypeNameSetting the UITypeName Property

Per fornire un'interfaccia utente personalizzata, lo sviluppatore deve impostare la proprietà UITypeName di DtsPipelineComponentAttribute sul nome di una classe che implementa l'interfaccia IDtsComponentUI.To provide a custom user interface, the developer must set the UITypeName property of the DtsPipelineComponentAttribute to the name of a class that implements the IDtsComponentUI interface. Quando questa proprietà è impostata dal componente, SQL ServerSQL Server Integration ServicesIntegration Services carica e chiama l'interfaccia utente personalizzata quando il componente viene modificato in SSISSSIS finestra di progettazione.When this property is set by the component, SQL ServerSQL Server Integration ServicesIntegration Services loads and calls the custom user interface when the component is edited in SSISSSIS Designer.

La proprietà UITypeName è una stringa delimitata da virgole che identifica il nome completo del tipo.The UITypeName property is a comma-delimited string that identifies the fully qualified name of the type. Nell'elenco seguente sono illustrati, nell'ordine, gli elementi che identificano il tipo:The following list shows, in order, the elements that identify the type:

  • Nome tipoType name

  • Nome assemblyAssembly name

  • Versione fileFile version

  • Impostazioni culturaCulture

  • Token di chiave pubblicaPublic key token

    Nell'esempio di codice seguente è illustrata una classe che deriva dalla classe di base PipelineComponent e specifica la proprietà UITypeName.The following code example shows a class that derives from the PipelineComponent base class and specifies the UITypeName property.

[DtsPipelineComponent(  
DisplayName="SampleComponent",  
UITypeName="MyNamespace.MyComponentUIClassName,MyAssemblyName,Version=1.0.0.0,Culture=neutral,PublicKeyToken=abcd...",  
ComponentType = ComponentType.Transform)]  
public class SampleComponent : PipelineComponent  
{  
//TODO: Implement the component here.  
}  
<DtsPipelineComponent(DisplayName="SampleComponent", _  
UITypeName="MyNamespace.MyComponentUIClassName,MyAssemblyName,Version=1.0.0.0,Culture=neutral,PublicKeyToken=abcd...", ComponentType=ComponentType.Transform)> _   
Public Class SampleComponent   
 Inherits PipelineComponent   
End Class  

Implementazione dell'interfaccia IDtsComponentUI Implementing the IDtsComponentUI Interface

L'interfaccia IDtsComponentUI contiene i metodi chiamati da Progettazione SSISSSIS quando un componente viene aggiunto, eliminato e modificato.The IDtsComponentUI interface contains methods that SSISSSIS Designer calls when a component is added, deleted, and edited. Gli sviluppatori di componenti possono fornire codice nella loro implementazione di questi metodi per interagire con gli utenti del componente.Component developers can provide code in their implementation of these methods to interact with users of the component.

Questa classe viene in genere implementata in un assembly distinto dal componente stesso.This class is typically implemented in an assembly separate from the component itself. Anche se non è obbligatorio utilizzare un assembly distinto, in questo modo lo sviluppatore può compilare e distribuire il componente e l'interfaccia utente indipendentemente l'uno dall'altra e mantenere piccola l'impronta binaria del componente.Although use of a separate assembly is not required, this lets the developer build and deploy the component and the user interface independently of each other, and keeps the binary footprint of the component small.

L'implementazione di un'interfaccia utente personalizzata fornisce allo sviluppatore di componenti un maggior controllo sul componente quando viene modificato in Progettazione SSISSSIS.Implementing a custom user interface gives the component developer more control over the component as it is edited in SSISSSIS Designer. Ad esempio, un componente può aggiungere codice al metodo New, che viene chiamato quando il componente viene inizialmente aggiunto a un'attività Flusso di dati, e visualizzare una procedura guidata che consente all'utente di completare la configurazione iniziale del componente.For example, a component can add code to the New method, which is called when a component is initially added to a data flow task, and display a wizard that guides the user through the initial configuration of the component.

Dopo aver creato una classe che implementa l'interfaccia IDtsComponentUI, è necessario aggiungere codice per rispondere all'interazione dell'utente con il componente.After you have created a class that implements the IDtsComponentUI interface, you must add code to respond to user interaction with the component. Il metodo Initialize fornisce l'interfaccia IDTSComponentMetaData100 del componente e viene chiamato prima dei metodi New e Edit.The Initialize method provides the IDTSComponentMetaData100 interface of the component, and is called before the New and Edit methods. Questo riferimento deve essere archiviato in una variabile membro privata e utilizzato in seguito per modificare i metadati del componente.This reference should be stored in a private member variable and used to modify the component's metadata thereafter.

Come effettuare modifiche in un componente e renderle persistentiModifying a Component and Persisting Changes

L'interfaccia IDTSComponentMetaData100 viene fornita come parametro al metodo Initialize.The IDTSComponentMetaData100 interface is provided as a parameter to the Initialize method. Questo riferimento deve essere memorizzato nella cache in una variabile membro dal codice dell'interfaccia utente e quindi utilizzato per modificare il componente in risposta all'interazione dell'utente con l'interfaccia utente.This reference should be cached in a member variable by the user interface code, and then used to modify the component in response to user interaction with the user interface.

Anche se è possibile modificare direttamente il componente tramite l'interfaccia IDTSComponentMetaData100, è preferibile creare un'istanza di CManagedComponentWrapper tramite il metodo Instantiate.Although you can modify the component directly through the IDTSComponentMetaData100 interface, it is better to create an instance of the CManagedComponentWrapper by using the Instantiate method. Quando si modifica direttamente il componente tramite l'interfaccia, le misure di sicurezza di convalida del componente vengono ignorate.When you edit the component directly by using the interface, you bypass the component's validation safeguards. Il vantaggio dell'utilizzo dell'istanza della fase di progettazione del componente tramite CManagedComponentWrapper è che ci si assicura che il componente controlli le modifiche apportate.The advantage of using the design-time instance of the component through the CManagedComponentWrapper is that you ensure that the component has control over the changes made to it.

Il valore restituito del metodo Edit determina se le modifiche apportate a un componente vengono rese persistenti o annullate.The return value of the Edit method determines whether changes made to a component are persisted or discarded. Quando questo metodo restituisce false, tutte le modifiche vengono annullate; true rende persistenti le modifiche al componente e contrassegna il pacchetto come da richiederne il salvataggio.When this method returns false, all changes are discarded; true persists the changes to the component and marks the package as needing to be saved.

Utilizzo dei servizi di Progettazione SSISUsing the Services of the SSIS Designer

Il IServiceProvider parametro il Initialize metodo fornisce l'accesso ai seguenti servizi di SSISSSIS progettazione:The IServiceProvider parameter of the Initialize method provides access to the following services of SSISSSIS Designer:

ServizioService DescriptionDescription
IDtsClipboardService Viene utilizzato per determinare se il componente è stato generato come parte di un'operazione Copia/Incolla o Taglia/Incolla.Used to determine whether the component was generated as part of a copy/paste or cut/paste operation.
IDtsConnectionService Viene utilizzato per accedere alle connessioni esistenti o per creare nuove connessioni nel pacchetto.Used to access existing connections or to create new connections in the package.
IErrorCollectionService Viene utilizzato per acquisire eventi dai componenti del flusso di dati quando è necessario acquisire tutti gli errori e gli avvisi generati dal componente anziché ricevere solo quelli più recenti.Used to capture events from data flow components when you need to capture all the errors and warnings raised by the component instead of receiving only the last error or warning.
IDtsVariableService Viene utilizzato per accedere alle variabili esistenti o per creare nuove variabili nel pacchetto.Used to access existing variables or to create new variables in the package.
IDtsPipelineEnvironmentService Viene utilizzato dai componenti del flusso di dati per accedere all'attività Flusso di dati padre e ad altri componenti del flusso di dati.Used by data flow components to access the parent Data Flow task and other components in the data flow. Questa caratteristica può essere utilizzata per sviluppare un componente come la Creazione guidata dimensioni a modifica lenta, che crea e connette componenti del flusso di dati aggiuntivi se necessario.This feature could be used to develop a component like the Slowly Changing Dimension Wizard that creates and connects additional data flow components as needed.

Questi servizi offrono agli sviluppatori di componenti la possibilità di accedere e creare oggetti nel pacchetto in cui viene caricato il componente.These services provide component developers the ability to access and create objects in the package in which the component is loaded.

EsempioSample

Nell'esempio di codice seguente è illustrata l'integrazione di una classe di interfaccia utente personalizzata che implementa l'interfaccia IDtsComponentUI e un Windows Form che funge da editor per un componente.The following code example shows the integration of a custom user interface class that implements the IDtsComponentUI interface, and a Windows form that serves as the editor for a component.

Classe dell'interfaccia utente personalizzataCustom User Interface Class

Nell'esempio di codice seguente è illustrata la classe che implementa l'interfaccia IDtsComponentUI.The following code shows the class that implements the IDtsComponentUI interface. Il metodo Edit crea l'editor del componente, quindi visualizza il form.The Edit method creates the component editor and then displays the form. Il valore restituito del form determina se le modifiche apportate al componente sono persistenti.The return value of the form determines whether changes to the component are persisted.

using System;  
using System.Windows.Forms;  
using Microsoft.SqlServer.Dts.Runtime;  
using Microsoft.SqlServer.Dts.Pipeline.Design;  
using Microsoft.SqlServer.Dts.Pipeline.Wrapper;  

namespace Microsoft.Samples.SqlServer.Dts  
{  
    public class SampleComponentUI : IDtsComponentUI  
    {  
        IDTSComponentMetaData100 md;  
        IServiceProvider sp;  

        public void Help(System.Windows.Forms.IWin32Window parentWindow)  
        {  
        }  
        public void New(System.Windows.Forms.IWin32Window parentWindow)  
        {  
        }  
        public void Delete(System.Windows.Forms.IWin32Window parentWindow)  
        {  
        }  
        public bool Edit(System.Windows.Forms.IWin32Window parentWindow, Variables vars, Connections cons)  
        {  
            // Create and display the form for the user interface.  
            SampleComponentUIForm componentEditor = new SampleComponentUIForm(cons, vars, md);  

            DialogResult result  = componentEditor.ShowDialog(parentWindow);  

            if (result == DialogResult.OK)  
                return true;  

            return false;  
        }  
        public void Initialize(IDTSComponentMetaData100 dtsComponentMetadata, IServiceProvider serviceProvider)  
        {  
            // Store the component metadata.  
            this.md = dtsComponentMetadata;  
        }  
    }  
}  
Imports System   
Imports System.Windows.Forms   
Imports Microsoft.SqlServer.Dts.Runtime   
Imports Microsoft.SqlServer.Dts.Pipeline.Design   
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper   

Namespace Microsoft.Samples.SqlServer.Dts   

 Public Class SampleComponentUI   
 Implements IDtsComponentUI   
   Private md As IDTSComponentMetaData100   
   Private sp As IServiceProvider   

   Public Sub Help(ByVal parentWindow As System.Windows.Forms.IWin32Window)   
   End Sub   

   Public Sub New(ByVal parentWindow As System.Windows.Forms.IWin32Window)   
   End Sub   

   Public Sub Delete(ByVal parentWindow As System.Windows.Forms.IWin32Window)   
   End Sub   

   Public Function Edit(ByVal parentWindow As System.Windows.Forms.IWin32Window, ByVal vars As Variables, ByVal cons As Connections) As Boolean   
     ' Create and display the form for the user interface.  
     Dim componentEditor As SampleComponentUIForm = New SampleComponentUIForm(cons, vars, md)   
     Dim result As DialogResult = componentEditor.ShowDialog(parentWindow)   
     If result = DialogResult.OK Then   
       Return True   
     End If   
     Return False   
   End Function   

   Public Sub Initialize(ByVal dtsComponentMetadata As IDTSComponentMetaData100, ByVal serviceProvider As IServiceProvider)   
     Me.md = dtsComponentMetadata   
   End Sub   
 End Class   

End Namespace  

Editor personalizzatoCustom Editor

Nel codice seguente è illustrata l'implementazione del Windows Form visualizzato durante la chiamata al metodo Edit.The following code shows the implementation of the Windows form that is shown during the call to the Edit method.

using System;  
using System.Drawing;  
using System.Collections;  
using System.ComponentModel;  
using System.Windows.Forms;  
using System.Data;  

using Microsoft.SqlServer.Dts.Pipeline.Wrapper;  
using Microsoft.SqlServer.Dts.Runtime;  

namespace Microsoft.Samples.SqlServer.Dts  
{  
    public partial class SampleComponentUIForm : System.Windows.Forms.Form  
    {  
        private Connections connections;  
        private Variables variables;  
        private IDTSComponentMetaData100 metaData;  
        private CManagedComponentWrapper designTimeInstance;  
        private System.ComponentModel.IContainer components = null;  

        public SampleComponentUIForm( Connections cons, Variables vars, IDTSComponentMetaData100 md)  
        {  
            variables = vars;  
            connections = cons;  
            metaData = md;  
        }  

        private void btnOk_Click(object sender, System.EventArgs e)  
        {  
            if (designTimeInstance == null)  
                designTimeInstance = metaData.Instantiate();  

            designTimeInstance.SetComponentProperty( "CustomProperty", txtCustomPropertyValue.Text);  

            this.Close();  
        }  

        private void btnCancel_Click(object sender, System.EventArgs e)  
        {  
            this.Close();  
        }  
    }  
}  
Imports System   
Imports System.Drawing   
Imports System.Collections   
Imports System.ComponentModel   
Imports System.Windows.Forms   
Imports System.Data   
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper   
Imports Microsoft.SqlServer.Dts.Runtime   

Namespace Microsoft.Samples.SqlServer.Dts   

 Public Partial Class SampleComponentUIForm   
  Inherits System.Windows.Forms.Form   
   Private connections As Connections   
   Private variables As Variables   
   Private metaData As IDTSComponentMetaData100   
   Private designTimeInstance As CManagedComponentWrapper   
   Private components As System.ComponentModel.IContainer = Nothing   

   Public Sub New(ByVal cons As Connections, ByVal vars As Variables, ByVal md As IDTSComponentMetaData100)   
     variables = vars   
     connections = cons   
     metaData = md   
   End Sub   

   Private Sub btnOk_Click(ByVal sender As Object, ByVal e As System.EventArgs)   
     If designTimeInstance Is Nothing Then   
       designTimeInstance = metaData.Instantiate   
     End If   
     designTimeInstance.SetComponentProperty("CustomProperty", txtCustomPropertyValue.Text)   
     Me.Close   
   End Sub   

   Private Sub btnCancel_Click(ByVal sender As Object, ByVal e As System.EventArgs)   
     Me.Close   
   End Sub   
 End Class   

End Namespace  

Vedere ancheSee Also

Creazione di un componente del flusso di dati personalizzatiCreating a Custom Data Flow Component