ColdFusion 9.0 Resources

cfobject: .NET object

Description

Creates a .NET object, that is, a ColdFusion proxy for accessing a class in a local or remote .NET assembly.

Syntax

<cfobject  
    class="class name" 
    name="instance name" 
    type=".NET|dotnet" 
    action="create" 
    assembly="absolute path" 
    port="6086" 
    protocol="tcp|http" 
    secure="no|yes" 
    server = "localhost">

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

History

ColdFusion 8: Added .NET and dotnet type values, and the assembly, port, protocol, and secure attributes.

Attributes

Attribute	Req/Opt	Default	Description
`class`	Required		Name of the .NET class to instantiate as an object.
`name`	Required		String; reference name of the component to use in your application.
`type`	Required for .NET		Object type. Must be `.NET` or `dotnet` for .NET objects.
`action`	Optional	create	Action to take. Must be `create`.
`assembly`	Optional.	mscorlib.dll which contains the .NET core classes.	For local .NET assemblies, the absolute path or paths to the assembly or assemblies (EXE or DLL files) from which to access the .NET class and its supporting classes. If a class in an assembly requires supporting classes that are in other assemblies, you must also specify those assemblies. You can, however, omit the supporting assemblies for the following types of supporting classes: .NET core classes (classes in mscorlib.dll) Classes in assemblies that are in the global assembly cache (GAC) To specify multiple assemblies, use a comma-delimited list. For remote .NET assemblies, you must specify the absolute path or paths of the local proxy JAR file or files that represent the assemblies. If you omit this attribute, and there is no local .NET installation, the tag fails without generating an error. If you omit this attribute, there is a local .NET installation, and the specified class is not in the .NET core classes, ColdFusion generates an error.
`port`	Optional	6086	Port number at which the .NET-side agent is listening.
`protocol`	Optional	`tcp`	Protocol to use for communication between ColdFusion and .NET. Must be one of the following values: `http`: Use HTTP/SOAP communication protocol. This option is slower than tcp, but might be required for access through a firewall. `tcp`: Use binary TCP/IP protocol. This method is more efficient than HTTP.
`secure`	Optional	`false`	Whether to secure communications with the .NET-side agent. If `true`, ColdFusion uses SSL to communicate with .NET.
`server`	Optional	`localhost`	Host name or IP address of the server where the .NET-side agent is running. Can be in any of these forms: server name (for example, myserver) IP address (for example, 127.0.0.1) You must specify this attribute to access .NET components on a remote server.

Usage

The cfobject tag with a .NET or dotnet value for the type attribute creates a reference to a .NET object of a given class. Using the reference, you can access the .NET object’s fields and methods. The .NET classes do not have to be local, and you can use the cfobject tag on a system that does not have .NET installed, including UNIX-based or OS-X systems.

To access .NET assemblies, do the following:

Install the ColdFusion 9 .NET Extension and run the .NET extension service on the system on which the assemblies are installed. You do not have to install the extension or run the extension service on a ColdFusion system that accesses only remote assemblies. For installation instructions, see Installing and Using ColdFusion.
If the assemblies are located on a remote system, create Java proxies for the .NET classes that you use, copy the proxies to the ColdFusion system, and configure the remote system for access by the proxies. For information on these steps, see Using Microsoft .NET Assemblies in the Developing ColdFusion Applications. If the .NET assemblies are on your ColdFusion system, you do not have to perform these steps.

Accessing methods and fields

You call .NET methods as you use any other ColdFusion object methods. In the simplest case, your application code uses the following format to call a .NET class method:

<cfobject type=".NET" name="mathInstance" class="mathClass">  
    assembly="C:/Net/Assemblies/math.dll"> 
<cfset myVar=mathInstance.multiply(1,2)>

If a .NET class has multiple constructors, and you do not want ColdFusion to use the default constructor to create the object, invoke a specific constructor by calling the special init method of the ColdFusion object with the constructor’s arguments. For example, you can use the following tags to instantiate com.foo.MyClass(int, int):

<cfobject type=".NET" class="com.foo.MyClass" 
    assembly="c:\temp\myLib.dll" name="myObj" > 
<cfset myObj.init(10, 5)>

You access and change .NET class public fields by calling the following methods:

Get_fieldName() 
Set_fieldName()

For example, if the .NET class has a public field named account, you can access and modify its value by using Get_acount() and Set_account() methods, respectively.

You can access, but not modify final fields, so you can only call Get_fieldName() for these fields.

Example

The following example uses the GetProcess method of the .NET System.Diagnostics.Process class to get and display information about the processes running on the local system. Because it uses a core .NET class, for which ColdFusion automatically generates proxies, you do not have to specify an assembly name in the cfobject tag.

For more complex examples, including examples that use custom .NET classes, see Using Microsoft .NET Assemblies in the Developing ColdFusion Applications.

<cfobject type=".NET" name="proc" class="System.Diagnostics.Process">  
<cfset processes = proc.GetProcesses()> 
<cfset arrLen = arrayLen(processes)> 
 
<table border=0 cellspacing="3" cellpadding="3"> 
    <tr bgcolor="#33CCCC"> 
        <td style="font-size:12px; font-weight:bold" nowrap>Process ID</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Name</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Memory (KB)</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Peak Memory (KB)</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Virtual Memory Size (KB)</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Start Time</td> 
        <td style="font-size:12px; font-weight:bold" nowrap>Total Processor Time</td> 
    </tr> 
    <cfloop from = 1 to="#arrLen#" index=i> 
        <cfset process = processes[i]> 
        <cfset id = process.Get_Id()> 
        <cfif id neq 0> 
            <cfoutput> 
            <tr> 
                <td align="right">#process.Get_Id()#</td> 
                <td>#process.Get_ProcessName()#</td> 
                <td align="right">#process.Get_PagedMemorySize()/1000#</td> 
                <td align="right">#process.Get_PeakPagedMemorySize()/1000#</td> 
                <td align="right">#process.Get_VirtualMemorySize()/1000#</td> 
                <td>#process.Get_StartTime()#</td> 
                <td>#process.Get_TotalProcessorTime()#</td> 
            </tr> 
            </cfoutput> 
        </cfif> 
    </cfloop> 
</table>