PageRenderTime 13ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/Visual Studio 2008/CSDllCOMServer/ReadMe.txt

#
Plain Text | 215 lines | 151 code | 64 blank | 0 comment | 0 complexity | 7bf108986eae4dfecd423e78121fc496 MD5 | raw file
  1========================================================================
  2    LIBRARY APPLICATION : CSDllCOMServer Project Overview
  3========================================================================
  4
  5/////////////////////////////////////////////////////////////////////////////
  6Summary:
  7
  8This Visual C# sample focuses on exposing .NET Framework components to COM,  
  9which allows us to write a .NET type and consuming that type from unmanaged  
 10code with distinct activities for COM developers.
 11
 12There are basically three methods to define the class interface for a 
 13component:
 14
 151. Explicitly Define the Class Interface with 
 16[ClassInterface(ClassInterfaceType.None)] 
 17
 18This is the recommended way if you are going to expose your .NET class to COM 
 19aware clients. The code in SimpleObject demonstrates this method.
 20
 212. Implicitly Define the Class Interface with 
 22[ClassInterface(ClassInterfaceType.AutoDual)] or 
 23[ClassInterface(ClassInterfaceType.AutoDispatch)].
 24
 25Using ClassInterface to expose the public methods of a .NET class is NOT 
 26generally recommended because it's creedless to COM versioning. This method 
 27is not demonstrated in this code sample.
 28
 293. Use Microsoft.VisualBasic.ComClassAttribute
 30
 31The ComClassAttribute attribute instructs the compiler to add metadata that 
 32allows a class to be exposed as a COM object. It simplifies the process of 
 33exposing COM components from Visual Basic. Without ComClassAttribute, you 
 34need to follow a number of steps to generate a COM object from Visual Basic. 
 35For classes marked with ComClassAttribute, the compiler performs many of 
 36these steps automatically. The sample VBDllCOMServer demonstrates the use of 
 37the attribute. Visual C# can also benefit from ComClassAttribute, as long as 
 38the project references the Microsoft.VisualBasic assembly. This method is 
 39not demonstrated in the code sample.
 40
 41CSDllCOMServer exposes the following component:
 42
 43SimpleObject whose class interface is explicitly defined.
 44
 45  Program ID: CSDllCOMServer.SimpleObject
 46  CLSID_CSExplicitInterfaceObject: 4B65FE47-2F9D-37B8-B3CB-5BE4A7BC0926
 47  IID_ICSExplicitInterfaceObject: 32DBA9B0-BE1F-357D-827F-0196229FA0E2
 48  DIID_ICSExplicitInterfaceObjectEvents: 95DB823B-E204-428c-92A3-7FB29C0EC576
 49  LIBID_CSDllCOMServer: F0998D9A-0E79-4F67-B944-9E837F479587
 50
 51  Properties:
 52    // With both get and set accessor methods
 53    float FloatProperty
 54
 55  Methods:
 56    // HelloWorld returns a string "HelloWorld"
 57    string HelloWorld();
 58    // GetProcessThreadID outputs the running process ID and thread ID
 59    void GetProcessThreadID(out uint processId, out uint threadId);
 60
 61  Events:
 62    // FloatPropertyChanging is fired before new value is set to the 
 63    // FloatProperty property. The Cancel parameter allows the client to 
 64    // cancel the change of FloatProperty.
 65    void FloatPropertyChanging(float NewValue, ref bool Cancel);
 66
 67NOTE: The GUIDs used in this sample are generated by guidgen.exe (Visual 
 68Studio / Tools / Create GUID). When you write your own COM objects, you need 
 69to generate and use new GUIDs.
 70
 71NOTE: COM components or ActiveX controls written in .NET languages cannot 
 72be referenced by .NET applications in the form of interop assemblies. If you 
 73"add reference" to such a TLB, or drag & drop such an ActiveX control to your 
 74.NET application, you will get an error "The ActiveX type library 'XXXXX.tlb' 
 75was exported from a .NET assembly and cannot be added as a reference.". The 
 76correct approach is to add a reference to the .NET assembly directly.
 77
 78
 79/////////////////////////////////////////////////////////////////////////////
 80Sample Relation:
 81(Relation of the current sample and other samples in 
 82Microsoft All-In-One Code Framework http://cfx.codeplex.com)
 83
 84CppCOMClient -> CSDllCOMServer
 85CppCOMClient consumes this C# component using #import and the smart pointers.
 86
 87CSDllCOMServer - VBDllCOMServer
 88These COM samples expose the same set of properties, methods, and events, 
 89but they are implemented in different .NET languages.
 90
 91CSDllCOMServer - CSCOMService
 92Both are COM components written in Visual C#. CSDllCOMServer is an in-process
 93component in the form of DLL. CSCOMService is an out-of-process component in 
 94the form of Windows Service. 
 95
 96
 97/////////////////////////////////////////////////////////////////////////////
 98Deployment:
 99
100A. Setup
101
102Regasm.exe CSDllCOMServer.dll
103It registers the types that are COM-visible in CSDllCOMServer.dll.
104
105B. Cleanup
106
107Regasm.exe /u CSDllCOMServer.dll
108It unregisters the types that are COM-visible in CSDllCOMServer.dll.
109
110
111/////////////////////////////////////////////////////////////////////////////
112Creation:
113
114A. Creating the project
115
116Step1. Create a Visual C# / Class Library project named CSDllCOMServer in 
117Visual Studio 2008.
118
119Step2. In order to make the .NET assembly COM-visible, first, open the 
120property of the project. Click the Assembly Information button in the page, 
121Application, and select the "Make Assembly COM-Visible" box. This corresponds 
122to the assembly attribute ComVisible in AssemblyInfo.cs:
123
124	[assembly: ComVisible(true)]
125
126The GUID value in the dialog is the libid of the component:
127
128	[assembly: Guid("f0998d9a-0e79-4f67-b944-9e837f479587")]
129
130Second, in the Build page of the project's property, select the option 
131"Register for COM interop". This option specifies whether your managed 
132application will expose a COM object (a COM-callable wrapper) that allows a 
133COM object to interact with your managed application.
134
135B. Adding a component whose interface is explicitly defined
136
137Step1. Define a "public" interface ICSExplicitInterfaceObject to describe the 
138COM interface of the coclass. Specify its GUID, aka IID, using GuidAttribute: 
139
140	[Guid("32DBA9B0-BE1F-357D-827F-0196229FA0E2")]
141	
142In this way, IID of the COM object is a fixed value. By default, the 
143interfaces used by a .NET Class are transformed to dual interfaces 
144[InterfaceType(ComInterfaceType.InterfaceIsDual)] in the IDL. This allows the
145client to get the best of both early binding and late binding. Other options  
146are [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] and 
147[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)].
148
149Step2. Inside the interface ICSExplicitInterfaceObject, define the prototypes 
150of the properties and methods to be exported. The terms marked as 
151[ComVisible(false)] are not exported.
152
153Step3. Define a "public" interface ICSExplicitInterfaceObjectEvents to 
154describe the events the coclass can sink. Specify its GUID, aka the Events Id, 
155using GuidAttribute:
156
157	[Guid("95DB823B-E204-428c-92A3-7FB29C0EC576")]
158	
159Decorate the interface as an IDispatch interface:
160
161	[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
162
163Step4. Inside the interface ICSExplicitInterfaceObjectEvents, define the 
164prototype of the events to be exported.
165
166Step5. Define a "public" class CSExplicitInterfaceObject that implements the 
167interface ICSExplicitInterfaceObject. Attach the attribute 
168[ClassInterface(ClassInterfaceType.None)] to it, which tells the type-library
169generation tools that we do not require a Class Interface. This ensures that 
170the ICSExplicitInterfaceObject interface is the default interface. In addition, 
171specify the GUID of the class, aka CLSID, using the Guid attribute:
172
173	[Guid("4B65FE47-2F9D-37B8-B3CB-5BE4A7BC0926")]
174
175In this way, CLSID of the COM object is a fixed value. Last, decorate the 
176class with a ComSourceInterface attribute:
177
178	[ComSourceInterfaces(typeof(ICSExplicitInterfaceObjectEvents))]
179
180ComSourceInterfaces identifies a list of interfaces that are exposed as	COM 
181event sources for the attributed class.
182
183Step6. Make sure that the constructor of the class CSExplicitInterfaceObject 
184is not private (we can either add a public constructor or use the default 
185one), so that the COM object is creatable from the COM aware clients.
186
187Step7. Inside CSExplicitInterfaceObject, implement the interface 
188ICSExplicitInterfaceObject by writing the body of the property FloatProperty 
189and the methods HelloWorld,  GetProcessThreadID and HiddenFunction.
190
191Step8. Build the project. If a stand-alone tlb file, CSDllCOMServer.tlb, is 
192created in the output folder, it basically means that the project is built 
193successfully.
194
195
196/////////////////////////////////////////////////////////////////////////////
197References:
198
199Exposing .NET Framework Components to COM
200http://msdn.microsoft.com/en-us/library/zsfww439.aspx
201
202COM Interop Part 2: C# Server Tutorial
203http://msdn.microsoft.com/en-us/library/aa645738.aspx
204
205Building COM Servers in .NET By Lim Bio Liong
206http://www.codeproject.com/KB/COM/BuildCOMServersInDotNet.aspx
207
208Understanding Classic COM Interoperability With .NET Applications By Aravind
209http://www.codeproject.com/KB/COM/cominterop.aspx
210
211KB: How to develop an in-process COM component 
212http://support.microsoft.com/kb/976026/en-us
213
214
215/////////////////////////////////////////////////////////////////////////////