Pro CSharp And The .NET 2.0 Platform (2005) [eng]

604 CHAPTER 18 ■ THE .NET REMOTING LAYER

■Source Code The AsyncWKOCarProviderClient project is located under the Chapter 18 subdirectory.

The Role of the [OneWay] Attribute

Imagine that your CarProvider has a new method named AddCar(), which takes a JamesBondCar input parameter and returns nothing. The key point is that it returns nothing. As you might assume given the name of the System.Runtime.Remoting.Messaging.OneWayAttribute class, the .NET remoting layer passes the call to the remote one-way method, but does not bother to set up the infrastructure used to return a given value (hence the name one-way). Here is the update:

// Home of the [OneWay] attribute. using System.Runtime.Remoting.Messaging;

...

namespace CarGeneralAsm

{

public class CarProvider : MarshalByRefObject

{

...

// The client can 'fire and forget' when calling this method.

[OneWay]

public void AddCar(JamesBondCar newJBC) { theJBCars.Add(newJBC);}

}

}

Callers would invoke this method directly as always:

//Make the car provider.

CarProvider cp = new CarProvider();

//Add a new car.

cp.AddCar(new JamesBondCar("Zippy", 200, false, false));

From the client’s point of view, the call to AddCar() is completely asynchronous, as the CLR will ensure that a background thread is used to remotely trigger the method. Given that AddCar() has been decorated with the [OneWay] attribute, the client is unable to obtain any return value from the call. Because AddCar() returns void, this is not an issue.

In addition to this restriction, also be aware that if you have a [OneWay] method that defines output or reference parameters (via the out or ref keyword), the caller will not be able to obtain the callee’s modification(s). Furthermore, if the [OneWay] method happens to throw an exception (of any type), the caller is completely oblivious of this fact. In a nutshell, remote objects can mark select methods as [OneWay] to allow the caller to employ a fire-and-forget mentality.

Summary

In this chapter, you examined how to configure distinct .NET assemblies to share types between application boundaries. As you have seen, a remote object may be configured as an MBV or MBR type. This choice ultimately controls how a remote type is realized in the client’s application domain (a copy or transparent proxy).

If you have configured a type to function as an MBR entity, you are suddenly faced with a number of related choices (WKO versus CAO, single call versus singleton, and so forth), each of which was addressed during this chapter. As well, you examined the process of tracking the lifetime of a remote object via the use of leases and lease sponsorship. Finally, you revisited of the role of the .NET delegate type to understand how to asynchronously invoke a remote method (which, as luck would have it, is identical to the process of asynchronously invoking a local type).

606 CHAPTER 19 ■ BUILDING A BETTER WINDOW WITH SYSTEM.WINDOWS.FORMS

Given that the total number of types within System.Windows.Forms is well over 100 strong, it would be redundant (not to mention a terrible waste of paper) to list every member of the Windows Forms family. To set the stage for the next several chapters, however, Table 19-1 lists some of the core .NET 2.0 System.Windows.Forms types (consult the .NET Framework 2.0 SDK documentation for full details).

Table 19-1. Core Types of the System.Windows.Forms Namespace

■Note In addition to System.Windows.Forms, the System.Windows.Forms.dll assembly defines additional GUI-centric namespaces. For the most part, these additional types are used internally by the Forms engine and/or the designer tools of Visual Studio 2005. Given this fact, we will keep focused on the core

System.Windows.Forms namespace.

Working with the Windows Forms Types

When you build a Windows Forms application, you may choose to write all the relevant code by hand (using Notepad or TextPad, perhaps) and feed the resulting *.cs files into the C# compiler using the /target:winexe flag. Taking time to build some Windows Forms applications by hand not only is a great learning experience, but also helps you understand the code generated by the various graphics designers found within various .NET IDEs.

To make sure you truly understand the basic process of building a Windows Forms application, the initial examples in this chapter will avoid the use of graphics designers. Once you feel comfortable with the process of building a Windows Forms application “wizard-free,” you will then leverage the various designer tools provided by Visual Studio 2005.

Building a Main Window by Hand

To begin learning about Windows Forms programming, you’ll build a minimal main window from scratch. Create a new folder on your hard drive (e.g., C:\MyFirstWindow) and create a new file within this directory named MainWindow.cs using your editor of choice.

In the world of Windows Forms, the Form class is used to represent any window in your application. This includes a topmost main window in a single-document interface (SDI) application, modeless and modal dialog boxes, and the parent and child windows of a multiple-document interface (MDI) application. When you are interested in creating and displaying the main window in your program, you have two mandatory steps:

1. Derive a new class from System.Windows.Forms.Form.

2. Configure your application’s Main() method to invoke Application.Run(), passing an instance of your Form-derived type as an argument.

Given this, update your MainWindow.cs file with the following class definition:

using System;

using System.Windows.Forms;

namespace MyWindowsApp

{

public class MainWindow : Form

{

// Run this application and identify the main window. static void Main(string[] args)

{

Application.Run(new MainWindow());

}

}

}

In addition to the always present mscorlib.dll, a Windows Forms application needs to reference the System.dll and System.Windows.Forms.dll assemblies. As you may recall from Chapter 2, the default C# response file (csc.rsp) instructs csc.exe to automatically include these assemblies during the compilation process, so you are good to go. Also recall that the /target:winexe option of csc.exe instructs the compiler to generate a Windows executable.

