Introduction
If you haven’t used Microsoft Visual Studio before, then this tutorial is for you. It will walk you through the major features of Visual Studio 2010 and get you started with creating various types of Synergy .NET applications. You will also learn useful tips and techniques that can save you valuable time while programming within Visual Studio.Tutorial Setup
No specific preparation is needed in order to complete this tutorial.Tutorial Steps
Starting Visual Studio
Before we can get started, if it’s not already running, we need to start Microsoft Visual Studio 2010.□
From the Windows Start Menu, select All Programs > Microsoft Visual Studio 2010 > Microsoft Visual Studio 2010. Once Visual Studio has finished loading, you should be looking at a screen called the Start Page. This screen allows you to easily create a new development project, or open an existing one, and open recently used projects. On the right side of the Start Page Visual Studio presents all kinds of information, the content of which is also customized to the type of environment that you select (we’ll talk about this more in a moment). This information can include news and announcements, technical information, and lots of other types of content. The Start Page is often overlooked by developers, but when you are learning Visual Studio and .NET development it can be a valuable source of information. The Start Page closes when you create or open a development project, but you can return to it at any time by selecting View > Start Page from the menu. Many things in Visual Studio are customizable, so to help to ensure that you are able to complete this tutorial, we’re going to reset all Visual Studio settings to default values. In fact, there are multiple sets of default values, as you will see shortly. There are default settings based on the some of the available programming languages, defaults for types of development (e.g., web development) and various other scenarios. The first time you start Visual Studio after installing it, you will be asked to select which default configuration you wish to use. Many people select General Development Settings for an initial configuration well suited to multiple languages and various types of development projects. It is also possible to switch Visual Studio to a different collection of settings at any time, and also to save and restore custom settings.Reset to Default Settings
□
From the menu, select Tools > Import and Export Settings.□
Select the Reset All Settings radio button, and then click the Next button.□
On the “Save Current Settings” page, check that Yes, save my current settings is selected (to save a backup so that you may restore your current settings after completing this tutorial, if required) and then click the Next button.□
On the “Choose a Default Collection of Settings” page, Select General Development Settings□
Click the Finish button□
When you see the “Reset Complete” screen, click the Close button. Selecting one of these pre‐defined collections of default settings can make many changes to your environment. Things that are commonly changed include menu items, menu item shortcuts, toolbars, and more.Creating a New Project
One of the first things you’re likely to want to do is create a new development project, so let’s do that now. As with many things in Visual Studio, there are often several ways to do something. For example, to create a new development project you can: On the Start Page, click the New Project… link. Select File > New > Project… from the menu. Click the New Project button on the toolbar. Type Ctrl+Shift+N.□
On the Start Page, click on the New Project… link. You will notice that the New Project dialog is divided into several main parts. On the left is a tree view where you can select from various project categories and sub‐categories, many of them based on the programming language that you wish to use. When you select a category, the center part of the dialog displays a list of project templates that belong to the category that you have selected. When you select a project template, a brief description of the project created by the template is displayed at the right of the dialog. Finally the lower portion of the dialog allows you to pick the location where you would like the project to be created, and specify a name for your new project. The project name that you pick is used in many ways, depending on the type of project you are creating. Generally the project name will be used to determine things like: The name of the “Solution” that is created (more about this in a moment). The name of the project that is created. The name of the folder that the project will be created in. The name of the main “assembly” (program or library) that will be created by the project. The name of the “default namespace” that will be used when some types of item are added to the project. Of course, even after a project has been created, all or any of these things can be changed, but some are harder to change than others. It’s best to put some thought into the name of your project before you create it.
□
In the templates tree (left) expand the Synergy/DE category, and then select Windows.□
In the project templates list (center) select Windows Forms Application.□
In the Name field, enter IntroToVisualStudio.□
Decide on a folder to create your project in, and enter its name in the Location field.□
Ensure that the Create directory for solution checkbox IS checked . In Visual Studio, one or more projects may exist within a Solution. Every project will have some type of output, usually an assembly, either a program (.exe) or library (.dll). Projects make up the various parts of an application. A Solution is merely a collection of projects, providing a way for developers to move around the various parts of their application easily. Every project must exist within a solution, and a solution can contain multiple projects. When you create a new project in Visual Studio by one of the mechanisms that we discussed earlier, Visual Studio will also create a Solution. If the “Create directory for solution” box is not checked, then the solution file is named the same as the project being created, and is created in the same folder as the project. This is generally appropriate if you only plan on working with one project in the solution. If the “Create directory for solution” box is checked, then Visual Studio will create a folder for the solution (below the location that you specify) and save the solution file in that folder. Then a second folder, for the project, will be created below the solution folder, and all of the project files will be created in or below the project folder. This is appropriate when you intend to add several projects to a solution, as each project will be stored in its own folder below the main solution folder. You’ll also notice that in this case you are able to specify a different name for the solution itself.□
Click on the OK button to create your new solution and project. Because of the virtual machine, creating and opening the solution and project may take a few seconds. Different project templates cause different things to happen when a new project is created. For a Windows Forms project, what generally happens is the solution and project, and various default project files are displayed in the Solution Explorer towards the top right of the screen, the visual design surface for the default form that was added to the project is displayed filling most of the screen, and the Properties window is displayed towards the bottom right of the screen.Solution Explorer
The Solution Explorer window is a key part of Visual Studio, and is frequently used by developers. It allows you to navigate around the various files and other items that make up your projects and your solution. Generally, double‐clicking on a file will open that file, either in a text editor or perhaps some kind of visual design surface. Some files can be edited in various ways. For example, you will notice that when the project was created, the file Form1.dbl was automatically created, added to the project, and opened in design view. But there is another way of working with Form1.dbl, in a source code editor. To see this in action:□
In Solution Explorer, right‐click Form1.dbl and select View Code. When working with pieces of a UI it is common to work with these two views of a given source file, the design view and the code view.□
Right‐click Form1.dbl again and this time select View Designer. You may have noticed that once a file (or a view of a file) is opened, it remains open until you specifically close it. Each file is assigned a tab towards the top of the main work area, which looks like this: You can use these tabs to switch between the views of a file, or between multiple files that you have opened. You’ll also notice an X to the right of each tab, which can be used to close that file or view. You may sometimes see red dots next the file name on a tab. This is an indication that the file has been modified and needs to be saved. Visual Studio will automatically save files when you build or run, and there are also various ways to manually save one or more files. The easiest way to manually save files is to use the Ctrl+S shortcut to save the current file, or the Ctrl+Shift+S shortcut to save all changed files. It is easy to change the layout of the UI in Visual Studio, where most things can be repositioned, docked, stacked in tab sets, and hidden away at will. If at any time you can’t find Solution Explorer you can always make it visible by selecting View > Solution Explorer from the menu, or by using the keyboard shortcut Ctrl+Alt+L.Visual Design Surfaces
Many things that you work with in Visual Studio have visual design surfaces. Certainly it is common to work with a visual design surface when building a user interface, but several other things have them also. As the name suggests, a visual design surface allows you to design something visually, often by dragging items from a palette of available “things” and arranging them on the design surface. Right now we are creating a Windows Forms application, so we have access to a wide variety of components that can be used to build a Windows user interface. These components include things like the TextBox, CheckBox and Button controls that you’re probably familiar with. These controls are located in the Toolbox (more in a moment) and can be dragged to the visual design surface as needed. By the way, the same concept also applies when working with other types of application. As well as with traditional Windows Forms applications, developers commonly work with visual design surfaces and toolboxes when developing Windows Presentation Foundation (WPF) applications, ASP.NET Web applications, Silverlight applications, and others.The Toolbox
The Toolbox may not be visible right now, but if not look down the left hand side of the Visual Studio window and you may see a vertical tab that says Toolbox.□
If you don’t see the Toolbox Window then select View > Toolbox from the menu (or type Ctrl+Alt+X).□
With the Toolbox visible, click on the small icon at the top right of the Toolbox window to “pin” the window in place. Pinning a window provides a mechanism to ensure that it remains on the screen. Most windows, when unpinned, slide out of sight but leave behind a tab so that you can access the window again. Hovering the mouse over the one of these tabs will make the window appear so that you can access it, or pin it in place.□
Make sure that the design view of Form1.dbl is visible.□
In the Toolbox, go to the Common Controls group, then click once on and drag a Button control to the design surface.You will notice that when the button is created on the form, several white “handles” appear around the outside of the button. These handles perform two functions; they indicate which item is currently selected to be worked with, and they can be used to resize the selected item.
□
Single‐click the body of the form (not on the button) and you will see that the handles move to the form, which is now selected to be worked on.□
Single‐click on the button again, the handles move back to the button. As you click between these two items, look to the lower right portion of the screen. You should see a window called Properties, and you should see the content of the window change as you select different items on a visual design surface.□
If you can’t see the properties window, select View > Properties Window from the menu, or use the F4 keyboard shortcut.□
If necessary, pin the properties window in place.Properties Window
The properties window is another key part of Visual Studio where, if you’re developing a user interface at least, you are likely to spend a lot of time. Essentially each item that you work with (buttons, textboxes, checkboxes, etc.) have properties, sometimes hundreds of them, and the properties window allows you to inspect and change the values of these properties, in order to achieve the desired functionality within your application. Notice the mini toolbar at the top of the properties window; in fact many of Visual Studio’s windows have a similar toolbar, which generally allows you to view the information in the window in various ways. For example, the properties window is currently grouping the various properties of the selected button control by type (Accessibility, Appearance, etc.) because the first button ( ) on the toolbar is selected.□
Click on the second icon ( ) to order the properties alphabetically. Notice that the properties window also has a drop‐down list (at the top) which shows you which item is currently selected. Another way of changing the selected item is to drop down this list and select a different item.□
Drop‐down the list at the top of the properties window and select Form1.Notice how the selected item handles moved from the button to the form, and how the content of the properties window changed to reflect the properties of the newly selected item.
□
On Form1’s design view, select the form.□
In the properties window, Locate the Text property and set the value to My Form. A Windows Form’s text property is used to set the title of the window; notice how the text that you typed is now also displayed in the title area of the form designer. Some changes that you make in the properties window are reflected visually in the designer. In some cases, the opposite is also true. For example:□
With the form selected, locate the Size property. It may be easier to switch to alphabetic mode (toolbar at top of properties window).□
Notice the current value of the size property; probably the default 300, 300□
Now use the designer’s current item handles to visually resize the form.□
Check the Size property again, it should have changed. So, making changes in the properties window often visually changes the designer window, and making changes in the designer window also changes the properties window. Another thing to notice with respect to the properties window is how properties that have not been changed (i.e., currently have a default value) are displayed in normal text, whereas properties that have had their value changed are displayed in bold text. This visual indication of what properties have been changed can be very useful. So, we’ve discovered that we can change the properties of something either graphically in a design view, or via the properties window, but where is all of that information stored? The answer to that depends on what type of project you are working on. Some common examples are: Project Type Designer / Properties Changes Written To Windows Forms A “designer” programming language source file. Web Forms (ASP.NET) The main web page file (.aspx) in HTML format. Windows Presentation Foundation The main form or control file (.xaml) in XAML format. Silverlight The main form or control file (.xaml) in XAML format. Other Various, generally a programming language source file.Designer Source Files
To help you to understand what is happening when you interact with a visual design surface or with the properties window, let’s dig a little deeper into our simple application.□
In Solution Explorer, expand the Form1.dbl item. You will notice that below Form1.dbl are two other files, called Form1.designer.dbl and Form1.resx. By the way, these particular files are specific to a Windows Form, but the general principle of what we’re looking at here applies in a number of different scenarios. For now, the file that we are most concerned with is the Form1.desidner.dbl file. This is a special source file that is altered whenever you make changes to a Windows Form’s visual design surface or Properties window. WARNING: As a general rule, you should not edit “.designer” files. They are created and maintained by Visual Studio visual designers and the Properties window. It is relatively easy to break your application by making inappropriate changes to these files, and it can be difficult to resolve problems like this. With the warning out of the way … let’s edit the file!□
In Solution Explorer, double‐click on Form1.designer.dbl to open it in code view (you could also right‐click the file and select either Open or View Code). Right now the designer source file is fairly simple, because all we have is a form and a button. Notice how the “class” Form1 “extends” (is a) System.Windows.Forms.Form, and how the class contains an instance variable called button1 which is of type System.Windows.Forms.Button. That variable was created, by the designer, when we dragged the button onto the form. Look down a little and you will see that there is a method called InitializeComponent, and in that method there are various assignment statements which set various properties of the button (this.button.something) and the form its self (this.something). These lines of code are inserted when we make changes to the properties of the form, or objects “on” the form, either via changes that we make on the graphical design surface, or changes that we make in the Properties window. You may also notice that the code in this file defines the class as “public partial class Form1”.□
Click on the tab at the top of the edit area called Form1.dbl. If you closed this view then in Solution Explorer, right‐click on Form1.dbl and select View Code. Notice that the class in this source file is also defined as “public partial class Form1”. A partial class is a class composed from partial class definitions in multiple source files, so in this case the class Form1 is made up of source code in the file Form1.dbl, which the developer controls, and code in the file Form1.designer.dbl, which the designer and properties window control. If you look at the default code in Form1.dbl you will notice that there is a “constructor” method (public method Form1) which containsa call to the InitializeComponent method which is in Form1.designer.dbl. So, when the application creates an instance of the Form1 class, the designer‐generated code is executed to create and configure all of the controls on the form.
Program.dbl
Projects which target an assembly which is an executable program (i.e., an .exe rather than a .dll) include another source file, called Program.dbl. This is the “main‐line” or the “entry point” to the application.□
In Solution Explorer, double‐click on the file Program.dbl to open it in the code editor. The default code in the Program.dbl file will vary, depending on the type of application, but tends to be very simple in nature. In the case of a Windows Forms application, as you can see, the file contains a main‐line program which essentially just launches a new instance of the default form, Form1. If you were to rename the class in Form1.dbl (and of course the matching partial class in Form1.designer.dbl) to a different name, or if you wanted to launch some other form at application startup, then you would need to edit the code in Program.dbl as appropriate.The Properties Folder
Each project that you create will include a folder called Properties, and depending on the type of project, the folder will contain one or more files.□
In Solution Explorer, expand the Properties folder to view the files that it contains. In the Windows Forms project that you’re currently working in, there will be various files in the Properties folder. These files are AssemblyInfo.dbl, Resources.resx and Settings.settings. Although you can edit some of these files directly, and some of these file types also have visual designers associated with them, the files in the Properties window are usually maintained via the Project Properties dialogs, as you will see shortly.AssemblyInfo.dbl
□
In Solution Explorer, double‐click AssemblyInfo.dbl to open it in a code editor. AssemblyInfo.dbl contains various attribute definitions used to embed information into the compiled assembly. You can specify information about your company, the name of the product, copyright information, etc. The file can also be maintained via a dialog window which can be accessed by opening the projectproperties, selecting the Application tab and clicking the Assembly Information… button.
Resources.resx
This file is a resource file which is a special type of file that can be used to embed various resources (strings, images, audio files, etc.) the application might need, directly into the application’s assembly. The benefit of using resource files is that any resources that the application needs do not need to be provided as individual files on disk, which in turn can significantly simplify application deployment. Resource files are actually XML files. The resources added to the file are serialized (if necessary) and stored within the XML file. That being said, you will probably never deal with a resource file as an XML file, because Visual Studio provides a graphical designer that lets you work with the contents of resource files. Resources in resource files are also very easy to use within the application, because the resource file designer dynamically generates a class which represents the contents of the resource file. Accessing a resource is as easy as referring to a static property in this class.□
In Solution Explorer, double‐click the Resources.resx file to open the resource file designer. By default the resource file designer opens in Strings mode, but you can switch to working with Images, Icons, Audio, Files or Other Items using the drop‐down field in the top‐left corner of the resource designer. You will also notice that there are buttons on the toolbar which allow you to add and remove items from the resource file. Let’s work through a simple example of adding a string resource to a project:□
In the Name column, where it defaults to String1, change the resource name to WelcomeMessage.□
In the Value column add the text Welcome to my application.□
In the Comment column add the text Displayed at application startup.□
Type Ctrl+S to save your changes. Now let’s take a look at what we actually did with the resource designer.□
In Solution Explorer, right‐click on Resources.resx and select View Code.The XML file that you are looking at is the actual resource file. If you scroll to the bottom of the file you will see the resource that you just added via the designer.
□
Close the XML view of the resource file.□
In Solution Explorer, expand the view of the file Resources.resx Like forms that we discussed earlier, resource files also have a designer source file, in this case Resources.designer.dbl□
Double‐click on Resources.designer.dbl to open it in the source code editor. As you interact with a resource file through the designer, Visual Studio generates the code in the designer source file. As you can see, the source file contains a sub‐namespace called Properties (the name of the folder) containing a class named Resources (the name of the resource file).□
Scroll down to the bottom of the source file. As you can see, the string resource that you added has been exposed as an internal static property. This means that we can refer to the value of the string resource from anywhere in the project (assembly) like this:Properties.Resources.WelcomeMessage
□
Close the source file by clicking on the close (cross) icon in its main tab. Let’s add some code to the application to make use of the resource string that we just added:□
In Solution Explorer, double‐click on the file Form1.dbl to open its visual designer.□
Double‐click somewhere in the body of the form to open the code editor window.□
Place your cursor in the procedure division of the Form1_Load method and add the following code:this.Text = Properties.Resources.WelcomeMessage
□
Type Ctrl + F5 to save your changes, and to build and run the application. You should see the text that you entered in the resource file now displayed in the application drag bar.□
Close the application.□
Close the Resources.resx file by clicking on the X icon in its main tab.Settings.settings
Conceptually the settings file is similar to a resource file. However, where a resource file is intended to store resources like images, sounds and strings that are used by an application, the settings file is intended to store application or user settings. A setting is a name / value pair, and you can specify the data type of the value.□
In Solution Explorer, double‐click on the Settings.settings file to open the settings file designer. Settings files also have a .designer.dbl file, and just like with resource files the settings designer dynamically generates a class called Settings, with public properties to represent the settings that you have defined in the designer. This means that you can programmatically access the settings with code like this:Properties.Settings.Default.AutoLogin
Default values for the settings that you define are stored in the .settings (XML) file.□
Close the Settings.settings designer by clicking on the X icon in its main tab.The References Folder
□
In Solution Explorer, expand the References folder. All Visual Studio development projects will include a special folder called References. The folder doesn’t contain files, but rather contains a list of assemblies that are accessible from the code within your application. If you want to access types that are stored in a particular assembly, you add a reference to the assembly. We’ll look at how to do that shortly. When you create a new project from a project template, the template will probably include a set of pre‐ configured references. Some of these references may be required because of existing code that has already been included in the project by the template, while others may have been included simply because you are likely to need them when developing a particular type of application.□
In Solution Explorer, right‐click on the References folder and select Add Reference…The Add Reference dialog allows you to browse assemblies that are available to be referenced by your project. There are five tabs at the top of the dialog, as follows: .NET Lists all .NET Framework components available for referencing, as well as assemblies from third parties that have been registered on your system. COM Lists all COM components available for referencing and use through .NET’s COM interop capabilities. Projects Lists Visual Studio projects in the current solution available for referencing. Select assemblies from this tab to create project‐to‐project references. Browse Allows you browse additional files to find a component not listed in the current tab and add it to the list. Recent Displays recently added references. As an example of adding a reference to a project, to make types (classes, etc.) that are available in a particular assembly available for use in the project, let’s assume we want to have the ability to expose a WCF service from our application. To do that you would need to use several classes that are provided by the .NET Framework in the System.ServiceModel namespace.
□
In the .NET tab, click the Component Name column title to sort the list of assemblies in alphabetical order, and then locate and select the System.ServiceModel assembly.□
Click the OK button to add the reference. You should now see System.ServiceModel listed under the References folder in your project, meaning that whatever types are defined in that assembly are now available for you to use in your code.Object Browser
Visual Studio’s Object Browser window allows you to browse and view the content of assemblies.□
In Solution Explorer, double‐click on the System.ServiceModel reference that you just added. You should see the Object Explorer window open, and the System.ServiceModel assembly should be selected in the list of assemblies to the left side of the screen. Similar to the .NET tab in the add reference dialog, this list shows assemblies that are provided by the .NET Framework as well as other assemblies that you may have referenced in your project. At the top of the dialog is a toolbar with a drop‐down list which allows you to apply filters to the list of assemblies that are displayed.□
In the Browse drop‐down list, select .NET Framework 4 to filter the list of assemblies to only those assemblies available in that version of the .NET Framework.□
Click the small triangle icon next to the System.ServiceModel assembly. Assemblies can contain types (classes, etc.) from one or more namespaces. When you drill into an assembly in Object Browser, the first thing you see is the namespaces that are present in the assembly: Above you can see that the System.ServiceModel assembly contains types from multiple namespaces. Note that the types in a namespace don’t have to be all defined in one assembly. For example, you can see that this namespace contains some types from the System namespace, but there will be types from the same namespace in other assemblies too.□
Click the triangle icon next to the System.ServiceModel namespace to drill into it. Drilling into a namespace displays the types that are present in that namespace. The nature of the type is indicated by the icon displayed next to it. For example, in the diagram above, ActionNotSupportedException is a class while AuditLevel is an enumeration.□
Single‐click on the class BasicHttpBinding to select it. In the upper‐right section of the Object Browser window you can see more detail about the type that you have selected, and again the icon next to each item indicates the nature of the item. In the case of the BasicHttpBinding class, you will see that the class has several methods, one of which is called CreateBindingElements(), and also several properties, including BypassProxyOnLocal.□
Single‐click on the CreateBindingElements method to select it.In the lower‐right portion of the Object Browser window you can see even more information about the thing that you have selected above. In this case the information is telling us about the method that we selected. We can see that it is a public method, so it’s available for us to call, it does not have any parameters (nothing is listed between the parentheses following the method name) and it returns a BindingElementCollection. There is also useful descriptive information about what the method does, any parameters it might accept, and the return value. You may also notice that other types that are mentioned here appear to be hyperlinks, and sure enough clicking on one of them will take you to the documentation for that type in Object Browser. There are also forward and back buttons on the toolbar to make navigating around easy, just like in a web browser. You can also use Object Browser to add references to your project. For example, let’s suppose that by browsing around in Object Browser we determined that we need a reference to the System.ServiceModel.Activation assembly.
□
In Object Browser select the System.ServiceModel.Activation assembly□
In Object Browser toolbar, click the Add to References in Selected Project in Solution Explorer button. Object Browser can be very useful. If you have an idea about what you need then it can allow you to easily browse detailed information about things, and, having confirmed what you need, you can add a reference to the required assembly. Object browser is also a great way to learn about the capabilities of things, because it makes it easy to view detailed information about methods, parameters, return values, enumerations, and lots of other things.□
Close Object Browser by clicking on the cross icon in its main tab.Project Properties
Each project that you create includes many options which allow you to define lots of different things. These options, more commonly referred to as project properties, all have default values and can be customized through the “Project Properties” dialogs.□
In Solution Explorer, right‐click on the IntroToVisualStudio project (it’ll be shown in bold text immediately below the solution) and from the context menu select Properties. The project properties dialog has various tabs down the left hand side.□
Check that the Application tab is selected. Let’s take a look through the various tab pages and explore what options are available to you. There are lots of options, so we’ll just pick out some of the more important ones. Application The tabs that are displayed will vary based on the type of application that you are working on. We’re currently working on a Windows Forms Application, so you should see tabs that look something like this: Most projects create one assembly, and that assembly can either be an executable program or a class library. The assembly name and output type fields determine the name of the assembly that is created by the project, with the output type being used to determine the file extension (.exe or .dll). The default namespace determines the namespace that is inserted into any new source files that are added to the project. When using most project templates, the assembly name and default namespace default to the name of the project that you create, and by the time a new project has been created, the default namespace will already have been used in whatever source files are added to the project by the project template. So, if you change the default namespace you will usually want to review any existing source files in the project and change the namespace used in those files.The assembly information file (AssemblyInfo.dbl) was discussed earlier. You’ll notice the Assembly Information… button that allows you to edit the content of the file through a simple user interface. One of the most important settings for an application is the Target framework, which determines the version of the .NET framework that the assembly will be built for. Synergy .NET projects will default to either the .NET Framework 4.0, or the .NET Framework 4.0 Client Profile. The client profile is a smaller version of the .NET Framework 4.0 which is commonly found on desktop PCs and laptops; it has some of the features of the full framework removed. These features include things like the ASP.NET web components which are typically only required on server systems. You can change the target framework to an earlier version if you wish, which could for example help with deployment because most systems will have V2.0 of the Framework already installed, but may not have 4.0. However by doing this you may be restricting the capabilities of your application, because some features of the current .NET Framework will not be available for you to use. A better approach is to target the latest version of the Framework, and set up your deployment packages or procedures to install the latest Framework if required. The Output type setting allows you to specify the type of assembly being created; either a Windows Application, Console Application or Class Library. Generally this setting will be set correctly by the project template that you use, and won’t need to be changed. You can also set an application icon on this tab page. Doing so will cause the icon file to be added to the project, and embedded as a resource in the target assembly. Selecting an application icon does not cause that icon to be displayed at the top left of any forms that you may add to a project. If you want to use the icon on forms then you must set each form’s Icon property also. Build Events
□
Switch to the Build Events tab The Build Events tab allows you to specify build configuration instructions. You can also specify the conditions under which any post‐build events are run. Note the following: Build events (specified in the Pre‐build event command line and Post‐build event command line fields) can include any command that is valid at a command prompt or in a .bat file. If you specify a .bat file, the name of the file should be preceded by "call" (without quotes) to ensure that all subsequent commands are executed. For example: call C:\MyFile.bat. The % character is reserved for MSBuild, so if you specify an environment variable, replace each % with the %25 escape sequence. For example, replace %MY_VAR% with %25MY_VAR%25. If your pre‐build or post‐build event does not complete successfully, you can terminate the build by having your event action exit with a code other than zero (which indicates a successful action). Compile
□
Switch to the Compile tab On the compile tab you can determine which Synergy.NET compiler (dblnet) options are used when the project is built. The Compiler command line box towards the top of the form displays a summary of the actual command line options that will be used, and the other fields on the form allow you to determine what those options should be. As you can see, there are some compiler options that are used by default. There are specific UI controls on the form to allow you to set or unset some of the more commonly used compiler options, and the Other options field allows you to specify any other compiler options that are not specifically supported by controls on the form. Environment Variables□
Switch to the Environment Variables tabThe environment variables tab allows you to specify environment variables that are to be set when the project is opened. These environment variables will be in place during development in Visual Studio, and also when you execute utilities or your application from the Visual Studio environment. It is possible to refer to the translation of one environment in the value of another, using the syntax $(ENVVAR). For example, if you had one environment variable called ROOT that translated to a folder path, and you wanted to set another variable called DAT that translated to a folder called DAT below the ROOT folder, you could express the value for the DAT environment variable as $(ROOT)DAT. This would of course assume that the value of the ROOT variable was terminated with a trailing backslash character. The environment within Visual Studio includes several pre‐defined macros that can be used when setting environment variables. For example the macro $(SolutionDir) translates to the folder specification of the current solution file, and $(ProjectDir) translates to the location of the current project file, which may or may not be the same as the solution folder. As you can see in the screen‐shot above, you can also refer to these macros when setting environment variables in your project. The table below shows a list of some of the available macros:
Macro Translates To Example
$(Configuration) The name of the current project configuration. Debug $(OutDir) Path to the output file directory relative to the project directory. This path should have a trailing slash. This resolves to the value for the Output Directory property. bin\Debug\ $(ProjectDir) The directory of the project (defined as drive + path); it c:\temp\MyTestApp\
includes the trailing backslash. $(ProjectExt) The file extension of the project. It includes the '.' before the file extension. .synproj $(ProjectFileName) The file name of the project (defined as base name + file extension). MyTestApp.synproj
$(ProjectName) The base name of the project. MyTestApp $(ProjectPath) The absolute path name of the project (defined as drive + path + base name + file extension). c:\temp\MyTestApp\MyTestApp.synproj $(RootNameSpace) The namespace, if any, containing the application. MyTestApp $(SolutionDir) The directory of the solution (defined as drive + path); it includes the trailing backslash. c:\temp\MyTestApp\ $(SolutionExt) The file extension of the project. It includes the '.' before the file extension. .sln $(SolutionFileName) The file name of the solution (defined as base name + file extension). MyTestApp.sln $(SolutionName) The base name of the solution. MyTestApp $(SolutionPath) The absolute path name of the solution (defined as drive + path + base name + file extension). c:\temp\MyTestApp\MyTestApp.sln $(TargetDir) The directory of the primary output file for the build (defined as drive + path); it c:\temp\MyTestApp\bin\Debug\
includes the trailing backslash. $(TargetExt) The file extension of the primary output file for the build. It includes the '.' before the file extension. .exe $(TargetFileName) The file name of the primary output file for the build (defined as base name + file extension). MyTestApp.exe $(TargetName) The base name of the primary output file for the build. MyTestApp $(TargetPath) The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension). c:\temp\MyTestApp\bin\Debug\MyTestApp.exe Bear in mind that the environment variables that you specify through the project properties dialogs are only present in your development environment. If you use this mechanism to specify values for environment variables that are required at application runtime (outside of Visual Studio) then you must provide those environment variables via some other mechanism. Signing
□
Switch to the Signing tabThe signing tab allows you to specify that the assembly created by the project should be digitally signed. To sign the assemblies, check the Sign the Assembly checkbox and then select the strong name key file that you wish to use to sign the assembly. Once you have enabled signing, there is an option in the Choose a strong name key file drop‐down list which allows you to create a new key file. This is done using the .NET Framework’s strong name utility (sn.exe). We’re not going to get into assembly signing here because it’s a large and complex subject area, but it is definitely something that you need to learn about before you release .NET applications to customers. Reference Paths
□
Switch to the Reference Paths tab The Reference Paths tab allows you to specify folders that will be searched when the project system needs to locate a referenced assembly. When the project system finds an assembly reference, it resolves the reference by looking in the following locations, in the following order: The project directory. The project directory files appear in Solution Explorer. Directories specified on this page (Reference Paths). Directories displaying files in the Add Reference dialog box. The project's obj directory. (Assemblies created by adding COM references to your project are added to the project's obj directory.)Build
□
Switch to the Build tab The build tab allows you to specify various settings related to how your assembly is built. Each project that you create includes several configurations and, when working in the project, you always have one of these configurations selected. By default there is a drop‐down list on the main toolbar which allows you to easily switch to a different configuration. Most projects have two initial configurations defined, called Debug and Release, and the default is usually the Debug configuration. At the top of the form you will see a drop‐down list which allows you to select the Configuration to modify. Changes that you make in the lower half of the form are applied to that configuration. You need to remember this because if you’re making a change to one configuration, then you may want to make corresponding changes to other configurations also. In fact, if this is the case, you can select All Configurations in the configuration dropdown list, and the changes that you make will then be applied to all configurations. The Platform field is not used in Synergy .NET projects and should be ignored. Platform target allows you to specify the processor to be targeted by the assembly. Select x86 to target 32‐bit platforms, select x64 to target 64‐bit platforms, or select Any CPU for the assembly to be platform agnostic. Output path allows you to determine where the assembly created by the project (or more specifically the project configuration) will be stored. As you can see the default location is in a bin\Debug (or bin\Release) folder below the project folder. The XML documentation file option allows you to enable the creation of an XML file which contains API documentation for the code in your project. The information in the file is derived both from the actual code in the project, as well as from any documentation comments that you may have included in the code. Once you have the XML documentation file there are several products on the market that can transform the information in the file into various types of documentation. The Debug/Optimize code option allows you to specify whether to use just‐in‐time (JIT) optimization, and specifies the level of debug and stack trace information that will be available, which affects<blank> Includes less debug information in the assembly than is included by the Debug setting, and only includes limited line number listings for trace‐backs, but includes more information than the Optimize setting. This is the default setting for Release configurations. Debug Full debugging information is included in the assembly. This is the default setting for Debug configurations. Optimize Includes the least amount of debugging information in the assembly, resulting in the best performance. Enables JIT optimization. This option is recommended for production code. The Generate serialization assembly option determines whether the compiler will use the XML Serializer Generator Tool (sgen.exe) to create XML serialization assemblies. Serialization assemblies can improve the startup performance of XmlSerializer if you have used that class to serialize types in your code. The option can be set to one of the following values: Auto (default) Serialization assemblies will be generated only if you have used XmlSerializer to encode types in your code to XML. Off Serialization assemblies will never be generated, regardless of whether your code uses XmlSerializer. On Serialization assemblies will always be generated. It should be noted that due to a Visual Studio issue, setting the Generate serialization assembly to On might not result in a serialization assembly, even if there are serializable types in the project. There is an article on Microsoft Connect (bug id 123088) which discusses this issue. You can locate the article via an internet search for "Project Does Not Generate Serialization Assembly Even When Specifically Told To Do So". The DLL base address specifies the preferred base address at which to load the assembly. This can be specified in decimal or hexadecimal format, and it must be 0x10000 aligned. The default base address for a DLL is set by the .NET Framework common language runtime. Setting a DLL base address is an advanced subject and is beyond the scope of this introductory tutorial.
Debug
□
Switch to the Debug tab The options on the Debug tab are used to set properties for the behavior of the project when the debugger is started. As with the build options, it is possible to specify different debugger settings based on the currently selected configuration, and again the Platform field is not used with Synergy .NET projects and should be ignored. The options under Start Action are used to set the item to be started when the debugging begins, and can be set to one of the following: Start project (default) Specifies that the executable for the project should be started when the application is debugged. Start external program Specifies that some other executable is launched when the application is debugged. Specify the full path to the executable to be started in the field to the right, which is enabled when this option is selected. Start browser with URL Specifies that a URL should be accessed when the application is debugged. Specify the URL in the field to the right, which becomes enabled when this option is selected. If you select this option without entering anything in the text field, the debugger will work as if "Start project" were selected. The Command line arguments field allows you to specify any command line arguments that should be passed to the program when starting an executable. The option is not applicable if starting a URL. The Working directory option allows you to specify the directory from which the project will be launched for debugging. This applies only when Start project is selected. The default is the output path folder specified in the build tab’s Debug configuration.The Use remote machine, Enable unmanaged code debugging,“Enable SQL Server debugging and Enable the Visual Studio hosting process options are not implemented in Synergy .NET projects and should be ignored. Settings
□
Switch to the Settings tab You’ve already seen the settings tab earlier, when we were introducing the Settings.settings file. When you clicked on the file you were presented with the visual designer for the project settings file, and that same designer is available via the project properties dialogs also. Resources□
Switch to the Resources tab And you’ve seen the resources tab before also, when we discussed the projects Resources.resx file earlier. Again, the designer for the file is also available via the project properties dialogs.□
Close the project properties dialog by clicking the close (cross) icon in the main tab bar. If you’ve made any changes then you may be prompted to save your changes.Building the Project
Visual Studio 2010 utilizes an external build system called msbuild to perform build operations. Almost all projects have the concept of a build which is the process of generating whatever the output of the project is, generally a .NET assembly, from whatever the input for the build is, generally source code. You don’t need to do anything special to define what happens during a build other than configuring the content of the project, which in most cases involves adding source files and source code to the project. However there are other types of project that Visual Studio supports. For example, there are project templates to allow you to create Windows Installer installation packages (msi files), as well as various other things. But most projects have a build option, and that’s how you cause the project output to be generated (assuming that you have no errors of course!). Based on the project template, Visual Studio knows HOW to build the target output. In the case of a Synergy .NET project, it knows to build a dblnet command line using the various options specified in the project properties dialogs and using a list of all the source files and assembly references defined in the project. Then it executes this command and displays the resulting output.The Output Window
Generally the output from a build is displayed in one or two places depending on whether the build was successful. First, the actual textual output is displayed in the Output window, and then, if there were any errors, those errors are generally parsed and displayed in a more structured way in the Errors window. Follow these steps to ensure that the output and errors windows are visible.□
From the menu, select View > Output (or type Ctrl+Alt+O)□
If the error window is not pinned in place, then pin it in place by clicking the small push‐pin icon at the top‐right corner of the window.□
From the menu, select View > Error List (or type Ctrl+\ and then E) Now to build the project:□
From the menu, select Build > Build Solution (or type Ctrl+Shift+B) You should see the output window become focused, and output similar to this: ‐‐‐‐‐‐ Build started: Project: IntroToVisualStudio, Configuration: Debug Any CPU ‐‐‐‐‐‐ ========== Build: 1 succeeded or up‐to‐date, 0 failed, 0 skipped ========== This output indicates that the project was built successfully.Error List Window
To demonstrate what happens when there is an error:□
In Solution Explorer, double‐click on Form1.dbl to display the forms graphical designer.□
Double‐click inside the body of the form to open the code editor window and position your cursor in the Form1_Load method.□
Somewhere in the procedure division of the method, add some invalid code – anything. Adding the words junk code would work quite nicely!□
Type Ctrl + Shift + B to build the project. It is not necessary to manually save your changes, because Visual Studio will automatically do that each time you do a build, or execute, or debug. Again you should initially see the compiler output in the output window, but when the compiler completes with an error, the error list window should be displayed, and should contain the details of the errors that were reported by the compiler. You’re probably looking at something like this: The window displays the errors, warnings, informational messages emitted by the compiler, as well as information about the file in which the error occurred, the line number, and the name of the project. If you only want to look at a certain type of message (errors vs. warnings for example) then you can filter the content of the list by clicking on the various buttons in the small toolbar above the error list. The list is also active; in that you can double‐click on messages in the list to take you to the point of the problem. To demonstrate this:□
Close the Form1.dbl source file by clicking on the close (cross) icon in its main tab.□
Double‐click on the first error line in the error list window. You should see the source file be re‐opened, and your cursor be positioned at the line with the problem … don’t fix it just yet!Task List
Visual Studio has another useful window called the Task List. It’s probably already displayed in the same tab‐set as the output and error list windows, but, if not, then:□
Display the task list by selecting View > Task List from the menu (or by typing Ctrl+\ and then T) The task list window has two modes determined by the drop‐down list in its small toolbar.□
Make sure that the drop‐down list has the User Tasks option selected. With User tasks selected, a developer can manually create a to do list by clicking on the Create User Task button and entering the details of the task in the list. Tasks can then be checked off once completed, or deleted by right‐clicking on the task and selecting Delete.□
Click on the Create User Task button in the task lists toolbar.□
Type a new task … perhaps something like “Make this application actually do something!” and hit enter.□
Mark the task as complete by clicking its checkbox.□
Delete the user task by right clicking it and selecting Delete (or by selecting the task and pressing Delete). While creating user tasks in a project can be useful, what is more useful is the option to create to do comments in your code. These are comments, with a special format, that a developer can place into a source file, that will show up in the task list window.□
In the Form1.dbl code editor, add a comment like this after the bad code:;TODO: This needs fixing!
□
In the task list window, change the drop‐down list from User Tasks to Comments. You should see the comment that you entered displayed in the Task List. The TODO: prefix that you typed is what determines that the comment should be displayed in this way.□
Back in the Form1.dbl source code editor, remove the TODO comment, and the bad code.□
Perform a build to ensure that the application is in a good state (Crtl+Shift+B).Executing a Project
Depending on the type of project that you’re working on (you can’t directly execute a class library project), once you have successfully performed a build, the next thing you’re likely to want to do is run the application. Visual Studio makes this very easy. There are two main ways to begin executing a project, one is to select Debug > Start Debugging (or press F5), and the other is to select Debug > Start Without Debugging (or press Ctrl+F5). As you have probably already deduced, the difference between these two options is that with the first, if any things like breakpoints or watchpoints are activated, then control will pass to the debugger. With the second method the debugger will not be used, even if breakpoints and watchpoints are present.□
Execute the application by pressing F5 (or by selecting Debug > Start Debugging). You should see the Windows Forms program start. Of course it’s not very interesting, because all the application currently does is change the main form’s title to the string stored in the WelcomeMessage resource file string. Even clicking the button doesn’t do anything! Let’s change that:□
Close the application.□
Display the Form1 designer window.□
Double‐click on the button. When you double‐click on a control Visual Studio takes you to the code for the default event for that control. If that code doesn’t exist, then Visual Studio will insert a new empty event handler method for the event. The default event for a button is the Click event, so you should now be looking at the button1_Click method, which looks like this:□
In the data division, add a record and three integer fields, like this:
□
In the procedure division, add the following code: The point of this exercise is just to give us some code that we can interact with in the debugger later.Using the Debugger
In Visual Studio the debugger is completely embedded within the development environment, making it much easier to step through code and examine data. The debugger has many features, so we’ll just take a brief look at some of the more fundamental things that you can do. Breakpoints work in much the same way that you would expect in traditional Synergy, but are easier to work with as a result of the graphical nature of the way that they are set, cleared and visualized. Code editor windows all have a small region at the left margin where breakpoints can be set. To set a breakpoint at a certain position you simply click in this region, and you will see a visual representation of the breakpoint, like this: The red circle indicator in the breakpoint region indicates that a breakpoint is set at that position. If you execute the application in debug mode then execution will be interrupted at that point. It is also possible to have breakpoints set in your project, but disable one or more of those breakpoints so that they will not fire while you are debugging. To disable a breakpoint right‐click on the breakpoint indicator and select Disable Breakpoint. Disabled breakpoints look like this. Re‐enable a disabled breakpoint by right‐clicking the breakpoint indicator and selecting Enable Breakpoint. You can also toggle between an enabled and disabled state by placing your cursor on the source line and pressing Ctrl + F9. It is also possible to disable or enable all breakpoints via items on the Debug menu.If you wish to remove the breakpoint, simply click on the breakpoint indicator, or right‐click it and select Delete Breakpoint.
