PageRenderTime 6ms CodeModel.GetById 1ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/Visual Studio 2008/CSRegFreeCOMClient/ReadMe.txt

#
Plain Text | 381 lines | 293 code | 88 blank | 0 comment | 0 complexity | e85fcbef14119be2d715e136726be841 MD5 | raw file
  1========================================================================
  2    LIBRARY APPLICATION : CSRegFreeCOMClient Project Overview
  3========================================================================
  4
  5/////////////////////////////////////////////////////////////////////////////
  6Summary:
  7
  8Registration-free COM is a mechanism available on the Microsoft Windows XP 
  9(SP2 for .NET Framework-based components), Microsoft Windows Server 2003 and 
 10newer platforms. As the name suggests, the mechanism enables easy (e.g. 
 11XCOPY) deployment of COM components to a machine without the need to register 
 12them.
 13
 14The CSRegFreeCOMClient sample demonstrates how to create a registration-free 
 15COM from the aspect of .NET Framework based client, so that the client can 
 16consume existing COM server as if the COM server is Registration-free.
 17
 18
 19/////////////////////////////////////////////////////////////////////////////
 20Sample Relation:
 21(Relation of the current sample and other samples in 
 22Microsoft All-In-One Code Framework http://cfx.codeplex.com)
 23
 24	CSRegFreeCOMClient -> ATLDllCOMServer
 25
 26
 27/////////////////////////////////////////////////////////////////////////////
 28Creation:
 29
 30A. The client automatically searches manifest file of its dependency, 
 31and use the manifest file to Activate the activation context.
 32
 33	Step1. 
 34	Add a reference to the ATLDllCOMServer COM component by right-clicking 
 35	the project, selecting "Add Reference...", turning to the COM tab, and 
 36	adding ATLDllCOMServer Type Library. Visual Studio will automatically 
 37	generate an interop assembly "Interop.ATLDllCOMServerLib.dll". If the
 38	ATLDllCOMServer Type Library is not in the list, please build and setup 
 39	the ATLDllCOMServer sample first.
 40
 41	Step2. 
 42	Create a thread whose thread apartement is set to STA, because we are 
 43	going to demonstrate the instantiation and use of a STA COM object: 
 44	ATLDllCOMServer.SimpleObject.
 45
 46	Step3. 
 47	Create method ConsumeCOMComponent which contains logic of consuming COM 
 48	server.
 49
 50	Step4. 
 51	Add app.manifest file by right-clicking the project, selecting "Add" 
 52	--> "New Item" --> "General" --> "Application Manifest File" and click 
 53	Add button. 
 54
 55	Step5. 
 56	Open the app.manifest file, find assemblyIdentity element, modify its 
 57	Name property to CSRegFreeCOMClient:
 58	
 59		<assemblyIdentity version="1.0.0.0" name="CSRegFreeCOMClient"/>
 60    
 61	Step6. 
 62	Add dependency element immediate after assemblyIdentity node:
 63	
 64		<dependency>
 65		<dependentAssembly>
 66		  <assemblyIdentity
 67					  type="win32"
 68					  name="ATLDllCOMServer.X"
 69					  version="1.0.0.0" />
 70		</dependentAssembly>
 71		</dependency>
 72	
 73	Step7. 
 74	Open property page of the app.manifest file by right-clicking the file 
 75	and selecting Property, change the value of Build Action dropdown to 
 76	Embedded Resource, and rebuild the application.
 77
 78	Step8. 
 79	Open the application's output folder (Debug or Release folder), put a 
 80	copy of ATLDllCOMServer.dll to this folder,	create a txt file and rename 
 81	it (including file extention) to ATLDllCOMServer.X.manifest, input the 
 82	following content:
 83
 84		<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 85		<assembly xmlns="urn:schemas-microsoft-com:asm.v1"  manifestVersion="1.0">
 86
 87			<assemblyIdentity
 88			   type="win32"
 89			   name="ATLDllCOMServer.X"
 90			   version="1.0.0.0" />
 91			   
 92			<file name = "ATLDllCOMServer.dll">
 93				<comClass clsid="{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}"
 94					threadingModel = "Apartment" />
 95				    
 96				<typelib tlbid="{9B23EFED-A0C1-46B6-A903-218206447F3E}"
 97					   version="1.0" helpdir=""/>
 98			</file>
 99
100			<comInterfaceExternalProxyStub
101				name="ISimpleObject"
102				iid="{830F85D0-91B9-406D-A273-BC33133DD44B}"
103				proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
104				baseInterface="{00000000-0000-0000-C000-000000000046}"
105				tlbid = "{9B23EFED-A0C1-46B6-A903-218206447F3E}" />
106			    
107		</assembly>
108		
109	Step9. 
110	Unregistry the ATLDllCOMServer.dll, then run CSRegFreeCOMClient.exe.
111	the output is:
112	
113		------Activate activation context automatically------
114		Call HelloWorld => HelloWorld
115		Press any key to continue...
116		
117B. The client activates activation context by specifying manifest file 
118manually.
119
120	Step1. 
121	Add a reference to the ATLDllCOMServer COM component by right-clicking 
122	the project, selecting "Add Reference...", turning to the COM tab, and 
123	adding ATLDllCOMServer Type Library. Visual Studio will automatically 
124	generate an interop assembly "Interop.ATLDllCOMServerLib.dll". If the 
125	ATLDllCOMServer Type Library is not in the list, please build and setup 
126	the ATLDllCOMServer sample first.
127
128	Step2. 
129	Create a thread whose thread apartement is set to STA, because we are 
130	going to demonstrate the instantiation and use of a STA COM object: 
131	ATLDllCOMServer.SimpleObject.
132
133	Step3. 
134	Create method ConsumeCOMComponent which contains logic of consuming COM 
135	server.
136
137	Step4. 
138	Create the ActivateActivationContext method which is used to activate 
139	the activation context according to given manifest file.
140
141	Step5. 
142	Add app.manifest file by right-clicking the project, selecting "Add" 
143	--> "New Item" --> "General" --> "Application Manifest File" and click 
144	"Add" button. 
145
146	Step6. 
147	Open the app.manifest file, find assemblyIdentity element, modify its 
148	Name property to CSRegFreeCOMClient:
149	
150		<assemblyIdentity version="1.0.0.0" name="CSRegFreeCOMClient"/>
151    
152	Step7. 
153	Add dependency element immediate after assemblyIdentity node:
154		
155		<dependency>
156		<dependentAssembly>
157		  <assemblyIdentity
158					  type="win32"
159					  name="ATLDllCOMServer.X"
160					  version="1.0.0.0" />
161		</dependentAssembly>
162		</dependency>
163		
164	Step8. 
165	Open property page of the app.manifest file by right-clicking the file 
166	and select Property, change the value of Build Action dropdown to 
167	Embedded Resource, and rebuild the application.
168
169	Step9. 
170	Create a new folder, for example, "D:\regfreecom", put a copy of 
171	ATLDllCOMServer.dll to this folder, create a txt file and rename it 
172	(including file extention) to ATLDllCOMServer.X.manifest, input following 
173	content:
174
175		<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
176		<assembly xmlns="urn:schemas-microsoft-com:asm.v1"  manifestVersion="1.0">
177
178			<assemblyIdentity
179			   type="win32"
180			   name="ATLDllCOMServer.X"
181			   version="1.0.0.0" />
182			   
183			<file name = "ATLDllCOMServer.dll">
184				<comClass clsid="{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}"
185					threadingModel = "Apartment" />
186				    
187				<typelib tlbid="{9B23EFED-A0C1-46B6-A903-218206447F3E}"
188					   version="1.0" helpdir=""/>
189			</file>
190
191			<comInterfaceExternalProxyStub
192				name="ISimpleObject"
193				iid="{830F85D0-91B9-406D-A273-BC33133DD44B}"
194				proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
195				baseInterface="{00000000-0000-0000-C000-000000000046}"
196				tlbid = "{9B23EFED-A0C1-46B6-A903-218206447F3E}" />
197			    
198		</assembly>
199		
200	Step10. 
201	Unregistry the ATLDllCOMServer.dll, launch cmd.exe and navigate to the 
202	folder where CSRegFreeCOMClient.exe exists, start CSRegFreeCOMClient.exe 
203	with command:
204
205		CSRegFreeCOMClient.exe someargs
206		
207	then, you will be required to input manifest file path:
208
209		------ Activate activation context manually ------
210		Please input the full path of manifest file:
211		
212	in this case, since we put the manifest file at D:\regfreecom, so we 
213	input:
214
215		D:\regfreecom\ATLDllCOMServer.X.manifest
216
217	the full output is:
218
219		------ Activate activation context manually ------
220		Please input the full path of manifest file:
221		D:\regfreecom\ATLDllCOMServer.X.manifest
222		Call HelloWorld => HelloWorld
223		Press any key to continue...
224
225
226/////////////////////////////////////////////////////////////////////////////
227FAQ:
228
2291. How can I get the CLSID, tlbID, iid etc if it is a third-party dll?
230To build a reg-free version for a given com dll, the key point it to 
231construct a correct manifest file for the com dll, here is some tip for you:
232
233   1. Make sure that the dll has no embedded manifest, if there is, a 
234      separate manifest file will no take effect, manifest view can help to 
235      verify whether a dll has embedded manifest.( but you can modify the 
236      embedded manifest using some tools, anyway, it is not suggested).
237      
238   2. Create a manifest file for the dll, the file usually looks like:
239   
240		<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
241		<assembly xmlns="urn:schemas-microsoft-com:asm.v1"
242		  manifestVersion="1.0">
243
244			<assemblyIdentity
245			   type="win32"
246			   name=" mycomdll.x"
247			   version="1.0.0.0" />
248
249			<file name = "mycomdll.dll">
250			
251				<comClass
252					clsid="{[CLSID_ MyComClass]}"
253					threadingModel = "Apartment" />
254
255				<typelib tlbid="{[LIBID_ MyComClass]}"
256					   version="1.0" helpdir=""/>
257					   
258			</file>
259
260			<comInterfaceExternalProxyStub
261				name=" ISomeInterface "
262				iid="{[IID_I SomeInterface]}"
263				proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
264				baseInterface="{00000000-0000-0000-C000-000000000046}"
265				tlbid = "{[LIBID_ MyComClass ]}" />
266		    
267		</assembly>
268
269   3. To get values for placeholders in the manifest, we can use OLE/COM 
270   ObjectViewer (Oleview.exe) tool. 
271   
272   Open Oleview.exe ( on Vista or Win7, you may run it as administrator),
273   click File -> View TypeLib… --> select target com dll and click OK, 
274   let's open ATLDllCOMServer.dll, and you will see:
275
276		// Generated .IDL file (by the OLE/COM Object Viewer)
277		// 
278		// typelib filename: ATLDllCOMServer.dll
279
280		[
281		  uuid(9B23EFED-A0C1-46B6-A903-218206447F3E),
282		  version(1.0),
283		  helpstring("ATLDllCOMServer 1.0 Type Library"),
284		  custom(DE77BA64-517C-11D1-A2DA-0000F8773CE9, 117441012),
285		  custom(DE77BA63-517C-11D1-A2DA-0000F8773CE9, 1269332262),
286		  custom(DE77BA65-517C-11D1-A2DA-0000F8773CE9, "Created by MIDL version 7.00.0500 at Tue Mar 23 16:17:41 2010
287		")
288
289		]
290		library ATLDllCOMServerLib
291		{
292			// TLib :     // TLib : OLE Automation : {00020430-0000-0000-C000-000000000046}
293			importlib("stdole2.tlb");
294
295			// Forward declare all types defined in this typelib
296			dispinterface _ISimpleObjectEvents;
297			interface ISimpleObject;
298
299			[
300			  uuid(87AD6FBC-8735-407C-9758-C80B48C78E7C),
301			  helpstring("_ISimpleObjectEvents Interface")
302			]
303			dispinterface _ISimpleObjectEvents {
304				properties:
305				methods:
306					[id(0x00000001), helpstring("method FloatPropertyChanging")]
307					void FloatPropertyChanging(
308									[in] single NewValue, 
309									[in, out] VARIANT_BOOL* Cancel);
310			};
311
312			[
313			  uuid(92FCF37F-F6C7-4F8A-AA09-1A14BA118084),
314			  helpstring("SimpleObject Class")
315			]
316			coclass SimpleObject {
317				[default] interface ISimpleObject;
318				[default, source] dispinterface _ISimpleObjectEvents;
319			};
320
321			[
322			  odl,
323			  uuid(830F85D0-91B9-406D-A273-BC33133DD44B),
324			  helpstring("ISimpleObject Interface"),
325			  dual,
326			  nonextensible,
327			  oleautomation
328			]
329			interface ISimpleObject : IDispatch {
330				[id(0x00000001), propget, helpstring("property FloatProperty")]
331				HRESULT FloatProperty([out, retval] single* pVal);
332				[id(0x00000001), propput, helpstring("property FloatProperty")]
333				HRESULT FloatProperty([in] single pVal);
334				[id(0x00000002), helpstring("method HelloWorld")]
335				HRESULT HelloWorld([out, retval] BSTR* pRet);
336				[id(0x00000003), helpstring("method GetProcessThreadID")]
337				HRESULT GetProcessThreadID(
338								[out] long* pdwProcessId, 
339								[out] long* pdwThreadId);
340			};
341		};
342
343   6. With above information, we can fill in the manifest as following:
344
345			<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
346			<assembly xmlns="urn:schemas-microsoft-com:asm.v1"  manifestVersion="1.0">
347
348				<assemblyIdentity
349				   type="win32"
350				   name="ATLDllCOMServer.X"
351				   version="1.0.0.0" />
352				   
353				<file name = "ATLDllCOMServer.dll">
354					<comClass clsid="{92FCF37F-F6C7-4F8A-AA09-1A14BA118084}"
355						threadingModel = "Apartment" />
356					    
357					<typelib tlbid="{9B23EFED-A0C1-46B6-A903-218206447F3E}"
358						   version="1.0" helpdir=""/>
359				</file>
360
361				<comInterfaceExternalProxyStub
362					name="ISimpleObject"
363					iid="{830F85D0-91B9-406D-A273-BC33133DD44B}"
364					proxyStubClsid32="{00020424-0000-0000-C000-000000000046}"
365					baseInterface="{00000000-0000-0000-C000-000000000046}"
366					tlbid = "{9B23EFED-A0C1-46B6-A903-218206447F3E}" />
367				    
368			</assembly>
369
370
371/////////////////////////////////////////////////////////////////////////////
372References:
373
374Registration-Free Activation of COM Components: A Walkthrough
375http://msdn.microsoft.com/en-us/library/ms973913.aspx
376
377Registration-Free Activation of .NET-Based Components: A Walkthrough
378http://msdn.microsoft.com/en-us/library/ms973915.aspx
379
380
381/////////////////////////////////////////////////////////////////////////////