■Note Technically speaking, you can build a Windows application at the command line using the /target:exe option; however, if you do, you will find that a command window will be looming in the background (and it will stay there until you shut down the main window). When you specify /target:winexe, your executable runs as a native Windows Forms application (without the looming command window).

To compile your C# code file, open a Visual Studio 2005 command prompt and issue the following command:

csc /target:winexe *.cs

Figure 19-1 shows a test run.

The Role of the Application Class

The Application class defines numerous static members that allow you to control various low-level behaviors of a Windows Forms application. For example, the Application class defines a set of events that allow you to respond to events such as application shutdown and idle-time processing. In addition to the Run() method, here are some other methods to be aware of:

•DoEvents(): Provides the ability for an application to process messages currently in the message queue during a lengthy operation.

•Exit(): Terminates the Windows application and unloads the hosting AppDomain.

•EnableVisualStyles(): Configures your application to support Windows XP visual styles. Do note that if you enable XP styles, this method must be called before loading your main window via Application.Run().

The Application class also defines a number of properties, many of which are read-only in nature. As you examine Table 19-2, note that most of these properties represent an “application-level” trait such as company name, version number, and so forth. In fact, given what you already know about assembly-level attributes (see Chapter 12), many of these properties should look vaguely familiar.

Table 19-2. Core Properties of the Application Type

Finally, the Application class defines various static events, some of which are as follows:

•ApplicationExit: Occurs when the application is just about to shut down

•Idle: Occurs when the application’s message loop has finished processing the current batch of messages and is about to enter an idle state (as there are no messages to process at the current time)

•ThreadExit: Occurs when a thread in the application is about to terminate

Fun with the Application Class

To illustrate some of the functionality of the Application class, let’s enhance your current MainWindow to perform the following:

•Reflect over select assembly-level attributes.

•Handle the static ApplicationExit event.

The first task is to make use of select properties in the Application class to reflect over some assembly-level attributes. To begin, add the following attributes to your MainWindow.cs file (note you are now using the System.Reflection namespace):

using System;

using System.Windows.Forms; using System.Reflection;

610 CHAPTER 19 ■ BUILDING A BETTER WINDOW WITH SYSTEM.WINDOWS.FORMS

// Some attributes regarding this assembly.

[assembly:AssemblyCompany("Intertech Training")] [assembly:AssemblyProduct("A Better Window")] [assembly:AssemblyVersion("1.1.0.0")]

namespace MyWindowsApp

{

...

}

Rather than manually reflecting over the [AssemblyCompany] and [AssemblyProduct] attributes using the techniques illustrated in Chapter 12, the Application class will do so automatically using various static properties. To illustrate, implement the default constructor of MainForm as so:

public class MainWindow : Form

{

public MainWindow()

{

MessageBox.Show(Application.ProductName, string.Format("This app brought to you by {0}", Application.CompanyName));

}

}

When you run this application, you’ll see a message box that displays various bits of information (see Figure 19-2).

Figure 19-2. Reading attributes via the Application type

Now, let’s equip this Form to respond to the ApplicationExit event. When you wish to respond to events from within a Windows Forms application, you will be happy to find that the same event syntax detailed in Chapter 8 is used to handle GUI-based events. Therefore, if you wish to intercept the static ApplicationExit event, simply register an event handler using the += operator:

public class MainForm : Form

{

public MainForm()

{

...

// Intercept the ApplicationExit event.

Application.ApplicationExit += new EventHandler(MainWindow_OnExit);

}

private void MainWindow_OnExit(object sender, EventArgs evArgs)

{

MessageBox.Show(string.Format("Form version {0} has terminated.", Application.ProductVersion));

}

}

612 CHAPTER 19 ■ BUILDING A BETTER WINDOW WITH SYSTEM.WINDOWS.FORMS

Although the complete derivation of a Form type involves numerous base classes and interfaces, do understand that you are not required to learn the role of each and every member from each and every parent class or implemented interface to be a proficient Windows Forms developer. In fact, the majority of the members (properties and events in particular) you will use on a daily basis are easily set using the Visual Studio 2005 IDE Properties window. Before we move on to examine some specific members inherited from these parent classes, Table 19-3 outlines the basic role of each base class.

Table 19-3. Base Classes in the Form Inheritance Chain

As you might guess, detailing each and every member of each class in the Form’s inheritance chain would require a large book in itself. However, it is important to understand the behavior supplied by the Control and Form types. I’ll assume that you will spend time examining the full details behind each class at your leisure using the .NET Framework 2.0 SDK documentation.

The Functionality of the Control Class

The System.Windows.Forms.Control class establishes the common behaviors required by any GUI type. The core members of Control allow you to configure the size and position of a control, capture keyboard and mouse input, get or set the focus/visibility of a member, and so forth. Table 19-4 defines some (but not all) properties of interest, grouped by related functionality.

Table 19-4. Core Properties of the Control Type

As you would guess, the Control class also defines a number of events that allow you to intercept mouse, keyboard, painting, and drag-and-drop activities (among other things). Table 19-5 lists some (but not all) events of interest, grouped by related functionality.

Table 19-5. Events of the Control Type

Finally, the Control base class also defines a number of methods that allow you to interact with any Control-derived type. As you examine the methods of the Control type, you will notice that

a good number of them have an On prefix followed by the name of a specific event (OnMouseMove, OnKeyUp, OnPaint, etc.). Each of these On-prefixed virtual methods is the default event handler for its respective event. If you override any of these virtual members, you gain the ability to perform any necessary preor postprocessing of the event before (or after) invoking your parent’s default implementation: