1. DAT372 Programming Microsoft® SQL Server DTS 2000 using.NET (Visual Basic®.NET and C#) Gert E.R. Drapers Architect Microsoft Corp.

2. Agenda DTS Architecture Overview DTS Architecture Overview Interop between.NET and DTS (COM) Interop between.NET and DTS (COM) Building Custom Tasks Building Custom Tasks – Registration – Simple Custom Task – Custom Task UI – State Persistence – Passing state through Global Variables – Task Logging and Events Debugging.NET Custom Tasks Debugging.NET Custom Tasks Deployment of.NET Custom Tasks Deployment of.NET Custom Tasks

3. DTS Architecture Overview Connection (OLE-DB) DTS Package DTS Designer DTSRUN.EXE DTSRUNUI.EXE Your Application DTS Wizard Transform Data Task CustomTask DTS Package Object Model (DTSPKG.DLL) Execute SQL Task CustomTask Send Mail Task CustomTask DataPumpTransform Copy Column Transfrom

4. SQL Server 2000 DTS Object Model Connections Connection2 ConnectionPropertiesOLEDBProperty GlobalVariablesGlobalVariable2 StepsStep2 PrecedenceConstraints PrecedenceConstraint Tasks Task CustomTask CustomTaskUI PersistPropertyBagPropertyBag PackageLog SavePackageInfosSavePackageInfo Package2

5. Interop between.NET and DTS DTS is implemented as a set of free threaded in-process COM servers DTS is implemented as a set of free threaded in-process COM servers – DTSPKG.DLL exposes all package and custom task interfaces through a Type Library – DTSPUMP.DLL (Custom Transforms) does not expose a Type Library Calling DTS from.NET (execution of packages) Calling DTS from.NET (execution of packages) – Requires the creation of a Runtime Callable Wrapper (RCW) that wraps the COM interfaces into a.NET assembly. Extending DTS using.NET ( building Custom Tasks) Extending DTS using.NET ( building Custom Tasks) – Requires creation.NET assemblies that expose themselves via a COM callable wrapper (CCW) to interact between COM/DTS and.NET

6. .Net To COM Interop Using COM Types From.NET Using COM Types From.NET – Create an assembly containing type definitions for COM types Add reference in VS, or use TLBIMP utility Add reference in VS, or use TLBIMP utility Define the types manually (PIA) Define the types manually (PIA) Runtime Callable Wrapper Object IFoo IUnknown Common Language Runtime COM Server Client Reference Counted Traced Reference

7. COM To.Net Interop Using.NET Types From COM Using.NET Types From COM – Create COM type library using TLBEXP – Install and Register the assembly RegAsm RegAsm GACUtil GACUtil IFoo IDispatch IUnknown COM Callable Wrapper Object IFoo Common Language Runtime Client COM Client Reference Counted Traced Reference

8. .NET interaction with DTS Calling DTS from.NET steps: Calling DTS from.NET steps: – Create new strong name key file sn.exe -k dts.key sn.exe -k dts.key – Create RCW of DTSPKG.DLL tlbimp.exe "C:\Program Files\Microsoft SQL Server\80\Tools\Binn\dtspkg.dll" /out:Microsoft.SQLServer.DTSPkg80.dll /keyfile:dts.key tlbimp.exe "C:\Program Files\Microsoft SQL Server\80\Tools\Binn\dtspkg.dll" /out:Microsoft.SQLServer.DTSPkg80.dll /keyfile:dts.key – Place RCW in the GAC (Global Assembly Cache) gacutil.exe -i Microsoft.SQLServer.DTSPkg80.dll gacutil.exe -i Microsoft.SQLServer.DTSPkg80.dll

9. COM Plumbing Expose Custom Task as a dual interface COM component Expose Custom Task as a dual interface COM component – [assembly:ClassInterface(ClassInterfaceType.A utoDual)] Use fixed GUID for Custom Task Use fixed GUID for Custom Task – [Guid("C5A81539-7D87-3A86-9F4C- FC61FAFEA373"), ComVisible(true)] – Optional, but eases the development and debugging of custom tasks

10. Custom Task Registration Need to add task to DTS Task Cache which is a COM Catalog during registration (RegSvr32) Need to add task to DTS Task Cache which is a COM Catalog during registration (RegSvr32) – const string TASK_CACHE = @"Software\Microsoft\Microsoft SQL Server\80\DTS\Enumeration\Tasks";.NET assemblies do not expose DllRegisterServer and DllUnregisterServer entrypoints, but call is redirected using attributes..NET assemblies do not expose DllRegisterServer and DllUnregisterServer entrypoints, but call is redirected using attributes. – COM equivalent of DllRegisterServer [System.Runtime.InteropServices.ComRegisterFunctionAttribute()] static void RegisterServer(Type t) { // Add GUID to DTS Custom Task Cache (COM Catalog) } –.NET implemetation of COM DllUnregisterServer [System.Runtime.InteropServices.ComUnregisterFunctionAttribute()] static void UnregisterServer(Type t) { // Remove GUID to DTS Custom Task Cache (COM Catalog) }

11. Handle COM Exceptions Always handle COM exceptions inside the Custom Task Always handle COM exceptions inside the Custom Task – Prevent throwing exceptions, this eases the success/failure management of a task. – Exceptions are converts in to HRESULT’s using System.Runtime.InteropServices; try { // your code… } catch(COMException e) { // handle COM exceptions first Console.WriteLine("COM exception \n{0}\n{1}", e.Message, e.StackTrace); } catch(System.Exception e) { // handle all other exceptions last }

12. Creating a Custom Task To create a custom task, implement: To create a custom task, implement: – CustomTask – User interface of the Custom Task CustomTaskUI (optional) CustomTaskUI (optional) – Custom property handling: PersistPropertyBag (optional) PersistPropertyBag (optional) Success/failure and error handling Success/failure and error handling Event support, providing status back to runtime Event support, providing status back to runtime NOTE: DTS is Free Threaded NOTE: DTS is Free Threaded – Non-Free threaded COM objects must execute on main thread (for example Visual Basic Custom Tasks)

13. DTS Custom Task using C# public class MyCustTask : CustomTask { private string _Name; private string _Description; public MyCustTask() { // TODO: Add constructor logic here } public void Execute(object pPackage, object pPackageEvents, object pPackageLog, ref DTSTaskExecResult pTaskResult) { // Implement Execute task logic here } public string Description { get {return _Description;} set {_Description = value;} } public string Name { get {return _Name;} set {_Name = value;} } public Properties Properties { get {return null;} }}

14. Custom Task UI Implement CustomTaskUI interface Implement CustomTaskUI interface – Initialize Called once per Task at initialization of Task UI Called once per Task at initialization of Task UI Save the pTask for later reference Save the pTask for later reference – New Called on creation of task Called on creation of task – Edit Called on editing of exiting task (do not change the task name!) Called on editing of exiting task (do not change the task name!) – Delete Called on deletion of task, default implementation is fine. Called on deletion of task, default implementation is fine. – Help Called on F1, Shift-F1 and Help via Task Properties Called on F1, Shift-F1 and Help via Task Properties – GetUIInfo Not implemeted by DTS Designer, no need to implement Not implemeted by DTS Designer, no need to implement – CreateCustomToolTip Not implemeted by DTS Designer, no need to implement Not implemeted by DTS Designer, no need to implement

15. Custom Task Persistence Implement PersistPropertyBag interface Implement PersistPropertyBag interface – DTS implementation of Automation enabled property bag – Loads and Saves into DTS Property Bag – Property bag does not support persistence of generic blobs or objects public void Load(Microsoft.SQLServer.DTSPkg80.PropertyBag PropertyBag) { _Name = (string) PropertyBag.Read("Name"); } public void Save(Microsoft.SQLServer.DTSPkg.PropertyBag PropertyBag) { PropertyBag.Write("Name", _Name); }

16. PropertiesProvider The PropertiesProvider object defines an object supplying a DTS Properties collection. The PropertiesProvider object defines an object supplying a DTS Properties collection. When exposed, DTS will retrieve the Properties collection as required. When exposed, DTS will retrieve the Properties collection as required. public Microsoft.SQLServer.DTSPkg.Properties Properties { get { Properties props; PropertiesProviderClass propsProv = new PropertiesProviderClass(); props = propsProv.GetPropertiesForObject(this); propsProv = null; return props; }}

17. Task Logging and Events Logging Logging – PackageLog.WriteStringToLog (LogString); – PackageLog.WriteTaskRecord(ErrorCode, Description); Eventing, events on the Package2 object, fired during Custom Task Execute() method Eventing, events on the Package2 object, fired during Custom Task Execute() method – OnStart (*) – OnQueryCancel (*) – OnProgress – OnError – OnFinish (*) (*) Automatically fired by DTS execution engine

18. Passing state via Global Variables Using global variables Using global variables – Get reference to Package object At design time: At design time: – CustomTaskUI_Initialize, get Parent of Parent of pTask object to get Package object reference At runtime: At runtime: – Parameter of CustomTask_Execute

19. The Impossible… Reusing a connection Reusing a connection – Not possible without C++ code/object that converts the IUnknown returned from Connection.AcquireConnection into OLEDB IDBSession and converts the IDBSession in to an System.Data.OleDbClient.Connection object Joining a transaction Joining a transaction – If above would work, transactions would flow if the Custom Task was derived from System.EnpriseService.ServiceComponent

20. Debugging Custom Tasks Using Visual Studio 7.0 Using Visual Studio 7.0 – Set “Enable Unmanaged Debugging” = true – Register Assembly, using REGASM.EXE %WINDIR%\Microsoft.NET\Framework\v1.0.3705 %WINDIR%\Microsoft.NET\Framework\v1.0.3705 – Install Assembly hosting custom task in GAC, using GACUTIL.EXE C:\Program Files\Microsoft Visual Studio.NET\FrameworkSDK\Bin C:\Program Files\Microsoft Visual Studio.NET\FrameworkSDK\Bin – Set “Start Application” to: c:\windows\system32\mmc.exe – Set break points in custom task code – Start debugging (F5), which loads MMC.EXE – Load SQL Server snap-in & start DTS Designer

21. Debugging Custom Tasks… Create a small.NET application that wraps execution of a DTS Package Create a small.NET application that wraps execution of a DTS Package [MTAThread] public void Main() { try { Package2Class package = new Package2Class(); object pVarPersistStgOfHost = null; package.LoadFromSQLServer("(local)", null, null, DTSSQLServerStorageFlags.DTSSQLStgFlag_UseTrustedConnection, null, null, null, “MyPackageName", ref pVarPersistStgOfHost); package.Execute();package.UnInitialize(); package = null; } catch(COMException e) { // handle COM exceptions first } catch(System.Exception e) { // handle all other exceptions last } }

22. Deploying Custom Tasks DTS Package wrapper: DTS Package wrapper: – Copy the RCW for DTSPkg.DLL to local disk (created using TLBIMP, PIA or Managed C++ wrapper) – Register the RCW in the GAC using GACUTIL (good practice to remove old references first).NET Custom Task.NET Custom Task – Copy Custom Task to local disk – Register Assembly using REGASM – Register Custom Task in GAC using GACUTIL

23. Resources Microsoft Knowledge Base Articles: Microsoft Knowledge Base Articles: – Q319985 - HOW TO: Handle Data Transformation Services Package Events in Visual C#.NET http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319985 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319985 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319985 – Q321525 - HOW TO: Use DTS Package Events in Visual Basic.NET http://support.microsoft.com/default.aspx?scid=kb;EN-US;q321525 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q321525 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q321525 – Q323047 - Using COM Interfaces to Expand DTS Functionality http://support.microsoft.com/default.aspx?scid=kb;EN-US;q323047 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q323047 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q323047 – Q242391 - INF: DTS Package Development, Deployment and Performance http://support.microsoft.com/default.aspx?scid=kb;EN-US;q242391 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q242391 http://support.microsoft.com/default.aspx?scid=kb;EN-US;q242391 Web Sites and Newsgroups: Web Sites and Newsgroups: – http://www.sqldts.com http://www.sqldts.com – http://sqldev.net http://sqldev.net – Microsoft SQL Server newsgroups on msnews.microsoft.com public.microsoft.sqlserver.dts public.microsoft.sqlserver.dts

24. Questions? Slides & samples: http://sqldev.net/events.htm E-Mail: GertD@SQLDev.Net

25. © 2002 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

26. Backup slides Executing Package using Events

27. Execute Package using Events class ExecPkgWithEvents {[MTAThread] static void Main(string[] args) { ExecPkgWithEvents app = new ExecPkgWithEvents(); app.Run();} public Package2Class package; public void Run() { package = new Package2Class(); UCOMIConnectionPointContainer CnnctPtCont = (UCOMIConnectionPointContainer) package; UCOMIConnectionPoint CnnctPt; PackageEventsSink PES = new PackageEventsSink(); // UUID of PackageEvents Interface Guid guid = new Guid("10020605-EB1C-11CF-AE6E-00AA004A34D5"); CnnctPtCont.FindConnectionPoint(ref guid, out CnnctPt); int iCookie; CnnctPt.Advise(PES, out iCookie); object pVarPersistStgOfHost = null; package.LoadFromStorageFile(…);package.Execute();package.UnInitialize();} } // class ExecPkgWithEvents

28. Execute Package using Events … class PackageEventsSink : DTS.PackageEvents { public void OnQueryCancel(string EventSource, ref bool pbCancel) { Console.WriteLine("OnQueryCancel({0})", EventSource); pbCancel = false; } public void OnStart(string EventSource) { Console.WriteLine("OnStart({0})", EventSource); } public void OnProgress(string EventSource, string ProgressDescription, int PercentComplete, int ProgressCountLow, int ProgressCountHigh) { Console.WriteLine("OnProgress({0})”, EventSource); } public void OnError(string EventSource, int ErrorCode, string Source, string Description, string HelpFile, int HelpContext, string IDofInterfaceWithError, ref bool pbCancel) { Console.WriteLine("OnError({0}”, EventSource); pbCancel = false; } public void OnFinish(string EventSource) { Console.WriteLine("OnFinish({0})", EventSource); } } // class PackageEventsSink : DTS.PackageEvents

29. Resources from Microsoft Press For more information please visit the TechEd Bookshop. www.microsoft.com/mspress SQL SERVER 2000

30. Resources from Microsoft Press For more information please visit the TechEd Bookshop. www.microsoft.com/mspress VISUALBASIC.NET

31. Don’t forget to complete the on-line Session Feedback form on the Attendee Web site https://web.mseventseurope.com/teched/ https://web.mseventseurope.com/teched/