Object Construction Technology Sample

  • Article

This sample demonstrates the use of object construction strings in a .NET environment. Object construction strings are initialization strings that can be specified or edited through the Component Services administrative tool, eliminating the need to hard code configuration information within components. The sample's user interface is a form with one button, which creates an object that uses construction strings. Message boxes display the various stages of activation.

For information about using the samples, see the following topics:

To build the sample using the command prompt

  1. Open the Command Prompt window and navigate to one of the language-specific subdirectories under the Technologies\ComponentServices\ObjectConstruction directory.

  2. Type msbuild ObjectConstructionCS.sln or msbuild ObjectConstructionVB.sln, depending on your choice of programming language.

To build the sample using Visual Studio

  1. Open Windows Explorer and navigate to one of the language-specific subdirectories under the Technologies\ComponentServices\ObjectConstruction directory.

  2. Double-click the icon for ObjectConstructionCS.sln or ObjectConstructionVB.sln, depending on your choice of programming language, to open the file in Visual Studio.

  3. On the Build menu, click Build Solution.

To run the sample

  1. Open the Command Prompt window or Windows Explorer and navigate to the directory that contains the built executable file.

  2. Type OCDemo.exe at the command line, or start the executable file by double-clicking it in Windows Explorer. Note whether you are executing the C# (in the \CS subdirectory) or Visual Basic (in the \VB subdirectory) version of the sample application, as this will determine which COM+ component attributes you will edit administratively in a subsequent step.

  3. When the program starts, click the button labeled Create Object. A message box will appear at each stage of activation. Note the object construction string value reported in the call to IObjectConstruct::Construct.

  4. Start the Component Services Administrative Tool by clicking Start -> All Programs -> Administrative Tools -> Component Services, and locate the OCDemoSvr COM+ application by expanding Component Services\Computers\My Computer\COM+ Applications in the left-hand explorer pane.

  5. Locate the Microsoft.Samples.Technologies.ComponentServices.ObjectConstruction.ObjectConstructionTest component by expanding OCDemoSvr\Components.

  6. Right-click the ObjectConstructionTest component and select Properties from the popup menu.

  7. Click the Activation tab and enter a new text value in the Constructor string edit field. Click OK to accept the change.

  8. Return to the OCDemo application and click Create Object again. Note the new value that is reported by the IObjectConstruct method (it should match the newly edited string from the COM+ explorer component properties page).

To uninstall the sample

  1. Navigate to the directory where you ran msbuild.exe or opened the .sln file.

  2. Type msbuild.exe ObjectConstructionVB.sln /t:Clean or msbuild.exe ObjectConstructionCS.sln /t:Clean, depending on your choice of programming language, at the command line. This calls the .NET Services Installation Tool (Regsvcs.exe) and the Global Assembly Cache Tool (Gacutil.exe) with the /u switch to remove the sample files from the COM+ catalog and the global assembly cache.

Requirements

Platform: Windows 2000, Windows XP, Windows Server 2003

.NET Framework Version: 2.0, 1.1, 1.0

Remarks

For more information about sample binary creation and registration steps, review the comments in the source code files.

This procedure shows how to create a COM+ component with object construction enabled and using a default construction string. On creating an object instance, various component methods display message boxes to demonstrate call order. You modify the object construction string by using the Component Services administration tool and re-run the sample to observe that the object construction string passed to the component instance has changed.

NoteNote

You must use the Global Assembly Cache Tool (Gacutil.exe) to install the OCDemoSvr.dll assembly into the global assembly cache before you run the sample. Gacutil.exe is located in the SDK\<version>\Bin directory. For example, if you built the Visual Basic version of the sample, navigate to the C:\Documents and Settings\Your User Name\My Documents\ Samples\Technologies\ComponentServices\ObjectConstruction\VB directory and type gacutil -i OCDemoSvr.dll.

The component name as viewed in the Component Services administrative tool is Microsoft.Samples.Technologies.ComponentServices.ObjectConstruction.ObjectConstructionTest.

When object construction is enabled for a component, COM+ calls and implements the IObjectContruct::Construct method immediately after it creates an instance of the object. The object construction string specified in the component's activation properties is passed as an argument to the method. This, in combination with component code that properly uses the object string, effectively provides parameterized object construction.

You can specify a default string value for the construction string in the Default property of the ConstructionEnabledAttribute, in the COM+ catalog, or both.

A component developer might use this feature, for example, to write a component that holds a generic ODBC connection. The object construction string would hold an exact DSN that could be changed through the Component Services administrative tool.

Object construction strings can be useful in combination with COM+ object pooling services.

See Also

Reference

Global Assembly Cache Tool (Gacutil.exe)
ConstructionEnabledAttribute
ServicedComponent
System.EnterpriseServices
System.Reflection

Concepts

Object Construction
Using COM Types in Managed Code

Other Resources

Writing Serviced Components