C# can produce two basic assembly types:

The important concept to know is that you can easily write your own class libraries. I show you how in the later section "Putting Your Classes into Class Libraries."

Assemblies, which are the compiled versions of individual projects, contain the project's code in a special format, along with a bunch of metadata, or detailed information about the classes in the assembly.

I introduce assemblies in this section because they round out your understanding of the C# build process — and they come into play in my discussion of namespaces and access keywords such as protected and internal. (I cover namespaces and these two access keywords later in this chapter.) Assemblies also play a big part in understanding class libraries. It's all covered in the later section "Putting Your Classes into Class Libraries."

One major consequence of compiling from .NET to IL, regardless of language, is that a program can use assemblies written in different languages. For example, a C# program can call methods in an assembly originally written in Visual Basic or C++ or the C# program can subclass a VB class.

You can take a look at some IL by running the Ildasm.exe tool in the .NET Software Development Kit (SDK) or the Reflector tool that I point you to at csharp102.info. Select a .EXE or .DLL assembly file to view its code as IL. A Visual Studio solution can contain any number of projects.

You can run executable assemblies in a variety of ways:

Think of a solution containing two .EXE assemblies as two separate programs that happen to use the same library assemblies. For example, you might have in a solution a console executable and a Windows Forms executable plus some libraries. If you make the console app the start-up project and compile the code, you produce a console app. If you make the Windows Forms app the start-up — well, you get the idea.

A class library contains one or more classes, usually ones that work together in some way. Often, the classes in a library are in their own namespaces. (I explain namespaces later in this chapter.) You may build a library of math routines, a library of string-handling routines, and a library of input/output routines, for example.

