Using the SDK documentation for a given type will likely be a daily or even hourly event when you first start writing managed code. So a practical exposure to the format can be helpful.
The first time that you use a new type you should look up the type in the reference documentation. Enter the name of the type (for example, System.Windows.Forms.Form or just Form) into the index tab of the documentation and select the topic for that type. The starting topic for a type can be very helpful and you should read it entirely. Then as you use the different member variables and member methods you can read their topics as needed. Here is an example of a topic from the FCL reference documentation.
Figure 4‑3 Sample SDK Reference Topic
Starting at the top of Figure 4‑3 and reading to the bottom, here are some noteworthy parts of the reference docs for a type.
· The top indicates the name of the type and the type of the type. In this example the name is Form and the type is a class (as opposed to a structure or interface, etc.).
· Following this is an abbreviated hierarchy indicating the derivation heritage from System.Object on up to the topic type and sometimes beyond if the type is a base class for other classes in the FCL.
· The Remarks section in any topic is likely to include a detailed description of the purpose of a type, as well as how to use it and links to companion types in the FCL. In the case of Figure 4‑3 the Remarks section included so much information that I had to excerpt it out of the figure so that it would fit on a single page in this tutorial.
· Many type topics in the FCL reference documentation include Example sections complete with source-code and a brief description. This can be one of the most helpful parts of the documentation! If you are having trouble conceptualizing the use of a particular type, just cut and paste the sample code into a quick C# project and try it out directly. Again, the source code for the Form topic was lengthy enough that I excerpted out the bulk of the source-code so that Figure 4‑3 would fit on a single page.
· The Requirements section of the topic is often one of the most important and commonly referenced parts of the reference documentation. One reason for this is that it includes the namespace of the type. In this example the Form type is in the System.Windows.Forms namespace. The namespace listed at the bottom of the help topic tells you what using statement you should add near the top of your source-code module. If you are using the Form type you would commonly include this line of code in your .cs file.
using System.Windows.Forms;
· Another key piece of information in the Requirements section of a type’s help topic is the assembly in which the type exists. All managed types must exist in a file (or group of files) known as an assembly. (In fact even a simple C# executable is technically a managed assembly). The FCL is published as a collection of dozens of assemblies. When one assembly references a type in another assembly, the compiler needs to know about the referenced assembly. This means that if your code references a type in the FCL, then you need to make sure that your project references that type’s assembly.
o If you are using the command line compiler, the /r compiler switch is used to indicate an assembly reference.
o If you are using the Visual Studio .NET environment to build your projects you can add a referenced assembly to a project using the add reference menu item.
· At least two important pieces of information are included in the See Also section of a FCL type reference topic. These are the links to the topics for the types members and the types namespace. The type members topic describes in brief all of the member methods, constructors, properties and member fields of a type. These topics detail what a type can do. The namespace topic for a type is a great way to find related types in the FCL. If you know that you know one class that you need, you can link to its namespace topic and find other classes that are likely to be helpful for your task.
It may seem strange, at first, to approach the reference documentation with the rigor expressed in the preceding bullets, but if you do you will master the Framework Class Library in no time.
Exercise 4‑1 Compile and Test Sample Code
1. As you have seen in this section many SDK topics include a fair amount of sample code. You should be comfortable cutting and pasting this code into your own projects to become familiar with various types.
2. Using the SDK documentation, search for the starting topic for the System.Windows.Forms.Form class. Read this help topic top to bottom.
3. Now create a new .cs file and cut and paste the sample source code from the SDK topic into your new source code file.
1. Hint: You will need to create a class with a static Main() method for an entry point. Your main method can be comprised of the sample code, or it can call the function in the sample code.
4. Build the new file, either with the command line compiler or the Visual Studio .NET IDE.
Exercise 4‑2 Create Base64toFile.cs
1. The source code in Figure 4‑2 implements a command line utility that converts a file to its base-64 representation. In this exercise you will modify these sources to create a utility that converts base-64 data back to its original form.
2. Here are some tips.
1. The CryptoStream will be the fromStream rather than the toStream in the new application.
2. You will use the Read element of the CryptoStreamMode enumeration rather than the Write element when newing up an instance of the CryptoStream.
3. You will use the FromBase64Transform helper type rather than the ToBase64Transform type.
3. Compile and test the new application.
No comments:
Post a Comment