Sometimes, you even build a whole solution that is nothing but a class library, rather than a program that can be executed on its own. (Typically, while developing this type of library, you also build an accompanying .EXE project, or driver, with which to test your library during development. But when you release the library for programmers to use, you release just the .DLL [not the .EXE] — and documentation for it that's generated by the XML comments are described in Book IV, which is all about Visual Studio.)

The next section shows you how to write your own class libraries (and drivers).

You can create the files for a new class library project and its driver in either of two ways:

If your whole purpose is to develop a stand-alone class library that can be used in various other programs, you can create a solution that contains a class library project from scratch — here's how simple it is:

If you have an existing solution — whether it's an ongoing application or a class library project such as the one described in the previous section — you can easily add a second project to your solution: either a class library project or an executable project, such as a driver. Follow these steps:

Figure 10-2. Organizing two projects in an all-in-one-folder.

If the project you're adding is intended to stand on its own and be usable in other programs, use the side-by-side approach.

The ClassLibrary example in this section (like most examples in this book) takes the all-in-one-folder approach. The point is that although the folders don't have to be in the same place, putting them there can be convenient.

The task of selecting the location is independent of adding the new project directly to the ClassLibrary solution. The two project folders can be in the same solution while still being located in different places.

Figure 10-3. Organizing two projects side by side.

After you have a class library project, create the classes that make up the library. The following ClassLibrary example shows a simple class library — I show you some driver code for it after the example:

// ClassLibrary -- in a Class Library project
// File: Program.cs in ClassLibraryDriver project
// ClassLibrary -- A simple class library and its driver program
using System;
namespace ClassLibrary
{
  public class MyLibrary
  {
    public void LibraryFunction1()
    {
      Console.WriteLine("This is LibraryFunction1()");
    }
    public static int LibraryFunction2(int input)
    {
      Console.WriteLine("This is LibraryFunction2(), returning {0}", input);
      return input;  // Just parrot the input.
    }
  }
}

Libraries can contain any C# type: class, structure, delegate, interface, and enumeration. I cover structures (structs) in Book I, delegates in Chapter 9 of this minibook, interfaces in Chapter 8 of this minibook, and enumerations (enums) in the article "Enumerating the Charms of the Enum" on csharp102.info.

By itself, the class library doesn't do anything, so you need a driver program, a small executable program that "drives" the library to test it during development by calling its methods.

In other words, write a program that uses classes and methods from the library. You see this behavior in the NamespaceUse program example later in this chapter (and other programs in this book) — for example, when you call the WriteLine() method of class Console from the .NET Framework class libraries. (Console is in the System namespace, in the library file mscorlib.dll.)

The following chunk of code continues the previous code listing. This one adds a new project with one class that contains a Main() method, and you can write code to exercise your library inside Main():

// ClassLibrary driver program

// In a separate Console Application project:

// File: Program.cs in ClassLibraryDriver project
using System;
using ClassLibrary;
namespace ClassLibraryExample
{
  class Program
  {
    static void Main(string[] args)
    {
      // Create a library object and use its methods.
      MyLibrary ml = new MyLibrary();
      ml.LibraryFunction1();
      // Call its static methods through the class.
      int result = MyLibrary.LibraryFunction2(27);
      Console.WriteLine(result.ToString());
      // Wait for user to acknowledge the results.
      Console.WriteLine("Press Enter to terminate...");
      Console.Read();
    }
  }
}

To run and test the library through the driver, add a reference to the library in the driver project references, mark the driver project as the start-up project (as described earlier, in the "Executables" section), and run the program the same as you run all console applications in this book.

Here's the output from the test driver:

This is LibraryMethod1()
This is LibraryMethod2(), returning 27
27
Press Enter to terminate...

From any program you ever write, just include using directives for your class library's namespaces and add a reference to the .DLL file that contains the library (providing a path to wherever it lives). Then use the classes in the library in your program. This strategy is exactly how other programs in this book use classes from the .NET Framework libraries. Note that the compiler copies the libraries into your project's build directories.

Suppose that a program has these two projects:

You can see this setup in the InternalLimitsAccess example on the Web.

In real life, the U.S. Congress has the annoying habit of expecting the Central Intelligence Agency (CIA) to reveal its secrets — just to members of Congress and senators, of course. ("We won't leak your secrets — honest.") Meanwhile, those overly secretive spooks at the CIA have secrets they would prefer to hang on to. (Maybe they know the secret formula for Coca-Cola or Colonel Sanders's secret herbs and spices or a more sinister entity.) Exactly what Secret X is doesn't matter here, but the CIA wants to keep Secret X, well, secret.

There's a problem, though. Everybody at the CIA needs to know Secret X. In the InternalLimitsAccess example, the CIA is divided into several classes — class GroupA and class GroupB, for example. Think of them as sections of the CIA that (sometimes) communicate and share with each other. Suppose that GroupA is the holder of Secret X, so the group marked it private. The code looks something like this:

// In assembly InternalLimitsAccess:
class Congress
{
  static void Main(...)
  {
    // Code to oversee CIA
  }
}

// In assembly CIAAssembly:
public class GroupA
{
  private string _secretFormulaForCocaCola; // Secret X
}
public class GroupB
{
  public void DoSomethingWithSecretX()
  {
    // Do something with Secret X, if only you could access it.
  }
}

Now GroupB can't see Secret X, but suppose that it has a legitimate need to know it. GroupA can, of course, bump Secret X to public status, but if it does, the secret isn't much of a secret any more. If GroupB can see the secret, so can those snoops over in Congress. Even worse, CNN knows it too, not to mention Fox, ABC, and other networks. And you know how well those folks keep secrets. Oh, right — Russia can see Secret X too.

// In assembly CIAAssembly:
internal class GroupA
{
  private string _secretFormulaForCocaCola; // Secret X
  internal string SecretX { get { return _secretFormulaForCocaCola; } }
}
public class GroupB
{
  public void DoSomethingWithSecretX()
  {
    // Do something with Secret X, now that we can see it:
    Console.WriteLine("I know Secret X, which is {0} characters long, but " +
    "I'm not telling.", GroupA.SecretX.Length);
  }
}

Now class GroupB has the access it needs — and it isn't giving up the secret (even under threat of waterboarding). All it tells Congress, over in Main(), is that it knows secret X and secret X has 11 characters. Here's that chunk of code:

class Congress
{
  static void Main(string[] args)
  {
    // Code to oversee CIA
    // The following line doesn't compile because GroupA isn't accessible
    // outside CIAAssembly. Congress can't get at GroupA over at CIA.
     // CIAAssembly.GroupA groupA = new CIAAssembly.GroupA();

    // Class Congress can access GroupB because it's declared public.
    // GroupB is willing to admit to knowing the secret, but it's
    // not telling -- except for a small hint.
    GroupB groupB = new GroupB();
    groupB.DoSomethingWithSecretX();

    // Wait for user to acknowledge results.
    Console.WriteLine("Press Enter to terminate...");
    Console.Read();
  }
}

From Main(), GroupA is now invisible, so an attempt to construct an instance of it doesn't compile. But because GroupB is public, Main() can access it and call its public method DoSomethingWithSecretX().

Wait! CIA does have to talk to Congress about certain topics, I'm happy to report — but on a need-to-know basis, limited to selected members of Congress and senators, of course. They can do so already, via GroupB, as long as they present the proper credentials, although you need to add them to the code:

public string DoSomethingWithSecretXUsingCredentials(string credentials)
{
   if (credentials == "congressman with approved access")
   {
     return GroupA.SecretX;
   }
   return string.Empty;
}

CIA can still keep its deepest, darkest secrets ultra-hush-hush by declaring them private inside their owning class. That strategy makes them accessible only in that class.

The main purpose of private is to hide information. In particular, private hides a class's internal implementation details. (Classes who know classes too intimately aren't the luckiest classes in the world. In fact, they're the unluckiest.) Classes with a lot of implementation details are said to be "too tightly coupled" with the classes they know too much about. If class A is aware of the internal workings of class B, A can come to rely too much on those details. If they ever change, you end up having to modify both classes.

The less the other classes — and assemblies — know about how class B performs its magic, the better. In Chapter 5 of this minibook, I use the example of a BankAccount class. The bank doesn't want forgetful folks like me — or forgetful classes such as class A — to be able to change a balance directly. That balance is properly part of the BankAccount class's implementation. It's private. BankAccount provides access to the balance — but only through a carefully controlled public interface. In the BankAccount class, the public interface consists of three public methods:

Access control considerations other than private and public arise in programming. I explain in the previous section how the internal keyword opens a class — but only to other classes in its own assembly.

However, suppose that the BankAccount class has a subclass, Savings Account. Methods in SavingsAccount need access to that balance defined in the base class, of course, although other classes, even in the same assembly, probably don't. Luckily, SavingsAccount can use the same public interface, the same access, as outsiders: using Balance, Deposit(), and Withdraw().

Sometimes, though, the base class doesn't supply such access methods for its subclasses (and others) to use. What if the _balance data member in BankAccount is private and the class doesn't provide the Balance property?

If the balance does indeed need to be accessible (read-only) to outsiders, you should, of course, provide the public Balance property to get the balance (read-only). However, you may still need to set the balance from inside SavingsAccount itself. To do that, you can give the set accessor of Balance protected access — accessible from SavingsAccount and other subclasses but inaccessible to outsiders. The discussion of properties in Chapter 5 of this minibook shows how to do it, and here's what the code looks like:

// In BankAccount:
public decimal Balance
{
  get { return _balance; }             // Public
  protected set { _balance = value; }  // Not public
}

The ProtectedLimitsAccess example on the Web illustrates using the protected keyword as just described.

The example has two subclasses of BankAccount: one in the same assembly as BankAccount and one in a different assembly. What's interesting with respect to protected is that either BankAccount subclass can access any item in BankAccount marked protected. The subclass doesn't have to be in the same assembly as its base class.

Making items in the BankAccount base class protected internal, rather than just protected, simply adds a new dimension to the accessibility of those items in your program. Using protected alone allows a subclass (in any assembly in the program) to access protected items in the base class. Adding internal extends the items' accessibility to any class, as long as it's in the same assembly as BankAccount or at least a subclass in some other assembly.

In the ProtectedInternalLimitsAccess example on csharp102.info, you can see this effect. The class AnotherClass that's defined within BankAccount's own assembly can access the protected internal set accessor in the Balance property. However, the nearly identical AnotherClass in a different assembly cannot access Balance's set accessor to set the balance.

If a class or other type needs to be private, protected, or protected internal, nest it, if you can, inside the class that needs access to it.

You declare a namespace using the keyword namespace followed by a name and an open and closed curly-braces block. The classes (and other types) within that block are part of the namespace:

namespace MyStuff
{
  class MyClass {}
  class UrClass {}
}

In this example, both MyClass and UrClass are part of the MyStuff namespace.

Besides classes, namespaces can contain other types, including these:

A namespace can also contain nested namespaces, to any depth of nesting. You may have Namespace2 nested inside Namespace1, as in this example:

namespace Namespace1
{
  // Classes in Namespace1 here ...
  // Then the nested namespace:
  namespace Namespace2
  {
    // Classes in Namespace2
    public class Class2
    {
      public void AMethod() { }
    }
  }
}

To call a method in Class2, inside Namespace2, from somewhere outside Namespace1, you specify this line:

Namespace1.Namespace2.Class2.AMethod();

Imagine these namespaces strung together with dots as a sort of logical path to the desired item.

(You can change any of those names, though. Just do it carefully and thoroughly. You can change the overall namespace name for a project in the project's Properties window. Rather than try to rename everything, I sometimes create a new program using the correct names and then import the class files from the original program — after which I scrap the original.)

However, namespaces affect visibility more than accessibility. By default, classes and methods in NamespaceA are invisible to classes in NamespaceB, regardless of their access-control specifiers. But you can make one namespace's classes and methods visible to another namespace in a couple of ways. The bottom line is that you can access only what's visible to you and "public enough."

I define "public enough" as having a strong enough access specifier from the viewpoint of Class1, the caller. This issue involves access control, extended earlier in this chapter and covered in the discussion of access specifiers in Chapter 5 of this minibook.

Making classes and methods in another namespace visible

C# provides two ways to make items in NamespaceB visible in NamespaceA:

• Fully qualify names from NamespaceB wherever you use them in NamespaceA. This method results in code such as the following line, which starts with the namespace name and then adds the class and lists the method:

  System.Console.WriteLine("my string");

• Eliminate the need for fully qualified names in NamespaceA by giving the namespace files a using directive for NamespaceB:

  using System;
  using NamespaceB;

Programs throughout this book make items in NamespaceB visible in NamespaceA with the using directive. I discuss full qualification and using directives in the next two sections.

Note

If the items in NamespaceB are in other assemblies, choose Project

The namespace of a class is a part of the extended class name, which leads to the first way to make classes in one namespace visible in another. This example doesn't have any using directives to simplify referring to classes in other namespaces:

namespace MathRoutines  // Broken into two segments -- see below.
{
  class Sort
  {
    public void SomeMethod(){}
  }
}
namespace Paint
{
  public class PaintColor
  {
    public PaintColor(int nRed, int nGreen, int nBlue) {}
    public void Paint() {}
    public static void StaticPaint() {}
  }
}
namespace MathRoutines  // Another piece of this namespace
{
  public class Test
  {
    static public void Main(string[] args)
    {
      // Create an object of type Sort from the same namespace
      // we're in and invoke a method.
      Sort obj = new Sort();
      obj.SomeMethod();
      // Create an object in another namespace -- notice that the
      // namespace name must be included explicitly in every
      // class reference.
      Paint.PaintColor black = new Paint.PaintColor(0, 0, 0);
      black.Paint();
      Paint.PaintColor.StaticPaint();
    }
  }
}

In this case, the two classes Sort and Test are contained within the same namespace, MathRoutines, even though they appear in different declarations within the file (or in different files). That namespace is broken into two parts.

The method Test.Main() can reference the Sort class without specifying the namespace because the two classes are in the same namespace. However, Main() must specify the Paint namespace when referring to PaintColor, as in the call to Paint.PaintColor.StaticPaint(). This process is known as fully qualifying the name.

Notice that you don't need to take any special steps when referring to black.Paint(), because the class of the black object is specified, namespace and all, in the black declaration.