toc

Team LiB
Next Section

Enterprise Development with Visual Studio .NET, UML, and MSF
Enterprise Development with Visual Studio .NET, UML, and MSF
by John Erik Hansen and Carsten Thomsen ISBN:1590590422
Apress © 2004 (955 pages)

Written for experienced developers, team leaders, and project managers who need a structured way of creating enterprise solutions, this step-by-step guide demonstrates how to deploy your project, analyze it, and model it using VEA.

Table of Contents
 | Enterprise Development with Visual Studio .NET, UML, and MSF
 | Foreword
 | Introduction
 | Part l - The Basics
 | Chapter 1 | - | Getting Started: A Modeling Primer
 | Chapter 2 | - | Planning and Documenting Your Solution
 | Part ll - UML
 | Chapter 3 | - | Getting to Know the Unified Modeling Language
 | Chapter 4 | - | Examining the UML Models: Behavioral Models
 | Chapter 5 | - | Examining the UML Models: Static Models
 | Chapter 6 | - | Planning a VB .NET or C# Project
 | Chapter 7 | - | Maintaining the UML Documentation
 | Part lll - VS. NET Enterprise Features
 | Chapter 8 | - | Using Enterprise Template Projects
 | Chapter 9 | - | Using Policy Files
 | Chapter 10 | - | Using Custom Help Topics
 | Chapter 11 | - | Visual SourceSafe
 | Chapter 12 | - | Visio for Enterprise Architects 2003
 | Chapter 13 | - | Application Center Test
 | Chapter 14 | - | Visual Studio Analyzer
 | Chapter 15 | - | Deploying Your Applications
 | Part IV - Hands-On Projects
 | Chapter 16 | - | Hands On: An Internal Project
 | Chapter 17 | - | Hands On: An External Project
 | Part V - Modeling Tools
 | Chapter 18 | - | IBM Rational XDE
 | Chapter 19 | - | Comparing Microsoft and IBM Rational UML Tools and Development Frameworks
 | Part VI - MSF
 | Chapter 20 | - | Microsoft Solutions Framework 3.0
 | Appendix | - | Useful Links and References
 | Index
 | List of Figures
 | List of Tables
 | List of Exercises
 | List of Sidebars

Team LiB
Next Section


backcover

Team LiB

Back Cover

Using Visual Studio .NET (VS .NET) for creating enterprise solutions, authors John Hansen and Carsten Thomsen have chosen to add the Unified Modeling Language (UML), for designing and documenting solutions, and the Microsoft Solutions Framework (MSF), for planning and managing projects.

Experienced developers, team leaders, and project managers who need a structured way of creating enterprise solutions will benefit from reading this book. Parts of this book can be used by developers (experienced or not) and managers who want to know about MSF and UML in connection with .NET development.

This guide provides an enterprise development overview, an in-depth introduction to UML, and coverage of various enterprise tools included with the VS .NET Enterprise Developer (VSED) and VS .NET Enterprise Architect (VSEA) editions, such as enterprise template projects, Visual SourceSafe (VSS), Visio for Enterprise Architects 2003 (VEA), Microsoft Application Center Test (ACT), and Visual Studio Analyzer.

Not only will you learn how to deploy your project, but also two hands-on chapters will show you how to analyze your project and model it using VEA, and guide you step-by-step through the process.

For most readers, this is a cover-to-cover book, but it can certainly be used as a reference guide whenever you need information about a particular tool or process. Throughout this book, you’ll find exercises that demonstrate the topic being discussed, making this book a must-have for programmers dealing with, or those with an interest in, developing enterprise .NET solutions.

About the Authors

John Erik Hansen is a specialist in project management, business analysis, and UML analysis/modeling. In these fields, he is credited for his ability of ensuring project successes.

John currently holds the MCSD and Rational Rose certifications, and a has graduate diploma in business administration. Lately, John has been working as a consultant on projects all over Europe. He has 10 years of experience working as a project manager, consultant, Microsoft CTEC Trainer, business analyst, and programmer (of data warehousing, e-procurement, ASP, Visual Basic, and .NET applications).

Carsten Thomsen is a Microsoft MVP, a recognition he received in August 1999. He lives in his native Denmark and currently holds the MCSE, MCAD, and MCSD certifications.

Carsten has been programming in Visual Basic for almost 12 years, and he specializes in data access, object-oriented analysis and design, and enterprise development.

These days, Carsten is primarily focused on development with Visual Studio .NET, using MSF, UML, Visual Basic .NET, and C#, but he also enjoys working with Microsoft SharePoint Portal Server 2003, Microsoft Content Management Server 2002, and Microsoft BizTalk Server 2004.

Carsten is now working as a .NET consultant mainly in London and Dublin, but he also does the odd .NET training job.

Team LiB


Enterprise Development with Visual Studio .NET, UML, and MSF

John Erik Hansen
Carsten Thomsen

Enterprise Development with Visual Studio .NET, UML, and MSF Copyright © 2004 by John Erik Hansen and Carsten Thomsen

All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher.

ISBN (pbk): 1-59059-042-2

Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.

Lead Editors
Julian Skinner, Karen Watterson

Technical Reviewers
Paul Besly, Phil Brown, Ike Ellis, Julian Skinner

Editorial Board
Steve Anglin, Dan Appleman, Ewan Buckingham, Gary Cornell, Tony Davis, John Franklin, Jason Gilmore, Chris Mills, Steve Rycroft, Dominic Shakeshaft, Jim Sumser, Karen Watterson, Gavin Wray, John Zukowski

Assistant Publisher and Project Manager
Grace Wong

Copy Edit Manager
Nicole LeClerc

Copy Editor
Marilyn Smith

Production Manager
Kari Brooks

Production Editor
Laura Cheu

Production Assistant
Katie Stence

Compositor
Susan Glinert Stevens

Proofreader
Katie Stence

Indexer
Valerie Robbins

Artist
April Milne

Cover Designer
Kurt Krames

Manufacturing Manager
Tom Debolski

Distributed to the book trade in the United States by Springer-Verlag New York, Inc., 175 Fifth Avenue, New York, NY 10010 and outside the United States by Springer-Verlag GmbH & Co. KG, Tiergartenstr. 17, 69112 Heidelberg, Germany.

In the United States: phone 1-800-SPRINGER, e-mail orders@springer-ny.com, or visit http://www.springer-ny.com. Outside the United States: fax +49 6221 345229, e-mail orders@springer.de, or visit http://www.springer.de.

For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA 94710. Phone 510-549-5930, fax 510-549-5939, e-mail info@apress.com, or visit http://www.apress.com.

The information in this book is distributed on an "as is" basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work.

The source code for this book is available to readers at http://www.apress.com in the Downloads section.


Foreword

Today, developers are continuously being overloaded with new technologies, standards, and tools, which are all being developed to fulfill customer requirements. This puts tough challenges on developers who need to produce modern software, whether it is shrink-wrapped software, enterprise applications, or part of systems integration.

Therefore, large vendors like Microsoft put a lot of effort into describing best practices and guidelines for using these new technologies, and how you can use well-proven patterns with them. Because most projects that fail don't fail because of technology issues, focusing on planning, architecture, design, and the development process will have a positive impact on the success rate of application development projects. Frequently, the disciplines of modeling, testing, and analyzing the running application are only footnotes in projects. Even worse, magazines, Web sites, product documentation, and newsgroups are biased toward code snippets,samples, and so on.

This book describes the "enterprise" (a much overloaded term—shouldn't you test a non-enterprise application?) features of Microsoft Visual Studio .NET, not only from a product feature view, but also from a general perspective, explaining why you should use them and how. For example, using enterprise templates, you can customize and restrict Microsoft Visual Studio .NET to support the application architecture that your organization has chosen. This way, you can use the development in a smart way, use new technologies the safe way, and continue to use solid and proven practices in your application development projects.

Use this book as your practical guide for getting the best out of the enterprise features of Microsoft Visual Studio .NET, and it will improve the quality of your applications.

Jørgen Thyme
Microsoft Denmark
Copenhagen, February 2004

About the Authors

John Erik Hansen is a specialist in project management, business analysis, and UML analysis/modeling. In these fields, he is credited for his ability of ensuring project successes. He currently holds the MCSD and Rational Rose certifications, and a Graduate Diploma in Business Administration. Lately, John has been working as a consultant on projects all over Europe. He has 10 years of experience working as a project manager, consultant, Microsoft CTEC Trainer, business analyst, and programmer (of data warehousing, e-procurement, ASP, Visual Basic, and .NET applications).

John lives with his wife, Karen, and son, Philip, in Odense, Denmark. He enjoys traveling and is a passionate soccer fan.

Carsten Thomsen is a Microsoft MVP, a recognition he received in August 1999. He lives in his native Denmark and currently holds the MCSE, MCAD, and MCSD certifications. Carsten has been programming in Visual Basic for almost 12 years. He specializes in data access, object-oriented analysis and design, and enterprise development.

These days, Carsten is primarily focused on development with Visual Studio .NET, using MSF, UML, Visual Basic .NET, and C#, but he also enjoys working with Microsoft SharePoint Portal Server 2003, Microsoft Content Management Server 2002, and Microsoft BizTalk Server 2004.

Carsten is the author of Database Programming with Visual Basic .NET and Database Programming with C#, both from Apress.

Carsten and his girlfriend, Mia, live in Esbjerg on the west coast of Denmark. They have a 5-year-old daughter, Caroline, and 2-year-old daughter, Cecilie. Nicole, 10, is Carsten's oldest daughter; she lives with her mother in Dublin, Ireland.

Carsten is now working as a .NET consultant mainly in London and Dublin, but he also does the odd .NET training job.


About the Technical Reviewer

Paul Besly has been producing software in various forms for about 20 years. Paul came through the classic SASD route to OO/UML, via C/C++/Visual Basic. He holds the MCSD.NET and MCT certifications.

Paul currently teaches OO design/patterns, UML, and .NET courses. As a very welcome part of this, he is also involved in a variety of mentoring activities. Prior to teaching, Paul spent many years producing software for flight simulators, road traffic systems, digital telephony, and other real-time software control systems.

His other interests include playing ragtime guitar and rugby.


Acknowledgments

This book is based on the knowledge gained by us (the two authors) from working in the IT business over the last decade or so. Having said that, we also learned a fair number of new tricks by writing this book, and that's really why we do it.

This book has been a long time coming due to various difficulties, but with the fantastic help we've had from the whole of the team at Apress and the private technical reviewers, we actually think that this is a much better book than if we had published it a year ago (or earlier), as originally scheduled.

These guys truly deserve special mention because of the time and effort they've put into the making of this book:

  • Pocholo Reyes, Consulting Manager, Database Wizards Inc. (preyes@wizardsgroup.com)

  • Samuel Santiago, a software architect who is passionate about distributed systems, component software development, and software architecture with UML (SSantiago@SoftiTechture.com)

  • Paul Besly, Principal Technologist (paul.besly@qa.com)

  • Phil Brown (MCT, MCDBA, and MCSD), Little Wolf, specialist in training and mentoring MSF, SQL Server, and Software Testing (phil@little-wolf.co.uk)

On a personal note, I (Carsten Thomsen) would like to thank my closest family for being so understanding when spending all those extra hours on this book, and in particular as I went though a minor depression for a number of months in 2003.

John Erik Hansen (jha@project2.dk), Odense, Denmark
Carsten Thomsen (carstent@dotnetservices.biz), Esbjerg, Denmark
April 2004


Introduction

I came across some of the beta chapters of this book while searching the Internetfor MSF information, and I used them as preparation for the MSF Practitioner exam. This book is a great practical approach to MSF and UML.

—Pocholo Reyes, MCSD, MCDBA, MCT, MSF; Consulting Manager,Database Wizards Inc. (preyes@wizardsgroup.com)

…Bottom line, if they complete the exercises, they will have a good grasp of how to use the UML and code generation features of VEA. The set of exercises are quite useful, and I learned a lot just working through Chapter 17.

—Samuel Santiago (SSantiago@SoftiTechture.com)

This book is all about using Visual Studio .NET (VS .NET) for creating enterprise solutions. Based on our experience, we've chosen to add the Unified Modeling Language (UML), for designing and documenting solutions, and the Microsoft Solutions Framework (MSF), for planning and managing projects.

Experienced developers, team leaders, and project managers who need a structured way of creating enterprise solutions will benefit from reading this book. In fact, parts of this book can be used by developers (experienced or not) and managers who want to know about MSF and UML in connection with .NET development. For most readers, this is a cover-to-cover book, but it can certainly be used as a reference guide whenever you need information about a particular tool or process.

We start out with an enterprise development overview chapter, followed by UML introduction and get-up-to-speed chapters. We next look at the various enterprise tools included with the VS .NET Enterprise Developer (VSED) and VS .NET Enterprise Architect (VSEA) editions, such as enterprise template projects, Visual SourceSafe (VSS), Visio for Enterprise Architects 2003 (VEA), Microsoft Application Center Test (ACT), and Visual Studio Analyzer. We then cover deployment. Next, we delve into two hands-on chapters that will show you how to analyze a project and model it using VEA, guiding you step-by-step through the process. In the final part of the book, we compare IBM Rational Rose XDE with VEA and compare the Rational Unified Process (RUP) with MSF. The final chapter examines MSF in detail.

Throughout this book, you'll find exercises that demonstrate the topic being discussed. You need VSEA to follow all of the examples in this book, although VSED is sufficient for most chapters.

We welcome feedback from our readers. We can be reached at carstent@dotnetservices.biz or jha@project2.dk. We'll gladly answer any queries concerning this book and will respond as soon as possible (of course, depending on the volume of messages, this might not be immediately).


Part l: The Basics

Chapter List

Chapter 1: Getting Started: A Modeling Primer
Chapter 2: Planning and Documenting Your Solution


Chapter 1: Getting Started: A Modeling Primer

Overview

This chapter will introduce you to enterprise modeling, enterprise development, and enterprise applications. Because we believe in learning by doing, we'll also use this chapter to let you get your feet wet. We'll walk you through two short but useful example models: one that you'll be able to use to create the skeleton for Visual Basic .NET (VB .NET) and/or C# classes and another that you can use to model the database.

So, what is it that you're about to see and learn? Well, as we already mentioned, we give you a fairly easy introduction to two rather simple Unified Modeling Language (UML) models in this chapter. Then we show you how these models are used for creating some "real" code and a database to be used by the code. We've written this chapter with the developer in mind, meaning you can generate code directly from the models you create. The UML models presented in this chapter are far from "complete"[1] and show only the class diagrams (or static structure diagrams as Visio calls them) and a database model. We assume that you're acquainted with object-oriented programming (OOP). It's not that we'll be going into detail about OOP, but we'll make use of terms such as class attributes, operations, and so on.

Basically, the aim of this chapter is to give you a look at what kind of modeling you can do with Visio. There's plenty of information for you in the upcoming chapters. In Chapter 2, you'll learn how to design and plan an enterprise solution, and in Chapters 3 through 5, you'll learn how you can use the various UML models supported by Visio to model your enterprise solution from a very high-level perspective to a very detailed perspective. So, this chapter will primarily serve as an introduction to the following chapters and, as such, the amount of detail in this chapter will vary.

If you're fairly new to application or database modeling, or if you're new to Visio, we suggest you do read this chapter; otherwise, feel free to move on to the next chapter.

[1]A UML model is never really complete, meaning you can always find things that can be expressed in a more detailed way. Our intention in stating that a model can be complete or incomplete is that you can say it's complete when all parties involved are satisfied that the information they want is contained in the model in the desired details. In other words, when it's good enough to proceed to the next stage.


Defining Enterprise Applications, Development, and Modeling

The word enterprise seems to be the buzzword these days when speaking of software development. You'll see many things labeled with the word, but it's rather hard to actually define what it is. In the context of this book, we care about only enterprise applications, development, and modeling, which we describe in the following sections.

Enterprise Applications

Enterprise applications are generally defined as applications that are built of many smaller applets, components, or programs. They are typically spread across any number of machines, effectively labeling them n-tier applications, because they consist of more tiers (physically or logically separated machines). Quite often, and ever increasingly so, enterprise applications are also physically separated on different networks across a wide area network (WAN) such as the Internet. Although there is no "proper" definition of enterprise applications, this is a good definition to use.

Enterprise Development

So what is enterprise development then? Is it when you're developing enterprise applications? No, the two are not automatically connected, although they tend to go hand in hand. Enterprise development is when you have a team of developers working on the same solution, mostly on different projects, but sometimes on the same project and sometimes even on the same functionality. Obviously, it takes more to organize enterprise development than other simpler types of development because there are more people involved. All these people must be managed so they don't perform the same task, or even worse, overwrite changes to the code made by another developer. This is one of those things you can manage by using tools that lock source code, such as Visual SourceSafe (VSS), which is described in Chapter 11.

On a project with one or two developers, you generally know what your tasks are, but more important, you also know what the other developers' tasks are. This isn't sowith enterprise solutions, because you don't have the overview of all the projects that make up an enterprise solution. That is the job of a project manager or someone with a similar role. You can read more about the various roles needed to create enterprise applications in Chapter 20.

Enterprise Modeling

Enterprise modeling is when you model your enterprise applications, with modelingliterally meaning models of your application and, in most cases, also the enterprise architecture. Enterprise modeling can be a complex task, especially when you factor in everything from working with legacy systems (and legacy people) to politics. However, it isn't necessarily so. An enterprise task certainly can be a rather large mouthful, but given the right approach, as you'll learn in the coming chapters, it's manageable and fairly easy. The keywords are planning and documentation, as you'll learn in Chapter 2.


Taking a Quick Look at Visio

Visio is Microsoft's modeling tool, and it's primarily this tool that we'll be using throughout the book. Visio is different from most other enterprise modeling tools, such as IBM Rational Rose and IBM Rational XDE, because it can be used for many different kinds of modeling, including UML and database modeling, as you'll see in this chapter. Visio isn't a new tool, but as a UML modeling tool, it hasn't been one of the major players in the market, because of its capabilities, or rather, lack of capabilities. However, the latest version of Visio (the one that is bundled with Visual Studio .NET Enterprise Architect Edition) goes a lot further than any previous version of Visio, which is why we've chosen to write about it in this book. It's by no means the best UML modeling tool around, but we do feel that it's good in many situations.

The Visual Studio .NET Enterprise Architect (VSEA) edition is the only version of Visual Studio .NET (VS .NET) that comes with the modeling tool Visio for Enterprise Architects (VEA). The other enterprise edition of VS .NET, Visual Studio .NET Enterprise Developer (VSED), doesn't include Visio. In fact, the modeling tools really separate VSEA and VSED.

Start Sidebar
Visio Versions

The Visio for Enterprise Architects (VEA) 2003 software that comes with VSEA is based on Visio 2002 Professional, which you can buy separately. However, you can't just buy the VS .NET Enterprise Developer edition and Visio 2002 Professional and hope they will give you the same functionality. VEA has everything that Visio 2002 Professional has, but it also provides integration with the VS .NET integrated development environment (IDE) through the UML add-on. This means that you get added functionality, such as reverse engineering of existing projects to UML models.

Since the release of VS .NET 2003, Microsoft Office has also been released in a new edition, Microsoft Office 2003. This also means that a new version of Visio has been released, Visio 2003, but only Visio Professional 2003 has some of the software modeling features that the VEA 2003 software has. You can see a Visio 2003 edition comparison at http://www.microsoft. com/office/visio/prodinfo/editions.mspx.

The latest edition of Visio has more features than VEA and Visio 2002 Professional, as you would expect, but only VEA has the UML add-on that allows code generation and forward engineering from UML diagrams. Visio Professional 2003 allows only reverse engineering of code. So, if you need to create code skeletons from UML diagrams, your only option at the time of writing (early 2004) is to install VEA. However, you can have both VEA and Visio 2003 installed at the same time (but because the installations overlap, Windows Installer is used to configure the active installation when you swap between the two). You can see a version comparison at http://www. microsoft.com/office/visio/prodinfo/compare.mspx.

Note that the documents produced with Visio 2003 are not compatible with previous versions.

End Sidebar

Although Visio is a stand-alone product in the Microsoft Office family line of software, it's also a professional tool for software architects, among others, which is really why you're reading this. If you're familiar with Visual Basic (VB) 6.0, you might be familiar with Visual Modeler, the rudimentary UML tool that came with VB Enterprise Edition (and was even available as a separate download for VB 5.0).This tool, which was licensed from Rational Software, has been replaced with VEA in VS .NET. Visual Modeler (which we guess, by the best of opinions, was a decent tool) was really just a "lite" version of Rational Rose from Rational Software[2](http://www.rational.com). Chapter 12 will give you a detailed introduction to Visio. We'll compare Visio to IBM Rational products in Chapter 19.

Note

If your customer doesn't own a copy of Visio, they can download the Visio Viewer that works with Microsoft Internet Explorer 5.0 or later from http://www.microsoft.com/downloads/details.aspx?FamilyID=3fb3bd5c-fed1-46cf-bd53-da23635ab2df&DisplayLang =en. This also applies for those parts of your organization that only need to read Visio diagrams and not create them. However, they could use the Web Publish facility. You can also download a trial version of Visio 2003 from http://www.microsoft.com/office/visio/prodinfo/trial.mspx.

[2]Rational Software was acquired by IBM, and the company is now called IBM Rational Software.


Modeling a Logon Process

For the first short, get-up-to-speed-fast, hands-on example in this chapter, we've decided to model a process that many people create the code for during their career: a logon process. For the modeling of the logon process, you need VEA 2003. Basically, you model the class in Visio, and later you generate the code in VB .NET or C#. You can then include the generated output in a VS .NET project.

Creating the VB .NET Class

Let's get started with creating the class on the class diagram in our UML model. In Exercise 1-1, you will start a new UML diagram and add a class to it.

Exercise 1-1
Start example

  1. Open VEA.

  2. To create a new UML model, select File® New®Software ®UML Model Diagram. It doesn't matter whether you select the UML Model Diagram (Metric) or the UML Model Diagram (US units). It's only a matter of page settings and it has nothing to do with different models. Note that one of the two might not appear on your system, depending on what you selected during setup.

  3. Create a class by dragging the Class icon from the UML Static Structure tab in the Shapes window, usually located on the left side at the top. VEA should now look like Figure 1-1.

    Click To expand
    Figure 1-1: VEA open with a new UML model diagram

    Tip

    The diagram view will probably be so small it will be hard to read when you first open it. However, you can change that by selecting a menu command in the View ä Zoom menu. There's also a list box on the toolbar for this purpose.
End example

You have the class diagram (static structure diagram) that you'll be working with. Now it's time to add attributes (variables and properties) and operations (procedures, event handlers, constructors, and destructors). You also need to give the class a name representing the functionality of the class. Exercise 1-2 shows how to do this.

Exercise 1-2
Start example

  1. Open the UML Class Properties dialog box by right-clicking the class (Class1) on the diagram and selecting Properties from the pop-up menu. You can also double-click the class.

  2. Name the class Logon by typing it in the Name text box, as shown in Figure 1-2.

    Click To expand
    Figure 1-2: The UML Class Properties dialog box

  3. Select the Attributes category in the Categories list.

  4. Create a new attribute by clicking the New button.

  5. Type m_userID in the Attribute column.

  6. Select VB::String from the Type list.

  7. Repeat steps 4 through 6, giving the second new attribute the name m_password. The UML Class Properties dialog box should now look like Figure 1-3. Note that attributes are private by default.

    Click To expand
    Figure 1-3: The UML Class Properties dialog box showing attributes

End example
Start Sidebar
Coding Conventions

Although this chapter isn't about coding conventions, and it doesn't even contain a lot of code, we want to get the message across, before you start e-mailing us about our coding conventions. We use the following Microsoft-endorsed and/or recommended guidelines:

  • http://www.gotdotnet.com/team/vb/VBSampleGuidelines.htm

  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconwhatiscommonlanguagespecification.asp

  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/ cpconvaluetypeusageguidelines.asp

  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsent7/html/ vxconcodingtechniques.asp

We're aware that some of these documents overlap, but they will give you an idea of why and how we name our classes, constants, variables, and so on.

End Sidebar
Note

VEA 2003 comes with a complete set of data types supported by the four programming languages you get with the VSEA edition: C#, C++, J#, and VB .NET. You can also choose from the Interface Definition Language (IDL) data types, which means you might avoid having separate models for different target languages. However, the IDL data types don't support all the data types in the three mentioned programming languages. On the other hand, IDL does support data types that are supported in only some of the three programming languages. One such example is unsigned data types, which aren't supported in VB .NET. One thing you can do is to use IDL data types for all the generic data types, and then use more language-specific ones when they are necessary.

Now that you've named the class and created the attributes for it, you need to create the operations for it. Exercise 1-3 demonstrates how to specify operations and their parameters.

Exercise 1-3
Start example

  1. Open the UML Class Properties dialog box (if it isn't already open).

  2. Select the Operations category from the Categories list.

  3. Create a new operation by clicking the New button.

  4. Type Logon in the Operation column.

  5. Select VB::Boolean from the Return Type list.

  6. Click the Properties button while the Logon operation is selected to open the UML Operation Properties dialog box.

  7. Select the Code Generation Options category from the Categories list.

  8. Select Procedure from the Operation Kind list.

  9. Select the Parameters category from the Categories list.

  10. Create a new parameter by clicking the New button.

  11. Type userID in the Parameter column.

  12. Select VB::String from the Type list, and ensure "in" is selected in the Kind column.

  13. Repeat steps 10 through 12, creating a new input parameter with the name password. The UML Operation Properties dialog box should now look like Figure 1-4.

    Click To expand
    Figure 1-4: The UML Operation Properties dialog box showing parameters

  14. Click OK.

  15. Select the Code Generation Options category from the Categories list.

  16. Select Visual Basic from the Target language list.

  17. Click OK. You return to the class diagram, which is updated to reflect the changes you've made. (You may need to select View ® Zoom to adjust the class size on the diagram.) The class has a new name, Logon, and the attributes and operations are displayed, divided by a horizontal line, as shown in Figure 1-5.

    Click To expand
    Figure 1-5: The class diagram with the updated class

End example

Now that you've actually completed the class skeleton for the example, let's take a moment to recap what you did to get to this point:

  1. Created a new UML model diagram

  2. Added a class to the diagram

  3. Created two attributes (private variables) for the class

  4. Created a public operation (procedure) with two input parameters

  5. Specified the target programming language as Visual Basic

Now you just need to save the UML model, following the steps in Exercise 1-4.

Exercise 1-4
Start example

  1. Select File ® Save.

  2. Browse to the location you want to save the model in and type a name in the Save As dialog box. Save the model with this name and path for easy access in later exercises and chapters: \EDWVSNETUMLMSF\Chapter 01\ VB .NET\Logon.vsd.

  3. Click OK.

End example

Generating the VB .NET Code for the Logon Class

Now that you've created the skeleton model for the Logon class, it's time to see the actual code that VEA generates from the model, which is what it's ultimately all about—generating and maintaining the code for your application. Exercise 1-5 shows how to generate the VB .NET code.

Exercise 1-5
Start example

  1. Select the Logon class.

  2. Select UML® Code®Generate. This brings up the Generate dialog box.

  3. Make sure Visual Basic is selected in the Target language list.

  4. Select the Logon class in the Select classes for code generation tree view.

  5. Select the location you want the generated output placed in by typing the path in the Location text box or by browsing to the location after clicking the Browse button. Save the output with this name and path for easy access in later exercises: \EDWVSNETUMLMSF\Chapter 01\VB .NET\ TopPackage\Logon.vb. The Generate dialog box should now look like Figure 1-6. Note that when you select the VB .NET folder, VEA assumes the Top Package folder underneath it.

    Click To expand
    Figure 1-6: The Generate dialog box

  6. Click OK. You might be prompted to create a nonexistent folder. If so, click Yes.

End example
Note

The Top Package subfolder comes from the Model Explorer, which is usually shown on the left side of the Visio workspace, as you can see in Figure 1-7. We won't be covering packages now, but a UML package in VEA resembles a namespace in .NET (that is, a logical grouping).

Figure 1-7: The Model Explorer with Top Package selected

In Figure 1-6, you can see the code-generation options for the Logon class in the Generate dialog box. Once you click OK in the Generate dialog box, the code is generated and output to the specified location. The Output window shows if any errors were encountered during the code generation.

In Figure 1-7, you can see the Top Package UML package selected in the Model Explorer. You can give your package any name by double-clicking the package. This will bring up the UML Package Properties dialog box.

Figure 1-8 shows the Output window after the VB .NET code is generated for the Logon class. In our case, there weren't any semantic errors.

Click To expand
Figure 1-8: The Output window showing semantic errors after code generation
Note

Semantic errors are programmatic errors such as incompatible data types. If you pick a data type as the return type for an operation that's not supported in the target programming language, you'll see a semantic error in the Output window.

Now let's take a look at the generated code. Go to the output location you specified in the Generate dialog box and double-click the Logon.vb file. If your VS .NET installation is working properly, and you haven't specified that VS .NET should open the last loaded solution when opening,[3] the code file is opened in the VS .NET IDE, and it should look similar to the one shown in Figure 1-9.

Click To expand
Figure 1-9: The generated VB .NET code for the Logon class

Figure 1-9 shows the generated output for the Logon class from the UML model as VB .NET code. If you're familiar with VB .NET or even VB, there shouldn't beany surprises in the generated code. However, we'll just run through the code listing, pointing out what the various code lines correspond to in the UML model:

  • Lines 4 and 15 define the class boundary.

  • Lines 6 and 8 are the two class attributes or member variables.

  • Lines 10 through 13 are the Logon procedure, declared as a Function, because you specified a return type (Boolean). The two input parameters have been declared with ByVal, which effectively means they're input parameters, because changes to the values of a parameter declared with ByVal won't be reflected in the caller of the operation.

    Tip

    To turn on line numbers in Visual Studio, select Tools ®Options ® Text Editor/Basic and check the Line Numbers option.

We're aware this isn't a lot of code, and that for such a small class it would be easier to create it the normal way. However, many useful applications do start out as small, simple, and unplanned applications, don't they?

Creating the C# Class

You've created the VB .NET class, and since the content of the C# class is the same, you need to change only a few things in the class model. The differences are the data types you used for the attributes and the operation and the target programming language. Exercise 1-6 demonstrates how to change from VB .NET to C#.

Exercise 1-6
Start example

  1. Open the previously saved Logon.vsd UML model in VEA (if it isn't already open).

  2. Open the UML Class Properties dialog box for the Logon class.

  3. Select the Code Generation Options category from the Categories list.

  4. Select C# from the Target language list.

  5. Click OK.

End example

Now you've changed the target programming language, but didn't we just state that you need to change the data types for the new target programming language? Yes, we did. However, the data types chosen for the VB .NET class were common type system (CTS) compatible, meaning they exist in all .NET programming languages. Well, this isn't quite true, but for data exchange between classes in different .NET languages to work, the exposed data types must be CTS compatible. You used the Boolean and String VB .NET data types, and they certainly have counterparts in C#. Generally, you won't find a problem when going from VB .NET to C#. A problem is more likely to arise when you go in the other direction—if you select an unsigned data type in C# and want the corresponding data type in VB .NET.VB .NET doesn't directly handle unsigned data types;[4] therefore, VEA won't be able to convert those data types for you.

If you feel confident that you can generate the C# code for the Logon class now, feel free to jump to the next section. However, for the purpose of having two different models saved in different locations and with the correct data types, follow along with Exercise 1-7.

Exercise 1-7
Start example

  1. Open the UML Class Properties dialog box for the Logon class.

  2. Select the Attributes category from the Categories list.

  3. Select C#::string from the Type list for the m_userID and m_password attributes.

  4. Select the Operations category from the Categories list.

  5. Select C#::bool from the Return Type list for the Logon operation.

  6. Click the Properties button while the Logon operation is selected to show the UML Operations dialog box.

  7. Select the Parameters category from the Categories list.

  8. Select C#::string from the Type list for the userID and password parameters.

  9. Click OK twice.

End example

The changes you've made to the Logon class should now be reflected on the diagram. Save the new model to this name and path for easy access in later exercises and chapters: \EDWVSNETUMLMSF\Chapter 01\C#\Logon.vsd.

Generating the C# Code for the Logon Class

Now that you have modified the Logon class for C#, it's time to see the code that VEA generates from the model. Exercise 1-8 shows how to generate the C# code.

Exercise 1-8
Start example

  1. Select the Logon class.

  2. Select UML ® Code®Generate. This brings up the Generate dialog box.

  3. Make sure C# is selected in the Target language list.

  4. Select the Logon class in the Select classes for code generation tree view.

  5. Select the location you want the generated output placed in by typing the path in the Location text box or by browsing to the location after clicking the Browse button. Save the output with this name and path for easy access in later exercises and chapters: \EDWVSNETUMLMSF\ Chapter 01\C#\TopPackage\Logon.cs.

  6. Click OK. You might be prompted to create a nonexistent folder. If so, click Yes.

End example

Let's take a look at the generated C# code. Go to the output location you specified in the Generate dialog box and double-click the Logon.cs file. The code file is now opened in the VS .NET IDE, and it should look like the one shown in Figure 1-10.

Click To expand
Figure 1-10: The generated C# code for the Logon class

Figure 1-10 shows the generated output for the Logon class from the UML model as C# code.

Code Generation Summary

As you've seen from the previous exercises, the code generated by VEA is nothing more than a skeleton of the class(es) you have in your UML model. However, you can add significantly more to your diagrams and have it reflected in the generated code. Specifically, we're thinking about documentation here, in the form of comments in the code, initial attribute values, visibility, scope, multiplicity in the form of collections and arrays, and so on.

[3]If you have specified that VS .NET should open the last loaded solution when opening, you can change that from the Options dialog box, or you can manually open the generated code file.

[4]The next version of VS .NET, code-named Whidbey, should be able to handle unsigned data types. It is scheduled to be released sometime in 2004.


Modeling a Database

The Logon class you created in the previous section needs to do some database lookup in order to validate the user that is trying to log on. Therefore, you need a database, which you'll be modeling in this section. In standard UML, you normally model a database as a class diagram, giving it a Table stereotype. (We'll talk more about stereotypes in later chapters.) VEA doesn't support the generation of Data Definition Language (DDL) scripts from class diagrams, which means you can't do it that way. However, VEA (and the standard versions of Visio) has a perhaps better way of dealing with databases: the database model diagram.

Creating the Database Model Diagram

VEA offers database modelers several options, including entity-relationship (ER) and Object Role Modeling (ORM) diagrams. However, in this book, we'll be using the database model diagram.

Start Sidebar
ER and ORM Diagrams

Entity-relationship (ER) diagrams (sometimes called ERDs) were introduced in the mid-1970s, originally by Dr. Peter Chen. They're used for conceptual modeling of relationships between entities, just as their name suggests. The fact that ER diagrams are used for conceptual modeling makes them different from the database model diagrams used in this book. The idea with ER diagrams is that anyone involved in a project should be able to understand an ER diagram. ER diagrams consist of different entity types, relationships, attributes, and types.

The entities are real-life objects, such as users, and sometimes they're more abstract than that, but they must be meaningful to the business. The attributes are used to describe the entities, and the relationships are used between entities.

One problem with ER diagrams is that there's no real standard, although most people use ER diagrams with only small variations. One notation that seems to have been standardized is the crow's feet notation, which is generally used to show cardinality of relationships between entities, using 0 (zero or more entity instances), 1 (one or more entity instances), or n (several entity instances). See Figure 1-11 for an example.

Click To expand
Figure 1-11: Crow's feet notation on a simple ER diagram

Object Role Modeling (ORM) is a method for designing database models at the conceptual level, meaning you're using terms and diagrams that can be understood by the user. A comparison to UML with regards to visual software communication is in order, because that's what it is: an easy way of visually communicating a database model at a level that's understood by all parties in a project. ORM diagrams are different from the database model diagrams we use in this book in the way they communicate their content. Check out the ORM Web site (http://www.orm.net) for more information.

End Sidebar

In Exercise 1-9, you'll start a new database model diagram and add a table entity to it.

Exercise 1-9
Start example

  1. Open VEA (if it isn't already open).

  2. Create a new database model by selecting File® New® Database ®Database Model Diagram. VEA should now look like Figure 1-12.

    Click To expand
    Figure 1-12: VEA open with a new database model diagram

  3. Create an entity by dragging the Entity icon from the Entity Relationship tab in the Shapes window (usually located on the top left—see Figure 1-12).

  4. Double-click the new entity (Table1) on the diagram to see the properties for it. You can also right-click the entity and select Properties from the pop-up menu. Now the Database Properties window is shown at the bottom of the Visio workspace, as in Figure 1-13. This is where you can set the properties, such as the name, for the entity that is selected on the database model diagram.

    Click To expand
    Figure 1-13: The Database Properties window open in the Visio workspace

End example

Now that you've added the table[1] entity to the diagram, it's time to set the properties of the table. Exercise 1-10 shows how to do this.

Exercise 1-10
Start example

  1. Name the table entity User in the Physical name text box in the Database Properties window. When you start typing, you'll notice that the text in the Conceptual name text box is synchronized with the contents of the Physical name text box. However, this only happens if you've selected the Sync names when typing check box, which is next to the Physical name text box.

  2. Select the Columns category from the Categories list.

  3. Type ID in the Physical Name column and select Row ID from the Data Type list. Make sure that Portable data type is selected as the Show option (see Figure 1-14).

    Click To expand
    Figure 1-14: The Database Properties window open on the Columns category page

  4. Select the Req'd (Required) and PK (Primary Key) columns.

  5. Repeat steps 3 and 4, creating two new columns named Name and Password of data type VarChar (variable length string). Make sure you select the Req'd column. The Database Properties window should now look like Figure 1-14.

End example
Note

In our example, the physical name and the conceptual name are the same, and we think it's wise to keep it that way. However, you can choose to have two different names for the table entity: one that's used in the database and one that's used in your diagrams. You would do this if you have a conceptual name with spaces or other characters that are not supported by the naming scheme implemented by the database on which you're creating the table.

In Figure 1-14, you can see the Database Properties window open on the Columns category page. There is one small problem with the two VarChar columns (Name and Password)—they've automatically been set to a maximum length of 10 characters, which isn't enough in our table. Therefore, you need to change the maximum length to 50 to accommodate a longer name and password in the table. As you can also see from Figure 1-14, the data type is named SBCS VarChar(10). SBCS stands for Single Byte Character System, which refers to the standard Western character sets that require only one byte for storing a character. However, if you need to store characters from other character sets such as Japanese or Chinese,which use two bytes of storage per character, you need to use the Double Byte Character System (DBCS).In Exercise 1-11, you'll adjust the length of two table columns.

Note

We're aware that 50 characters for a password might seem a bit excessive, but from a user's point of view, it's better to have too much space than too little. For this example, just follow the exercise instructions, which demonstrate how to change the size of a column.
Exercise 1-11
Start example

  1. Select the Name column and click the Edit button. This brings up the Column Properties dialog box.

  2. Select the Data Type tab, as shown in Figure 1-15.

    Click To expand
    Figure 1-15: The Column Properties dialog box showing the Data Type tab

  3. Type 50 in the Length text box.

  4. Click OK.

  5. Repeat steps 1 through 4 for the Password column.

End example

Figure 1-15 shows the Data Type tab of the Column Properties dialog box. You can see the data type properties for the Name column. We've set the length to 50 to accommodate a longer name than the default of 10.

Once you've changed the column lengths for the two columns, the Database Properties window should look like Figure 1-16. You can see that the column lengths have been changed to 50, because of the changes you made in the Column Properties dialog box.

Click To expand
Figure 1-16: The Database Properties window with updated column lengths
Note

If you need to know more about databases in general and database programming with C# or VB .NET, we can recommend these titles from Apress: Database Programming with VB .NET, Second Edition, written by Carsten Thomsen, ISBN: 1-59059-032-5; and Database Programming with C#, written by Carsten Thomsen, ISBN: 1-59059-010-4.

All the columns are now in place, with the ID column as the unique row ID, which we can later use for joining with other tables. We can also use Name as a unique value column, but in keeping with the way we apply the database normalization forms to our database schemas, this is how we proceed. The ID column has already been designated as the primary key of our table, meaning all values in this column must be unique and null values are disallowed.

Since the Name column is an excellent candidate for searching for a user when performing a lookup from the Logon process, it's a good idea to create an index on this column. An index will generally facilitate a faster lookup. Exercise 1-12 shows how to add an index.

Exercise 1-12
Start example

  1. Select the Indexes category from the Categories list.

  2. Click the New button, which brings up the New Index dialog box.

  3. Type IX_Name in the Non-unique index name text box.

  4. Click OK. The Database Properties window, with the Indexes page open, should now look like Figure 1-17.

    Click To expand
    Figure 1-17: The Database Properties window showing the Indexes page

  5. Select the Name element of the Available columns list, and click the Add button to add the Name column to the index.

  6. Select Unique index only from the Index type list. The IX_Name index now consists of the Name column, and the index is a unique index. (There are other options on the Index type list, but which unique index option is the best is database-specific.) The index is shown on the diagram as U1 next to the Name column.

  7. That's all you need for this simple database, so save it to \EDWVSNETUMLMSF\Chapter 01\Database.vsd.

End example

Generating the Database

Once you have your database model in place, it's really very simple to have the physical database generated. However, you do need to know which type of database you want to create and where it's located. Depending on the choice of database, you might also need to know the user ID and password for the database (hmm. . .user ID and password sound familiar). After you've selected the database type, you need to check the database model for problems that might prevent VEA from generating the database.

In Exercise 1-13, you'll generate the database model, and then check it for errors.

Exercise 1-13
Start example

  1. Select Database ® Options ® Drivers. This brings up the Database Drivers dialog box, which shows all the installed ODBC drivers on your system.

  2. Select Microsoft Access from the list and click OK.

  3. Select Database ® Model® Error Check.

End example

The Output window, which is now shown in the VEA workspace, displays the results of the error check, as shown in Figure 1-18. You can see that the logical validation went fine, but the physical validation didn't. This means that VEA won't be able to generate the Microsoft Access database, because there's a problem with the ID column.

Click To expand
Figure 1-18: The Output window showing database model error-check messages

In Figure 1-18, you can see that the physical validation against the Microsoft Access ODBC driver went wrong. The ID column has no precision specified. Wait a minute, didn't you tell VEA to use the Row ID data type and not CHAR, as it now seems to be? You did, but this is one of the cases where VEA has a problem with the selected portable data type when it comes to generating it in the physical database. But you don't need to worry, because if you know just a little about Microsoft Access, you also know that the physical data type you're after is the AutoNumber one. This data type generates a unique number for each new row inserted into the table, starting with 1 and incrementing by one, by default.

In Exercise 1-14, you will change the data type for the ID column.

Exercise 1-14
Start example

  1. Open the Database Properties window by clicking the Database Properties tab at the bottom of the Visio workspace.

  2. Change the data type for the ID column to Counter (auto).

  3. Select Database ® Model® Error Check.

End example

Now both the logical and physical validation against the Microsoft Access ODBC driver succeeds, as you can see from the Output window. Way to go! Now let's get that database on the road. In Exercise 1-15, you'll use the Generate Wizard togenerate the database.

Exercise 1-15
Start example

  1. Select Database ® Generate. This brings up the Generate Wizard, as shown in Figure 1-19.

    Click To expand
    Figure 1-19: The opening page of the Generate Wizard

  2. Select the Generate new database option.

  3. Click Next. Now the second page of the Generate Wizard displays, as shown in Figure 1-20. This is where you specify the type and physical location of the database.

    Click To expand
    Figure 1-20: The second page of the Generate Wizard

  4. Make sure Microsoft Access is selected in the Installed Visio drivers list.

  5. Select the Create MDB file option.

  6. Click the New button. The Create New Data Source dialog box appears.

  7. Select the System Data Source option and click Next.[2]

  8. Select Microsoft Access Driver from the list and click Next.

  9. Click Finish. The ODBC Microsoft Access Setup dialog box is now shown.

  10. Type Chapter 1 Database in the Data Source Name text box.

  11. Click the Create button. This brings up the New Database dialog box, which is really nothing more than the well-known Save As dialog box.

  12. Browse to the \EDWVSNETUMLMSF\Chapter 01 folder and type Database in the Database Name text box.

  13. Click OK.

  14. Click OK in the confirmation dialog box.

  15. Click OK in the ODBC Microsoft Access Setup dialog box.

  16. Click Next.

  17. Click OK in the Connect Data Source dialog box, because you haven't specified a user name or a password for the database.

  18. Click Next on the database table review page.

  19. Click Finish.

End example

After completing the Exercise, you're asked if you want to see the generated DDL script. Click Yes to open up the Visio Code Editor with the DDL script.

In Figure 1-21, you can see the DDL script for the Microsoft Access database you just created. You don't actually need the script, because the database was also created. However, it's good practice to have a script for all database objects your application relies on, because it's important to be able to re-create a databasestructure quickly in case of an emergency, such as if the database becomes corrupt and can't be fixed. You might also want to have the DDL script for testing purposes.

Click To expand
Figure 1-21: The Visio Code Editor with the Microsoft Access DDL script

If you have Microsoft Access 2000 or later installed on your system, you can open the database to see that the User table has been created with the columns specified and the correct data types.

Reverse Engineering a Database

Reverse engineering is, as the name suggests, the reverse of forward engineering or code generation from a UML model. So, reverse engineering is when you create a UML model from an existing VS .NET project or even from an existing database. With VSEA, you do any reverse engineering from within the VS .NET IDE. With stand-alone Visio 2000 Professional and Enterprise Editions, Visio 2002 Professional Edition, and the Visio 2003 Professional Edition, you can do it from within Visio.

As an example, let's try reverse engineering a database table. We'll reverse engineer the Customers table from the Microsoft Access Northwind example database,[3] but you can just as easily choose to reverse engineer a copy of the Customers table from your own organization. In Exercise 1-16, make sure you replace the Microsoft Access Northwind bits with the setup for your desired data source.

Exercise 1-16
Start example

  1. Open VEA (if it isn't already open).

  2. To create a new database model, select File ® New®Database ®Database Model Diagram.

  3. Start the reverse engineering by selecting Database ® Reverse Engineer. This brings up the Reverse Engineer Wizard, as shown in Figure 1-22.

    Click To expand
    Figure 1-22: The Reverse Engineer Wizard

  4. If you already have an ODBC DSN for the data source you want to reverse engineer a table from, select it from the Data Sources list and skip to step 13. If not, click the New button to create one. The Create New Data Source dialog box is now shown.

  5. Select the System Data Source option and click Next.[4]

  6. Select Microsoft Access Driver from the list and click Next.

  7. Click Finish. The ODBC Microsoft Access Setup dialog box is now shown.

  8. Type Northwind in the Data Source Name text box.

  9. Click the Select button. This brings up the Select Database dialog box, which is really nothing more than the well-known Open File dialog box.

  10. Browse to the Northwind.mdb database file on your system, or type in the name and path in the Database Name text box. It's usually located in the Program Files\Microsoft Office\Office11\Samples folder (if you have Microsoft Office 2000 or Microsoft Office XP installed).

  11. Click OK.

  12. Click OK in the ODBC Microsoft Access Setup dialog box.

  13. Click Next.

  14. Click OK in the Connect Data Source dialog box, unless you have specified a user name or a password for the database.

  15. Remove the selection from the Views option on the database objects review page of the Reverse Engineer dialog box and click Next.

  16. Select the Customers table on the database tables review page, as shown in Figure 1-23.

    Click To expand
    Figure 1-23: The database tables review page of the Reverse Engineer Wizard

  17. Click Finish. Your database model diagram is now updated with the reverse-engineered Customers table, as shown in Figure 1-24.

    Figure 1-24: The reverse-engineered Customers table on a class diagram

End example

[1] Table is a physical database term, and entity is a conceptual database term. You should keep this in mind, because Visio sometimes seems to mix the two.

[2] You can just as easily choose one of the other options, but for the sake of this example, please follow the Exercise.

[3]The Northwind sample database comes with most versions of Microsoft Access, but it's also an optional setup part of Microsoft SQL Server 2000.

[4]You can just as easily choose one of the other options, but for the sake of this example, please follow the Exercise.


Summary

This chapter introduced you to enterprise modeling by means of one UML model that was used for generating a class (Logon) in VB .NET and C#, as well as a database model that was used for generating a small database with just one table (User) in Microsoft Access.

These two simple models were described in detail, and you saw how the two models were created and how the actual code and database were generated from within VEA. You also saw how you can reverse engineer an existing database into a database model diagram.

So why would you really want to use modeling for your enterprise solutions? Well, modeling is quick, and it saves a lot of the drudgery of repeated typing because of DDL scripts and the code skeleton generation. Modeling also serves as part of the solution documentation. Another important reason is that you reduce the risk of errors when data names and data types are transcribed between designs, databases, and application code.

The next chapter presents some guidelines for how to design and plan your projects and solutions.


Chapter 2: Planning and Documenting Your Solution

Overview

"If you are failing to plan, you are planning to fail."

—Unknown

In this chapter, we introduce you to the concepts of solution design and planning. The majority of the chapter covers design. We explain what design really is, as seen from a rather wide perspective, and the implications of design to a software solution. We also introduce the Microsoft Solutions Framework (MSF) 3.0 design process and explain how Microsoft advises you to design your solutions. You'll see why solution design is so important and what it means if you choose to skip solution design. You'll also learn how design affects the cost and quality of your final software solution. You might even restrict yourself from selling your solution to certain customers if your design doesn't fulfill some specific design requirements. For example US federal agencies must purchase software that is designed according to the "508"[1] design standard, making it accessible to employees and the members of the public who are disabled. If you fail to meet these demands, you may lose the contract.

Toward the end of the chapter, we provide a light introduction to planning. First, we cover what planning is and why it is so important. Then we discuss how design is coupled with planning and how to plan your project.

After reading this chapter, you'll be able to define what solution design and planning are. You'll also be able to design and plan your own software solutions. The concepts, terms, and ideas introduced in this chapter are fundamental to your understanding of the following chapters, and you'll learn why we choose to design software solutions and, perhaps more important, why we use the Unified Modeling Language (UML). Throughout the chapter, we present some examples and diagrams that we would like you to consider as simple guides, meaning that everything will be explained in detail in the following chapters.

[1]Section 508 was signed into law by President Bill Clinton in 1998. It requires that electronic and information technology developed or purchased by the federal government be accessible by people with disabilities.


What Is Design?

Before we start explaining why design is so important in your software solution, let's look at the concept of design. Design isn't only about the well-known design features that we hear about all the time—for example, the graphical user interface (GUI) design in a software solution, which specifies how the various screens and dialog boxes in the solution will look. The truth is that there is much more to design than this, and design exists in a number of aspects in our daily lives.

Try pointing out something from your everyday life that has been designed. It isn't very hard—take your cellular phone,[2] for instance. It certainly has been the subject of a lot of design considerations. Your phone has been a subject for software and hardware designers, because they have needed to design how the phone should function. They have also discussed the user interface and input mechanisms, or how you access the functionality in the phone. Almost all cellular phone vendors have designed their phones with a keypad as the user interface, but some vendors have made design considerations that are remarkably different. For example, the physical design varies a lot; you can buy cellular phones in different sizes, shapes, and colors—all because they have been designed differently. See the point? Design is about look, feel, functionality, and so on. In fact, design is part of everything that involves considerations about how something is created.

Another example of design from your everyday life is your house. Your house was designed in a lot of different ways before the contractors started building it. A design-output example from the design phase is a blueprint. It's hard to imagine your house being built without a blueprint (design). Before you start physically building the house with bricks and mortar, you need a clear picture of what you're about to build. And to have an even better appreciation of how the house will look, you may want to request from your architect a scale model (physical design).Other outputs from the house-design process (tasks you need to do before you can start building) are as follows:

  • Budget for the house

  • Description of what the house will be used for

  • Negotiations with contractors (regarding the construction of the house)

  • Choice of materials

  • Time frame for the building process

  • Analysis of the physical environment where the house will be built

I'm sure you understand that design is simply the process of addressing all necessary considerations before building your product or performing your task. It's easy to identify other things that have been designed. Your car, for instance, has been designed for appearance and functionality. When creating a software solution, it shouldn't be any different. Software is such a hard concept to grasp because it's more conceptual than physical. For instance, a scale model of a house physically looks like a house, but smaller in size. This is the truth for any other physical object. Software isn't as easy to represent. So, creating models to embody the different aspects of software architecture is essential.

It's our aim to show you that design isn't only about cellular phones, houses, and cars. Design is part of anything you consider how to create before you actually create it. Now this certainly broadens the concept of design, doesn't it?

Why Design Is Important

Now that we've established a definition of design, you might ask, why is it important to design? Well, first of all, we can look at some situations where it's impossible tocreate a certain product or perform a certain task if no design has taken place. The house-building example comes in handy here. Imagine the contractors building the house without a blueprint, a usage description, or any instructions. The building process would be almost impossible. Worse yet, the final house would most likely not be as you expected, or the house would be useless for the purpose you had in mind. You could end up with a doghouse instead of a single-family home.

It becomes a bit trickier when it's actually possible to create something without first designing it. Because modern software development tools have been created for fast prototyping, they give developers the ability to do just that. As I'm sure you know, you can easily create software solutions by simply typing in lines of code off the top of your head, without designing the solution first. In such a case, why should you bother designing the solution? Well, we can't leave this question hanging for very long. We have two answers to this question:

  • Diving straight into the code, without first designing, doesn't mean that there is no design process. It just means that design is done simultaneously with the coding. The result is that the coding is somewhat slower, because you're considering the solution design while typing away, and it's easy to lose sight of the concept.

  • The feature and design optimizations are not done yet, which results in a less flexible and perhaps more expensive solution. If you start out by coding, you might not discover some issues relevant for optimization before you've actually coded them. Recoding functionality is a huge waste of time.

Good vs. Bad Design

Now that you've learned why design is important, you need to find out what can be characterized as "good design." If you think back to the cellular phone example, one good design element is the phone's size. Cell phones are generally designed in such a way that they fit in your pocket. This is a very useful design! The input interface is a keypad, which is also an example of good design because it enables you to easily control and use your phone's functionality.

Criteria for Good Design

Some criteria for good design are as follows:

Makes the solution usable: The design must make the solution usable for its intended purpose. If the purpose of the solution is to save the users time when managing their schedule (for example, an electronic calendar system), it must be easy to use. If the solution makes the task of schedule management more difficult or slower (for example, if users find it's better to use a regular, paper-based calendar[3]), the usable criterion isn't met, and thus the design is bad.

Fulfills the expectations of the target audience: This is a very critical point. First, you must determine who the target audience is. Next, you need to determine the characteristics of the target audience. When you create a software solution, you should analyze the characteristics of the target users by describing their educational background, computer skills, age, language skills, and so on. Finally, you gather the expectations and requirements from the target audience. You can do this through interviews. Then you have the information you need to determine the expectations of target audience.

Isn't error-prone: This criterion relates to the overall experience with a solution. Users have a nice experience when the solution isn't error-prone.

These criteria are seen from the users' perspective, but many other stakeholders are involved in a software solution. Management has an obvious interest in the solution, and customers also have an interest in the solution. The business organization has an interest in and expectations from the solution. From a business perspective, a usable, error-free solution that fulfills users' expectations can still be a failure. For example, business criteria might include the ability to integrate with existing legacy systems and a return on investment (ROI). If the solution doesn't fulfill the business's needs or expectations, it's considered a failure, and the failure can be tracked back to bad design.

From the business's perspective, good design is determined by how well the solution benefits the business. If you design a solution to solve a problem that brings very little value to the business, and you design it in such a way that makes the solution cost $1 million,[4] or any other seemingly crazy figure, you've crossed that line and introduced a design flaw.

To the list of good design guidelines, we can add the following guidelines, as seen from the business's perspective:

Provides benefits: It's important that the solution is beneficial to the business. You can ask yourself this question: Will the solution designed in this way make the business more efficient and improve the bottom line? If the answer is no, you might redesign the solution or even consider not developing the solution at all.

Is useful: The solution must be useful from the business's perspective. If the solution doesn't optimize any business processes at all, it isn't useful to the business. If the solution is impossible to integrate with existing systems, and it is difficult to scale and maintain in a sensible way, the solution isn't very useful, even though the users might like it.

Criteria for Bad Design

Okay, so what about the criteria for bad design? Well, a rule of thumb is that bad design doesn't fulfill expectations about the product and/or makes the product dangerous to use. Examples of bad design are as follows:4. Does the Oracle advertisement ring a bell here?

  • Air bags in cars that inflate unexpectedly or at the wrong time[5]

  • Poisonous toys

  • Rubber boots with holes in the heels

  • Software solutions that don't solve the users' needs

The example of air bags that inflate unexpectedly can be characterized as not fulfilling expectations in addition to being dangerous.[6] We all expect cars to be safe. Unsafe cars, then, do not fulfill our expectations.

But what about product designs that seem perfectly fine at first sight? Can they, too, be lacking in expectation fulfillment? They certainly can. Think of the cellular phone we discussed earlier. We decided it should be considered a good design. Now what if the specific phone (let's call it CellPhone2000) is targeted at adisabled audience who suffers from myopia?[7] The CellPhone2000 phone can certainly be considered a bad design if the keypad and display are made in such a way that makes the phone impossible for the target audience to use. What seemed like a good design turned out to be a bad design, because the target group had certain unfulfilled expectations.

Note

In order to determine if a design is good or bad, you must know not only the requirements, but also the characteristics of the users and their expectations.

The Cost of Bad Design

Bad design can be costly. If you look back at the example of car air bags that inflate unexpectedly, the bad design has, as you might have guessed, enormous costs. The makers of the cars with these air bags installed must fix the problem in every single car, spending an enormous amount of time and money. Even worse, one incident with an air bag could cost the company its good reputation, and the recent marketing campaigns might be wasted. This is because customers lose faith in the product and in the company.

Another cost of bad design is related to redoing[8] and revising. When you need to redo something, you tend to exceed your initial time budget, and the tasks you must do over again are a waste of time. Again, think of the car company with the faulty air bags. If they discovered the problem with the air bags inflating unexpectedly before the air bags were installed in the cars and sold to customers, the cost involved would, of course, be much less. However, the closer to the date for selling the cars to the customers the problem was discovered, the more costly it would be to correct the problem. The reason for this is that the closer you get to the point where you can sell or release your final product to the customers, the more you'll need to redo and the more work you'll have to discard. And all this revision must be done just when time is getting more and more precious.

As Figure 2-1 illustrates, the cost of correcting bad design increases over time. This is because more time is wasted. So, as you can see, bad design can have a tremendous financial impact when you create solutions. Another cost of bad design is the time involved to redo things and correct errors.

Click To expand
Figure 2-1: The cost of fixing bad design

So far, we have used only real-world product examples to demonstrate the costs of bad design, but design is not only related to physical products. Your software solutions also involve a lot of design issues. You design how to solve a specific business problem, you determine the technology needed to build the solution, and you specify what to develop and how it should be developed. Maybe you even prepare the user interface in relation to the users. All these steps are part of the design of the software solution you're building, and all of them need to be completed before you can start the actual coding. Otherwise, you risk making costly design flaws.

If you create a badly designed software solution, you'll very likely end up with a solution that isn't usable for your purpose. Furthermore, you'll need to correct errors and look-and-feel problems as you discover the undesirable features of your solution. Such corrections are very costly. Numerous studies show that a design problem that must be corrected once the product is in production can cost 10 to 100 times more than it would if it had been fixed at the requirements stage. This is a convincing statistic for customers or developers who want to skip the design stage to obtain an earlier ship date. As Figure 2-1 illustrates, the more time that passes before bad design is corrected, the more costly the bad design becomes.

If you have a bad design and decide not to correct it, but instead ship it as is, you face some additional problems:

Morale: The morale of the project group might be adversely affected by the fact that the group members are working hard to deliver a solution that's likely to be a failure because it either doesn't fulfill expectations or isn't usable for its intended purpose.[9] The group's adversely affected morale could lead to a slower development pace, which again could lead to exceeded deadlines and even more damage to morale. This is often a vicious cycle. No one wants to be associated with a "loser" product or a "loser" team.

Money: You can't avoid losing money if you choose to ship a product on time without correcting bad design. If you're developing a solution for internal use, and the solution isn't usable, your company will suffer from not getting an ROI. If your solution is targeted at external use, you might face poor sales and demands for error corrections, which can also be very costly.

Time: Bad design costs time. The time costs appear when you need to correct errors or redo the design and development. Also, remember that the damaged morale in the project group can cause reduced development speed, resulting in additional delays.

Reputation: Software developers who work with technology become accustomed to setbacks and imperfections, but business customers are not always so tolerant. Not correcting bad design often results in a damaged reputation for the company, and maybe for the project group as well. If you ship solutions with known design flaws, you will undoubtedly get the reputation of delivering poor-quality solutions. Such a reputation can be very hard to get rid of, and it can be damaging to both future sales and internal morale.

You don't have a choice about whether you'll discover bad design. You dohave a choice about when you discover it. When could be the difference between a successful project and one that is abandoned at a later stage. To ensure that you find out about problems as early as possible, you need to design and plan your solution properly before development. That is what this book will enable you to do in your .NET enterprise development.

[2]Anywhere but the US, this is also referred to as a mobile phone.

[3]For example, if your solution is difficult to use or isn't available outside the office, the users might be better off with a paper-based calendar.

[4]Dose the Oracle advertisement ring a bell here ?

[5]By "wrong time," we mean that the air bag inflates too early or too late when a crash happens.

[6]This actually could be an implementation issue, meaning that it was incorrectly implemented. For the purpose of our discussion though, it's bad design.

[7] Myopia is a condition in which a person can't see distant objects. For instance, a myopic person might hold a sheet of paper right in front of his or her eyes in order to see it.

[8] Redoing refers to the process when you need to delete code and start from scratch because the functionality wasn't developed the way it should have been in the first place.

[9]User expectations may be a long list that the project team may not be able to handle in one release. The right thing to do is to let the customer create a prioritized list of the expectations and implement the expectations in versions of the solution.


The Microsoft Solutions Framework Design Process

You've now seen what design really is, why it's important, and why it's a critical factor for success in an IT project. Now you'll dig into the design process and learn the steps you should complete to design a solution.

This section focuses on the way Microsoft suggests design is best carried out. The Microsoft design guidelines are incorporated into the Microsoft Solutions Framework (MSF). See http://www.microsoft.com/technet/ treeview/default.asp?url=/technet/itsolutions/ tandp/innsol/Default.asp for more information and Chapter 20 for a discussion on how to use the MSF. You should also take a look at the Microsoft patterns and practices at http://www.microsoft.com/resources/practices/.

In Chapter 20, you'll learn how to plan and develop a project using MSF throughout all the phases. (This chapter focuses on the planning phase.) The reason for choosing the MSF design process is that it's perfect for designing solutions in a Microsoft environment (it's based on best practices within Microsoft itself), which is exactly what you're about to do: Design a solution with VS .NET. Besides this obvious fact, the MSF design process is very useful for doing iterative development in an ever-changing world, and it actually fits in with other technologies as well. In fact, the MSF design process is technology-independent by nature. You start out by designing the solution without making any technology decisions, and then afterwards, you select the appropriate technologies for developing the solution, regardless of whether the right technology choice is a Microsoft technology. This is also the case with UML: You design your solution, regardless of the technologies you'll use in the development phase. This is an important issue, because if you determine in advance which technologies you'll use, before all the requirements, usage descriptions, and expectations are known, your risk of making a design flaw is high.[10]

The philosophy behind the MSF design process is that a solution must be designed without determining technology choices before all issues are known. This is exactly what has been outlined as a key point in good design.

Another important issue in Microsoft's philosophy of good design is that all perspectives in the solution need to be addressed. What perspectives exist in the design and development processes of a solution? Well, you've already seen that the users and the business have different perspectives, and that these perspectives need to be addressed differently. What other perspectives exist? The project group includes the developers' perspective. This adds up to a total of three different perspectives. To handle these three perspectives, Microsoft has divided the MSF design process into three separate steps:

Conceptual design: In the conceptual design step, the users' perspective is taken into account. In this step, you gather and organize all the requirements and information from the users and other stakeholders that can contribute to the users' perspective. At this stage, you shouldn't use technical terms such as database constraints, triggers, threading model, and so on. This is important because it's the users' perspective you're analyzing, so you must use language the users can understand. The output from this step is a requirements list, a use case model, and scenario and/or sequence diagrams (using UML). This phase is important, and the output may not be limited to the output mentioned.

Logical design: In the logical design step, the perspective moves from the user to the project group. Input to this step is the output from the conceptual design step. In the logical design step, the project group looks at the diagrams and descriptions created in the conceptual design step and tries to figure out how the solution can be designed. The output from this step is a business object model (or models) showing which objects are part of the solution and how they relate to one another, and lists of objects and services.

Physical design: The physical design step moves the perspective from the project group to the developers. In this step, the output from the logical design step is analyzed and transformed into physical object diagrams, physical database diagrams, deployment diagrams, and so on. The goal in this step is to design the solution so it can be developed and implemented.

Note that these three steps are evolutionary and can—and do—overlap. They are explained in detail in the sections that follow.

So far, we've focused on how MSF provides you with an efficient design process, but what about UML? This book is supposed to be about .NET, UML, and MSF, isn't it? Yes, indeed it is, and that's exactly what the book covers. The truth is that UML gives you an excellent way of describing things, using a common language that can be understood by everybody, but UML doesn't provide you with a design process or give you a sequence in which to complete tasks. This is where MSF comes into the picture. MSF provides you with a design process and guidelines for how the design process is carried out.[11] MSF provides you with the process and guidelines for designing, whereas UML provides you with the language to describe and document the functionalities and architectures analyzed and covered in the design process. (MSF and the MSF structure are explained in detail in Chapter 20, and the UML models are explained in detail in Chapters 4 and 5.)

Conceptual Design

Conceptual design is the first step in the MSF design process. In this step, you gather all the user requirements and structure them into little pieces of processes you'll have in your solution. The goal is to cover all user requirements, expectations, and needs for the future solution. You'll need a clear understanding of the business processes, which are the processes in the business. Business processes contains all the tasks needed to perform the process, including non-IT tasks. For example, a business process can contain the non-IT task "The janitor places a copy in the basement."

The output from this design step is use case models, which are descriptions of requirements and usage, and scenarios of how the processes in the use case models are performed. All output is modeled using UML.

Gathering Requirements

The first thing you need to do is in this step is gather all the requirements for the solution from the users' perspective and the business's perspective. Some of these requirements might already be present. For example, you may already have a list of requirements the users have identified. Incidentally, this list might have initiated the project in the first place. You might also have a very good understanding of what the requirements are. This is true for simple, small-scale projects, where simple business processes are handled.

There are other times, though, when the total requirements are not present. This is the case when the processes involved are very complex and when the project itself is complex. In a simple project with simple business processes, such as a system for project time tracking, you can go directly to creating the use case models, scenarios, and descriptions. In the case where the business processes involved and the project itself are complex, you need to do a bit more legwork to gather all the requirements for modeling with UML.

When you face a complex project, you need to look at means for obtaining requirements other than just asking the users for their requirements list. Some additional means for gathering requirements that you might consider are as follows:

Interviews: This is a very compelling way to obtain requirements, because it covers interviews not only with the end users, but also with the sponsor and management. In fact, all stakeholders can be interview candidates. The goal here is to identify processes and requirements needed in the solution. Joint design sessions with the main stakeholders can be very productive for reaching an agreement on scope.

Current systems: Analyzing and documenting a current system (if one exists) that solves the needs of users and that you're going to make a new version of can be very valuable. There are three reasons for this. First, the project group members get the opportunity to know the existing system, which ensures that all project group members have the same understanding of the old system. Second, you can use the analysis of the current system to identify any gaps between the current and future system. This can be important. You don't want to miss important features included in the old system and create a system with less value. Third, analyzing the current system can help you identify important business processes that you need to know about your project. That said, you must be careful when you do the current system analysis. Our experience is that if the system is not very complex and the project group is familiar with the current system, this time-consuming task isn't very beneficial. Documenting the current system in full can result in the classic "paralysis by analysis"[12] syndrome.

Enterprise architecture: Looking at the enterprise architecture can provide you with valuable information about how the organization does business. This can be business processes or activities related to the processes involved in your project. Imagine that you're building an e-commerce solution. Wouldn't it be nice to know which business activities are performed after your solution sends an order to the back-end systems? It certainly could be. By examining the enterprise architecture, you get the chance to identify other applications and see how they relate to your solution. You might also uncover the infrastructure and information needed to perform the business activities. In short, you analyze the current organization and its business activities in order to identify valuable information or business processes needed for your solution.

All these processes and information can, of course, be documented and described using UML.

Diagramming High-Level Requirements

After you have gathered all the requirements and have a clear understanding of the business processes involved in your solution, it's time to transform this knowledge into diagrams using UML. Remember that it's still the users' perspective that you must use, meaning that you still need to involve the users and employ language they can understand. UML has some diagrams used for describing requirements and processes in a nontechnical way: use case diagrams and activity diagrams.

The first thing you need to do is line up all your processes.[13] Then you draw the processes one by one. When this is done, you draw the actors and the relationships between the processes and actors. Actors are simply people or things that interact with the solution (Chapter 4 provides more details about actors and other diagram elements). For example, say you have an e-commerce application with a total of two processes—an ordering process and a shipping process—just to make the example simple. In this example, the only items you implement in your solution are the ability for a customer to place an order and the functionality of sending the order to shipping. Figure 2-2 shows a use case diagram with the two processes.

Figure 2-2: Use case diagram with two processes

For each of the processes, you now diagram which actor interacts with the process, meaning who inputs something to the process or receives something from the process. This doesn't need to be physical input; it can also be information. Figure 2-3 shows the processes with the corresponding actor and its relationships to the processes.

Click To expand
Figure 2-3: Use case diagram with an actor and two processes

Figure 2-3 is a use case diagram showing a group of use cases with relationships and an actor. You should now have a clear picture of which processes will be implemented in your solution. You also know which users will interact with which processes.

Diagramming Scenarios

The last step you need to perform in the conceptual design phase is to create scenarios for each of the processes you found when you diagrammed the high-level requirements. You can see from the use case diagram which processes form the solution. However, knowing which processes are parts of your solution isn't enough information for designing the solution in more detail. You must also know how each process is performed, and you must know which tasks are involved in performing the individual process. When you gather this information, you can write down a simple sequence of tasks needed in order to perform the entire process.

A sequence of tasks for performing the order process can look like this:

Precondition: A product has been selected.

  1. The customer places the product in the shopping basket.

  2. The customer continues to check out.

  3. The customer accepts the order.

  4. The customer selects a shipping method.

  5. The customer accepts the final order, including the shipping price.

Postcondition: The order is placed in the system.

This scenario is correct, and you don't need to go any further. In Figure 2-4, you can see the interactions between the customer (user) and the system.

Click To expand
Figure 2-4: The customer interacting with the system

If you describe the scenario using UML, you'll benefit from a good overview and an easy way of identifying objects and services, once you start the logical design step. So, the scenario expressed using UML can look like the sequence diagram shown in Figure 2-5.

Click To expand
Figure 2-5: UML sequence diagram

In Figure 2-5, you can see the system in detail, described using a UML sequence diagram. To build the solution, you need to know what happens inside the system.

Getting User Acceptance

One very important thing to remember in conceptual design is that you need acceptance from the users. The users need to sign off on the design and confirm that the created diagrams are valid and sound enough to move on to the logical design step. This doesn't mean that the conceptual diagrams are frozen and can't be changed. It simply means that you have a baseline for how the processes will be implemented. Having the users sign off on the conceptual design enables you to communicate what you've agreed upon before you move on, and it also requires the users to be sure of what they've been telling you.

You've been introduced to conceptual design and seen the UML models involved in this step, which are the use case model and the sequence diagram. By doing conceptual design, you gather the high-level requirements as seen from the users' perspective. You use UML to describe the requirements and high-level processes, and by using UML you have a language that is commonly understood. The description in the conceptual design isn't technical, but it matches the users' conceptual view of the domain expressed in ordinary language.

Logical Design

Logical design is the second step in the MSF design process. In this step, the focusmoves from the users' perspective to the project group's perspective. In this step, members of the project group get together and try to work out how the solution will be built so that the requirements and processes identified in the conceptual design step can be implemented.

When the perspective is the project group's, you need to use language understood by all project group members. You still can't use technical language (database triggers, threads, object pooling, and so on), but instead you use—yes, you guessed it—UML to describe the objects forming the solution. Remember that the project group consists of many different professionals: technical people, such as developersand engineers, as well as nontechnical people, such as project managers and business analysts.

The goal in the logical design step is for the project group to gain consensus about what the solution should look like and what will be developed. This is done by creating logical object models using UML. The input to this design step is the output from the conceptual design. The output from this design step is object models showing what will be developed (still in a nontechnical form).

Understanding the Big Picture

Understanding the big picture is exactly what logical design is all about. It's about the project group getting a clear and agreed-upon understanding of what will be developed in the development phase. To do this, the project group takes the output from the conceptual design and analyzes the various parts.

In the house-building metaphor, this step is the drawings you make with your family when designing your house. On a piece of paper, you draw how the rooms will be placed in your house and where the doors and windows will be located. The drawing might be to scale or it might not be—this isn't important. The important thing is that you and your family have a common and clear under-standing of what will be built and what the house will look like. In this case, you and your family are the project group. If your drawing is a real blueprint with the correct scale and all the technical words and measures needed for the contractors, you'll definitely have problems when discussing the drawing with your family (project group). Maybe you'll all be confused, or maybe your kids can't participate in the discussion because the drawing is too confusing to them. You draw a simple drawing to start with, so that all members of your family (project group) can participate.

This is precisely what you're after in the logical design process of your software solution. You need to have a simple drawing of the solution building blocks first. Otherwise, you'll lose the participation of some of your project members. Finally,it's almost impossible to identify the physical needs if you don't have a picture of what you want to build. This goes for both houses and software solutions.

Identifying Business Objects

First, you'll need to look at all your requirements and use case models from the conceptual design and try to identify the business objects. Business objects are things or people in your solution that do any of the following:

  • Receive information from your solution.

  • Deliver information to your solution.

  • Control parts of your solution.

  • Are controlled by your solution.

In other words, the business objects are things or people that are part of your solution.

Identifying objects is generally the hardest concept for beginners to grasp, but don't worry; after a few hands-on examples, you'll have a good understanding ofhow it works. Before introducing you to the way of identifying objects, let's take a look at the object types:

  • Persistent objects are, as the name suggests, objects that have a life of their own in your solution. Persistent objects are always in your solution, whether you are logged on, shutting down the solution, or working with your solution. For example, in an e-commerce solution, a persistent object can be Order. The Order object will have a life of its own and persists its data, usually in a database.

  • Control objects tie together events and handle the communication between the objects. For example, handling the messages in a message queue will be controlled by a control object. Control objects are usually not persistent.

  • Boundary objects are objects (in the system boundary) facilitating the interaction between the system and one or more outside objects. For example, the actors discussed earlier are boundary objects.

Let's go back to the house-building metaphor. In this example, the business objects are the doors, windows, walls, roof, father, mother, kids, dog, and so on. All of these things are part of the solution and relate to the solution. The walls divide rooms and hold the roof, the mother sleeps in the house, the kids open windows to let fresh air in, and so on.

When you identify business objects, a good rule of thumb is that nouns in your scenarios are very often business objects, as in the scenario shown earlier:

Precondition: A product has been selected.

  1. The customer places the product in the shopping basket.

  2. The customer continues to check out.

  3. The customer accepts the order.

  4. The customer selects a shipping method.

  5. The customer accepts the final order, including the shipping price.

Postcondition: The order is placed in the system.

In this scenario, the rule of thumb points out that the customer, order, product, shopping basket, check-out point, shipping price, and shipping method might all be business object candidates. For now, this is true. Later, you'll look at the business object candidates and discard the irrelevant ones. Others might not even be business objects at all.

You can also identify business objects by analyzing the use case diagrams and sequence diagrams. If you look at the use case diagram in Figure 2-3, you'll notice that the actors are often business objects. When you examine the sequence diagrams, you'll notice that the solid boxes often represent business objects. This is only a rule of thumb, and it isn't always correct. In the sequence diagram shown in Figure 2-5, the business objects are Product, Customer, and Order.

After you identify the business objects, you're ready to move on to identifying the business services.

Identifying .NET Services

The next step in getting the big picture is identifying .NET services.[14] First, let's look at what .NET services are in the first place. .NET services are isolated functionalities performing a service or handling a task. This is no different from whatyou're used to thinking of services in the COM+ world. Actually, the service concept is exactly the same, so the identification process isn't any different.

The difference between .NET services and the services you developed before using the .NET platform lies in their physical implementation. .NET services tend touse different protocols that make them accessible to remote clients. "Windows DNA is dead," you might be told when talking to .NET developers. "Well, not quite yet," you'll respond. When you deal with enterprise solutions, you still need to contend with existing or new COM+ components. Can they be used within the .NET Framework? Sure they can. The .NET services are generally XML-, SOAP-, and HTTP-based, but this doesn't matter until you're in the physical design phase, so for now, let's just start identifying the services.

The first task is to look at the output from the conceptual design: the use cases, scenarios, and sequence diagrams. This is similar to what you did when you identified the business objects. However, in this step, you don't look for nouns; instead, you look for verbs. A rule of thumb here is that verbs are often services in the solution. Look at it this way: The verbs represent something that the business objects (the nouns) do. For instance, the Customer business object places a Product in the Shopping Basket. The verb places indicates that this might be a service. The Customer object uses the "place" service in order to do something to the selected Product object. Consider the following scenario:

Precondition: A product has been selected.

  1. The customer places the product in the shopping basket.

  2. The customer continues to check out.

  3. The customer accepts the order.

  4. The customer selects a shipping method.

  5. The customer accepts the final order, including the shipping price.

Postcondition: The order is placed in the system.

Using the rule of thumb that services are often verbs, you can identify the following service candidates (they're "candidates" because the verbs won't all represent services in our solution):

  • Places the product in the shopping basket

  • Continues to check out

  • Accepts the order

  • Selects a shipping method

  • Accepts the final order

Look again at the sequence diagram in Figure 2-5. There, you can see that the relationships (represented by arrows) between the solid boxes are service candidates. So when identifying business objects, the solid boxes represent business object candidates, and the relationships between the business object candidates represent service candidates.

Tip

If a relationship exists between two business objects, a service always exists!

So, you end up with a list of service candidates. These service candidates are rather high-level services and will later be split up into additional services once you start talking about user, business, and data services. Yes, you still want to have the Windows DNA approach (which is explained in the next section) in mind, because in most enterprise projects, you can't avoid DNA components (COM+). Finally, remember that a service is something that represents an isolated functionality performing a service or task.

The Windows DNA Approach

The Windows Distributed Internet Applications Architecture (Windows DNA) is the standard for developing n-tier applications on the Windows platform. The philosophy behind Windows DNA is that you split up services into user services, business services, and data services. Figure 2-6 shows the Windows DNA architecture.

Click To expand
Figure 2-6: The Windows DNA architecture
Note

If you want more information about Windows DNA, we can recommend another Apress book: A Programmer's Introduction to Windows DNA, written by Christian Gross, published May 2000 (ISBN: 1-893115-17-8).

The Windows DNA principles are still as sound as they were when they were first introduced. What's changed with .NET is that you now have more choices. You also have fewer design issues if you decide that you need a mix of technologies to best solve your problem with .NET, because you'll still need to rely on existing DNA components (COM+) when building enterprise solutions. Table 2-1 compares the three layers of Windows DNA with the VS .NET architecture

Table 2-1: Windows DNA vs. VS .NET Architecture
Layer | DNA | VS .NET
Presentation | IIS, Win32 | ASP.NET, Web services client (optionally Windows forms)
Business Logic | COM+ | Web services (e.g., BizTalk)
Data | SQL Server 2000 | SQL Server 2000

By implementing Web services or building COM+ components with attention to Windows DNA, you can achieve tremendous advantages in scalability, maintainability, extensibility, and reusability.

Scalability: With isolated services, you can distribute the services to run on different servers. This means that all of your data services can run on a data server, which can be your SQL Server, while all your business logic services run on an application server. This way, you can scale your application just by adding more hardware, and not a single line of code needs to be edited.

Maintainability: What do you do when changes occur, and when should changes be implemented? These questions always arise in software development. With Windows DNA, application maintainability is easier and quicker. The reason for this is that you have an isolated bit of code, and the logic is isolated into reusable services. For example, imagine that you calculate value-added tax (VAT) in your application. If the calculation code is isolated in a service and the VAT percentage changes, you will need to change this in only one place—your VAT calculation service— instead of numerous places in a traditional procedural implementation. Furthermore, the testing process becomes much easier and less time- consuming. After making your changes to the service, you need to test only this one service. If the service passed the test, all your applications using the service should still be running, and you have updated your code in just one place. In the "good old days," a change to a critical program part often forced you to retest the entire application.

Extensibility: The solution can be extended as the business adds specializations to the generic objects via inheritance.

Reusability: When you split your application into services, you get a higher degree of reusability. Imagine that you have an application adding VAT to a product price. If this functionality is built into your ordinary procedural code, it can't be used by other applications unless you cut and paste the code into those other applications. If, however, you've split the logic into services having a VAT calculation service, you can call this service from other applications as well, perhaps with the price as a parameter, and then receive the price including VAT as the return value. That's real reusability. Also, when you develop your services as .NET XML Web services, you don't limit the reuse to desktop applications. Your .NET XML Web services can be accessed from anywhere using XML, SOAP, and HTTP.

Optimizing Business Processes

After you identify the business processes and services, it's time to optimize the findings. Some of these may be beyond the scope of your solution, so they can be eliminated. Some of the business processes, business objects, and business services may not really be processes, objects, and services, so they can be deleted from the list. Other objects, processes, and services may be redundant, and thus they can be merged.

In our example, we've identified the following business object candidates:

  • Customer

  • Order

  • Product

  • Shopping Basket

  • Check-out Point

  • Shipping Price

  • Shipping Method

First, you want to eliminate the items that are out of scope. If the scope for your solution were to develop a service enabling the user to put products in a shopping basket and continue to check out, then order processing would be out of scope. This effectively means that the Order business object candidate could be eliminated from the list, because it isn't within the scope for your specific solution. It doesn't mean that the Order business object candidate isn't relevant; it just means that it would not be developed for your project. In this example, though, we will consider the Order object to be within scope and keep it in our list.

Next, check if all the business object candidates in the list are real business objects. A real business object is an object that has a life of its own and contains information that needs to be persistent in the solution. In the sample list of business object candidates, the Customer object is a real business object. It has a life of its own, meaning that it's not dependent on other objects to be present. It needs to be persistent in the solution, meaning that the Customer object exists throughout the solution's life, regardless of the tasks performed.

An example of a business object candidate that isn't a real business object is the Shopping Basket object. The shopping basket isn't persistent in the solution. It doesn't have a life of its own, and you don't save shopping baskets (well, at least not in this solution). Finally, a shopping basket can't have a life of its own—it alwaysrelates to products and users to be present. The Shopping Basket object is merely a virtual container holding products for the user. The same goes for the Check-out Point business object candidate and the Shipping Price and Shipping Method object candidates. So, now you have the following business object candidates left:

  • Customer

  • Order

  • Product

The next step in the optimizing process is to check if some of the discarded business object candidates are instead properties/attributes for some of the real business objects. The discarded business object candidates are as follows:

  • Shopping Basket

  • Check-out Point

  • Shipping Price

  • Shipping Method

Now you need to check each of the discarded business object candidates to see if it is actually an attribute of one the business object candidates. In order to do this, you need to determine if the name for each of the discarded business object candidates is describing any of the business object candidates. The Shopping Basket object doesn't say anything about any of the business object candidates. Neither does the Check-out Point object. However, the Shipping Method object tells you something about the order. It tells you how the order is shipped. This means that the Shipping Method object is really an attribute of theOrder business object candidate. This also goes for the Shipping Price object; it tells you something about the price of shipping the order, and it is therefore an attribute of the Order business object candidate.

As you might have discovered, the rule of thumb "Identify business objects by looking at the nouns in the scenarios" is only partly correct, because attributes often appear as nouns in the scenarios as well. The business objects will typically be complex and require other nouns (attributes) to fully describe them. These nouns that are attributes are typically atomic (that is, they do not need to be broken down any further themselves).

Optimizing the services list isn't very complicated at this point. You simply remove services that relate to objects that are considered out of scope. That's enoughfor the time being; you'll finalize the services list later. For now, your list of services looks like this:

  • Places product in shopping basket

  • Continues to check out

  • Accepts order

  • Selects shipping method

  • Accepts final order

Identifying Attributes and Relationships

When you reach this step, you've already optimized the lists of business objects and services. The next step is to find the business object attributes and the relationships[15] among the business objects.

First, you need to identify the business object attributes. For each business object, you must ask what description of the object is needed in your solution. This is important, because there's no need to identify a lot of attributes if they aren't needed in your solution. Of course, this attribute identification isn't final. Later on in the design phase, and even in the development phase, you might discover that additional attributes are needed. For our e-commerce application example, the attribute list for the Product business object can look like this:

  • Product Description

  • Product Color

  • Product Size

  • Product Price

The idea of the logical design process is to create a business object model. A business object model shows you how the system will be developed in a logical way. By "logical way," we mean that you're not concerned with how the system is physically implemented. Instead, you focus on creating a model that shows which objects will be part of the solution and how they interact through the services identified. The business object model shows you how the use cases and scenarios, including the corresponding sequence diagrams identified in the conceptual design, will be implemented.

A simple business object model based on the ongoing example might look like the one in Figure 2-7.

Figure 2-7: A simple business object model

Another way of creating a logical business object model is to make a three-tier diagram. A three-tier diagram is sometimes easier to deal with in the physical design step because it builds on the Windows DNA approach with three layers. (But note that the three-tier model is not part of the UML specification, which you'll learn about in Chapter 4.) Before you make the three-tier diagram, it's wise to divide the services list into three separate lists. That's one list for each service layer: presentation, business, and data. If you do this, you'll have an easier job making the first three-tier diagram.

Physical Design

The last step in the MSF design process is physical design. In the physical design step, the focus moves from the project group to the developers. It's now time to dig into the details and plan how the solution will be implemented. The input to this design step is the output from the logical design step.

From the logical design step, you have the business object model(s) and the lists of business objects and services. This output describes exactly what will be implemented, but it is described in a logical way. The job now is to convert these models and descriptions into diagrams and descriptions necessary for the developers to implement the solution. The aim is make the diagrams and descriptions detailed enough to hand them over to the developers so they can start implementing the solution. This is a good rule of thumb to keep in mind. Continue to make the physical design more detailed and more technical until you reach thepoint where the project group feels the developers can take over implementing the solution on the basis of your physical design.

Choosing Technologies

Before you dig into the details and start outlining the technical details of your objects and services, you need to decide which technologies you want to use. There are three reasons why this is important:

Technical details: If you don't know what the technology choices are, you can't outline the technical details on the physical diagrams. If you design a service and you don't know if it's to be implemented as a COM+ service, a Web service, a CORBA service, a Java service, or something entirely different, you simply can't describe in detail parameter types, interfaces, and so on, because these will differ depending on the choice of technology.

Project plan: The choice of technology can have a major impact on the overall project plan. Imagine that the chosen technology will cost $100,000 and the project's budget is $100,000. With a ROI of $50,000/year, the project should be cancelled. If you haven't done the analysis that identifies this and you continue developing regardless, you'll be throwing good money after bad.

Business and design goals: The choice of technology must not only match the demands found in the logical design, it must also match the overall and general requirements from the business as stated in the project plan. What we have in mind here are the business goals and design goals, which you can find more detail about in Chapter 20. One design goal can be "Capitalize on the existing IT investment (Microsoft Windows 2000 Servers, Microsoft SQL Servers, MSF education, Visual Basic, and staff training)." If this is the case, it's out of the question to choose technologies for development that force the customer to invest in new servers and additional education.

In considering your technology candidates, first look at the business requirements, concentrating on the "nonfunctional" requirements that describe how the solution is expected to be used. In contrast to the requirements identified in the conceptual design phase, which focus on the users of the solution, the aim is to identify requirements as seen from the perspective of the business and sponsor. These goals can describe mandatory constraints of the technology choice.

The following sections describe an effective approach to identifying constraints and comparing technology candidates.

Categorizing Constraints

A good guideline is to divide all the identified constraints into categories. This way, you make sure that you address the most important categories. The categories to be considered are as follows:

Usage requirements: Here, you look at the characteristics of the users, or actors as they are called in the conceptual design step. The skills of the users are also important here. Some specific user skills might demand certain physical constraints, such as whether the users are familiar with the Windows platform, and the solution needs to be similar to other applications the users have. This can certainly be an issue that needs to be addressed.

Scalability: You need to know how the solution needs to scale: how many concurrent users the solution has to handle, what the overall number of users is, and how this will change in the future. The pattern of usage is important—1,000 users per hour spread evenly is a very different proposition from 200 users all using the solution in the first five minutes.

Maintainability: You need to identify if there are any demands for maintainability. Identify the number of future changes and the frequency of these changes. Finally, overall maintainability, which includes updates and error corrections, needs to be taken care of, and this can also result in constraints.

Reliability: How reliable does the solution need to be? Is a system crash acceptable and if so, at what level?

Performance: Performance is all about the response time and the overall performance of the system. Is it okay to wait for five seconds for the system to update the database?

Security: You need to determine how secure the solution must be. One issue relating to this is how confidential the data in the system is. Are we talking encrypted data or something else?

Developer knowledge and experience: The developers' knowledge and experience can become constraints. This is relevant when discussing development time, recruitment, development strategy, and so on.

Future visions: How will the solution and the organization evolve in the future? This can have impact on the choice of technology.[16]

Tip

You should check out the MSF Readiness discipline as well. The Readiness discipline is a discipline in the framework. By now, MSF has addressed four disciplines: risk management, readiness management, quality management, and project management. Readiness management has to do with resource readiness planning. Check Web sites and books on MSF for more information.

User expectations for reliability, speed, and security will often be recorded in a Service Level Agreement (SLA).

Creating a Matrix to Compare Technologies

The best way to approach the task of choosing a technology is, based on our experience, to create a matrix in a spreadsheet and plot in the constraints, together with an analysis of technology candidates. First, you need to identify the physicalconstraints for each category and plot them into the matrix. The identified requirements are then plotted into the matrix under the appropriate categories. In Figure 2-8 you can see a simple example of a matrix.

Click To expand
Figure 2-8: A simple matrix for comparing technologies

Figure 2-8 shows how you can use weighted scores in a matrix; this way, you can control which constraints are the most important ones. In the example, we've listed the constraints in column A and the weight in column B. You can see that this is an easy way to do a quick comparison of the technologies. The trick is to have all the constraints for the solution in the matrix. The following are some examples of physical constraints:

The solution must run on the existing Microsoft Windows 2000 Servers. This statement identifies the constraint that the solution must run on Windows 2000 Servers.

The solution must be implemented in three months. This statement identifies another constraint concerning development time. According to this statement, you can't choose the "optimal" development technology if it means that the developers will need five months to develop the solution because they have no knowledge of the "optimal" development technology. This constraint is in the developer knowledge category.

How many users will use the solution and how many concurrent users must the solution handle? How will the number of users evolve over time (future scenario)? The answers to these questions are in the scalability category.

What number of changes are to come and at what frequency? The answers can lead to specific physical constraints. These constraints are in the maintainability category.

Note

Microsoft usually distinguishes between maintainability (how easy is it to fix or work on?) and extensibility (how easy is it to add new functionality?). They normally go together, as good component design achieves both.

Besides these examples and the constraints, there are a number of questions you must always ask. It's impossible to choose the right technologies if you don't.

  • What is the number of users?

  • What is the number of concurrent users?

  • What data storage amount do you need?

  • What response time do you need?

  • What data confidentiality level is required?

  • What solution availability level is required?

Finally, you identify between two and five technology candidates. You identify the candidates through some high-level constraints that can be used as candidate baselines. If you have a constraint stating that the solution must run on a Windows 2000 platform, then the database candidates can be Microsoft SQL Server, Microsoft Access, and Oracle, but not a mainframe relational database management system (RDBMS). Another baseline constraint might state that the solution must be able to handle 1,000 concurrent users performing heavy queries to the database, which effectively eliminates Microsoft Access.

After you've found the technology candidates, you plot them into the columns of the matrix. The task is then to step through each requirement and give each technology candidate a score. The technology candidate with the highest cumulative score is probably the best choice. It's as simple as that!

Modeling the Physical Database

The easiest place to start the physical design is in the data storage section. Two scenarios exist: either you need to create a new database for your solution or you will use an existing database.

If you're going to use an existing database, you should simply diagram the database you're going to use. Be careful. If you've modeled the database before, you should just rely on that model (you don't want to update the database model several places, do you?).

In the logical design step, you identified the object that will be mapped into tables in the physical design step. The tables are just identified in a logical way, meaning that this might not be the way you actually implement them. Your job is to design how the tables will be physically implemented. Imagine that during the logical design step, you identified a table holding customer information. Maybe you left it at that, or maybe you even identified the information needed in the table. This information is to be the columns of the table. The Customer table example can hold the following columns:

  • ID

  • FirstName

  • LastName

  • Address

  • City

  • ZIPCode

  • Type

  • TypeDiscount

If you're going to implement this, you won't place the TypeDiscount in the Customer table. The reason is that if the discount changes for a specific customer, then all the records in the Customer table relating to the customer Type must be changed. This can be a huge change. What happens if a customer belongs to more than just one customer Type? Yes, you might have guessed it: You're dealing with the third normal form (3NF) of the relational database normalization model, which aims to eliminate redundant data attributes such as these.

Without digging too deeply into database normalization, we just want to mention that the 3NF is the most commonly used normal form of relational database design. To comply with the 3NF, the information in your tables must relate to the primary key, the entire primary key, and nothing but the primary key (so help me, Codd![17]). In this case, the Customer table will have the ID column as the primary key, and the TypeDiscount column is related to the Type column and not the primary key.

Note

For more information about normalization, you can refer to the Microsoft Webcast of normalization basics at http://support.microsoft.com/servicedesks/webcasts/wc060600/wc060600.asp?fr=1 . You can find other good database normalization sources at the MSDN Web site (http://www.msdn.microsoft.com), where you can search for "normalization." You can also find an explanation of normalization in the Apress book Database Programming with Visual Basic .NET, Second Edition, written by Carsten Thomsen, published October 2002 (ISBN: 1-59059-032-5).

There is one rule of thumb for database design that you should understand: Normalization isn't always a must-do. Normalization is optimized for data input, but not data output. If you're designing a system with a limited data input, but with a lot of heavy data output, such as a data warehouse solution, normalization is quite often not the right thing to do.

Wait a minute—is this UML? Yes, it is. Database modeling is often done with ER diagrams, but these, too, can be made using the UML notation. Both of these types of diagrams can be created with VEA.

Modeling the Physical .NET Service

The physical design of the .NET services is the most exciting design step for developers, because the design now goes technical. This is where the solution is designed the way it should be implemented. Before you start, you should note that .NET services, or services in general, don't need to be XML-based Internet communication services as the .NET Framework suggests. These services are called XML Web services. The .NET services can be anything, because you defined the services as isolated functionality. This means that the services can be classes, VBScript functions, and so on. The physical service model is created on basis of the three-tier model or logical object model created in the logical design step.

Each service identified during the logical design must now be physically possible to implement. This means that you need to determine which development tool you'll build your solution with and how the interfaces between the services will look. Furthermore, you'll more than likely need to divide some of the services into additional services. The services from the logical design step are only in a logical form, just like the database tables you made. When you move into the physical design step, you must start thinking about the actual implementation. If you're going to implement a service that shows the submitted orders for a customer, you'll have identified services that show submitted orders during the logical design step. You might even have placed this service in the user service layer. Depending on how detailed you've made the logical design, you might even have split up this service into a service that retrieves the data from the database and a service that displays the retrieved data for the customer.

As mentioned, the first step in transforming the logical design into a physical design is to split up the services into parts so each part is 100 percent a user, business, or data service. In the example, you can't really accept that the user service accesses the database directly. Why not? Well, if you want the user service to run on a client machine, which is generally the way it works, you also have the data access functionality on the client machine, which means you can't improve scalability by moving the data service to a dedicated data service machine. Furthermore, if you don't split your services into isolated services, you lose a lot of flexibility and reusability. Imagine that you want another application to display the submitted orders, but you want to display the orders differently than in your application. That effectively rules out the service, because it takes care of displaying the data as well as retrieving it. Had you instead created a data service for retrieving the data, then the other application could use this service to retrieve the data, and another service could display the data in the desired way. That's reuse of aservice, isn't it?

Another important thing to do when you split up your services is to always have a dedicated service for low-level data access and another service to manipulate the data.[18] You can, for example, split a service into three smaller services. This will result in a data service whose only task is to retrieve data from the database and pass the data on to the caller. It will also result in a business service that retrieves the data from the data service. In this case, the business service doesn't make any modifications to the data, but just passes it on. Finally, you'll have a user service that receives the data and displays it in a grid or another type of presentation.

If the business service doesn't do any data manipulation, why not just let the user service communicate directly with the data service? Well, you can do that, but just remember that this is a simple example. Our goal here is to illustrate that it's extremely important in enterprise development to have these data access only services. They're beneficial in many ways. Think of how you handle the products and related stock-keeping units (SKUs, a unique product ID) in your enterprise organization. You probably have an application for managing this, and in many organizations it's rather complicated. Is it easy to adopt changes to the structure? In many organizations, it isn't. But what if you had used service-based development? Would it then be easy to adopt structural changes? Not necessarily. If no pure data access service exists, it means that the business services (or even worse, the user services) themselves perform data access. This means that changes to the structure that affect the way data is fetched must be implemented into all the services interacting with the product-SKU data. This can be a huge job. And what about other services or applications using the affected services? If you instead have a data access service performing the low-level data access (DELETE, SELECT, INSERT, and UPDATE SQL statements), then you will need to change only this one service to reflect the structural changes.

After you test the service and make sure that input and output are as they were before the change, all other services can be changed and work error-free. To make the example more true to real life, imagine that a column name in the product-SKU system changes from SKUId to SKUNo. All SELECT statements used on this table then must change. If you've implemented the data access service, you can simply change the four SQL statements in the service to reflect this change. The old SELECT statement looked like this: SELECT ProductName, SKUid FROM ProductSKU. The new SELECT statement looks like this: SELECT ProductName, SKUNo AS SKUid FROM ProductSKU. Once you've changed the SQL statements, you can test if the service is working and all other applications and services will still work as well.

Interfaces are critical to services. Services need to know how to communicate with other services. Communication is done through interfaces. So, you need to know what the interface looks like and what parameters and parameter types are needed.

In the following example, you can see that the GetProductList method, which is exposed by one of the services, takes an integer value, CategoryId, as an input parameter, and the method then returns a DataSet object:

GetProductList(CategoryId as Integer) As DataSet

Not only do you need to know exactly how to communicate with a specific service, meaning what parameters to pass and what return values to expect, you also need to know how the developers must develop the service. This means that you need to know which technology to use before continuing with the physical design. You need to know how you want to build your services and with which development tools. Otherwise, you can't make the physical design detailed enough for the developers to start coding. For example, if the developers don't know if a service is going to be a Web service, a COM+ service, or even a CORBA service, they can't determine exactly how to develop the service with the right interfaces and data types.

The last thing we'll say about services for now is that dividing them into user, business, and data layers doesn't mean that the services always run on three different machines. In fact, they can all run on a single machine, but the diagramming is still divided into the three layers if you do three-tier modeling.

In enterprise development, using Microsoft development tools, your services will most often be Web services or COM+ components. These kinds of services take advantage of the built-in technologies, such as transaction services, scalability services, and so on. We call these built-in technologies for services as well, because that is exactly what they are. Consider the Microsoft Message Queue functionality, the Microsoft Transaction Server functionality, and the other functionalities exposed to you as services, which you can then choose to use in your own services. Now this is truly service-based development.

Start Sidebar
What If They Don't Want Service-based Development?

In the enterprise projects we've participated in, we used to preach about always creating COM components. Now we generally preach that you should create Web services for exposing your solution functionality. However, we've often experienced that the project team or the sponsor doesn't want service-based development, but instead prefers, say, "simple" ASP or ASP.NET code for running on a single Web server. The reason for this tends to be a lack of developer skills. After trying to explain the risks involved in doing so, we always go for the same compromise: Develop the solution in a way that makes it easy to change over to a service-based approach later on. In one project, we achieved this by creating all the services as ASP code placed in individual include files. This way, we can later convert the include files to COM+ components and replace the include statements with COM+ instantiation, without needing to redevelop the entire solution. That's certainly one valid approach to handling these kinds of constraints.

End Sidebar

Optimizing System Processes

Another key point about the design process is that you get the chance to discover irrational ways of doing things or you see some areas or processes that can be optimized. You can then change your design and develop a better solution. You might even save some development time, either because something can be done smarter or because you've discovered the needed changes before any development has taken place. Development efforts will be wasted in this case, which is exactly what we discussed earlier in this chapter. The benefit of designing is that you don't begin the costly development phase before you have the final design. Good design is not having to say you're sorry during the coding. It doesn't need to be perfect; you can't second-guess everything. It does, however, need to have ferreted out, as a minimum, all the first-order design issues and established a pattern of design to which subsequent lower order decisions can conform.

You have several ways of optimizing your design:

Testing user scenarios: This is an extremely important task. Many processes have been optimized after you've stepped through the scenarios with the users. By doing this, many nonoptimal ways of doing things will be uncovered, or ideas for optimizing certain tasks will surface. This task also has another purpose: making your users sign off the scenarios you step through. As you'll learn in Chapter 20, the developers will never be those testing the solution.[19]

Prototyping: Prototyping the solution has the benefit of presenting to users how the application looks and feels. The disadvantage is that users tend to focus on the layout instead of the functionality. However, prototypes can certainly reveal nonoptimal design. A problem with prototypes tends to be the challenge of explaining to the customer that the prototype is just a wafer-thin facade and by no means a nearly complete solution.

Analyzing similarities in development blocks: By analyzing your logical model as well as physical models, you might discover some areas where the functionality is almost identical and therefore a candidate for merger. Imagine that your solution will have three individual administration areas: one for administrating picture download, one for administrating document download, and one for administrating PowerPoint file download. You might have designed your solution with three distinct services and presentation pages for doing this. Surely, you can design this in such a way that you have only one area of administration with a parameter identifying which area is being administered. If it is possible, you've optimized the development process and made future changes easier.

Observing a live audience: If you've created a functional prototype ready for use in a live situation, you can perform a live audience observation. You place some target users in a room where you can watch them and make them use the solution in a real-life environment situation. You then observe their work processes to see where they have difficulties or where their work speed decreases. Afterward, you should ask for the users' opinions and experiences.[20]

Deploying the Services

The last step in the physical modeling phase is to decide how to install the physically developed services by determining on which servers they will run. You'll also determine if there is any installation information that needs to be described. You prepare this information by making deployment diagrams. Deployment diagrams are discussed in Chapter 5. The important thing to remember is that besides the physical models, additional information must be known in order to install the services, such as transactional demands, security level, and so on.

[10]For example, you will have a problem if you plan on developing a solution using Microsoft Foundation Classes (MFC) for your C++ project before you realize the requirements for the solution to be able to run on Linux as well.

[11]There are other development frameworks and project methods that provide you with a design process and guidelines, such as the Rational Unified Process (RUP) (see http://www-306.ibm.com/software/awdtools/rup/ for more information). However, in this book, we focus on MSF and UML because we believe these are the most appropriate for VS .NET solutions.

[12]This is David C. Vladeck's description.

[13] Process refers to the functionality of the final system. A process (when we talk about UML diagramming) is a collection of tasks forming the functionality.

[14]NET services refers to all kinds of services within the .NET environment. For example, .NET services can be Web services, COM+ components, Windows services, code snippets, and so on.

[15]Compared to a database model, attributes are fields; relationships basically represent the same meaning.

[16]Many programs have a versioning history. Just think of Microsoft Windows 3.1, 95, 98, 2000, XP, and 2003.

[17]Edgar F. Codd originated the relational approach to database management in the 1970s.

[18]Keep in mind that data services are not the same as the database server. Data services are code snippets handling the data access for you and are placed in the data service layer in the three-tier model.

[19]Of course, unit testing is excluded from this rule.

[20]You should do this via video, because there is a temptation to prompt the users ("Just press that key to route here. . .") if you are present.


Planning Your Solution

What's the difference between design and planning? Design is the process you've been through so far in this chapter. Basically, we've outlined what the design, functionality, and look and feel of the solution will be. You can consider design a plan for what you'll build. What you're missing is a plan for how to perform the tasks determined in the design process. This is the planning step.

The Planning Process

The following are the key points in the planning process:

  • Scheduling

  • Setting milestones

  • Establishing a communication plan

  • Creating an iteration plan

  • Test planning

In the following sections, we'll briefly outline these key points. The output of the planning process is a functional specification and a project plan. These areas are described in detail in Chapter 20.

Scheduling

The first step in the planning process is to make a schedule for when the development will take place. You need to determine the start date, the finish date, and the resources involved. You also need to make a project budget, not only for the development resources, but also for all expenses in the project as well as licenses, hardware investments, software investments, education, and so on. A rule of thumb is that the schedule should be expressed as both hours and working days. This way, you have the information for both the resources and the calendar days.

Milestones

Milestones are very important to incorporate in your planning. Milestones help you communicate to the stakeholders exactly where the project process is at any given point of time. Milestones represent completed work and are therefore used as an interim status point in your project process. There are four principle milestones defined in MSF, with interim ones added as necessary. The five principle milestones are as follows (you'll learn more about these milestones in Chapter 20):

  • Vision scope approved

  • Project plan approved

  • Scope complete

  • Release readiness approved

  • Deployment complete

Communication Plan

After a signed-off functional specification and budget, the communication plan is the most important thing to develop. In the communication plan, you determine who has which competencies and what the communication hierarchy is. Often in the communication plan, which is part of the project plan or an individual document, we've stated that the only person the customer can communicate with is the product manager (customer project manager). The customer isn't allowed to call the developers directly to make agreements without involving the product manager.This can certainly eliminate some of the confusion from the process. You can also in this section determine in what format (written or oral form[21]) change requests are accepted. Another important issue is to determine the competencies. Who can sign off on project documents? Is it the customer or the product manager pointed out by the customer? You need to determine these issues in advance to avoid confusion and misunderstandings.

Iteration Plan

You need to create an iteration plan. Enterprise software development needs to be performed in iterations to stay focused and make the process simple and fast moving. At an early stage, you should determine the iterations performed, the resources involved, and the schedule involved. An important rule for creating iteration plans is that the first iteration should include the core functionality needed, and the second iteration should include the most important features, starting with the high-risk features. This way, the overall project risk will decrease during the project process. Remember that the tradeoff strategy might eliminate features later on, so you should also start with the core features when you create the iteration plan. Among the core features, you should prioritize feature development according to risk.

Testing Plan

Planning the testing procedure is the final key issue. You should determine the start and end dates for the testing, and how errors are reported and addressed. It's very important that the customers are informed about how they will participate, including the dates and required effort. You should also determine the impact if these demands are not met. A customer that doesn't perform a required test can have an impact that may easily result in project delay.

Documenting Your Solution

Of course, it's important to document the solution after the solution has been built. But you should start the documentation much earlier. You should start documenting the solution in the planning phase while you design it by documenting the use cases and the scenarios.

If you use UML in all the design steps and you make sure to update all the models and diagrams when changes occur, you have complete documentation of the solution when the solution is built. That's nice, isn't it? This means no more documentation tasks after the solution is built. If you update the models and diagrams while you're developing—if, say in the physical design step, you change a service's functionality—all changes must be reflected in the related diagrams and models, from object diagrams to use case diagrams.

Finally, your documentation should be electronically archived and easy to access. Documentation printed out and placed on a shelf tends never to be updated, so it will never be current.

[21]We recommend written form for change requests. If you choose oral form, make sure to document important decisions in a project diary and confirm it by e-mail.


Summary

This chapter started with the quote, "If you are failing to plan, you are planning to fail," which is exactly the message of this chapter. This chapter introduced you to planning and design. You looked at design from a broad perspective, and you learned why design is important in software development.

You were also introduced to the design steps as advocated by the MSF: conceptual design, logical design, and physical design. In the conceptual design step, you gather the user requirements and describe those using UML in a way that's understandable to the user. In the logical design step, the focus moves from the user to the project team. Here, you design the solution in a logical way, so the whole project group has a clear understanding of what's going to be developed. Finally, in the physical design step, you look at the project from the developers' point of view. At this stage, you design how the solution will be developed and implemented in a technical way.

You also saw the importance of making the right technology choices at an early stage in the physical design. You were briefly introduced to how the solution isplanned after the design has been made and how the documentation of the solution is handled.

The intention of this chapter was to introduce you to the concepts of planning and design and give you a basis for understanding the design process. In Chapter 20, we elaborate on the MSF, and in Chapters 4 and 5, we delve into UML in detail.

The next chapter will provide you with a brief introduction to UML.


Part ll: UML

Chapter List

Chapter 3: Getting to Know the Unified Modeling Language
Chapter 4: Examining the UML Models: Behavioral Models
Chapter 5: Examining the UML Models: Static Models
Chapter 6: Planning a VB .NET or C# Project
Chapter 7: Maintaining the UML Documentation


Chapter 3: Getting to Know the Unified Modeling Language

Overview

In this chapter, we introduce you to the concepts of the Unified Modeling Language(UML). Our intention with this chapter is to give you a clear understanding of what UML really is, its historical background, and how it's used. UML is a modeling language, meaning that it's a language or concept for how to model and describe real-world objects and how they interact. The difference between UML and a normal programming language is that UML is a graphical language that uses graphics to describe objects. UML is also used to describe design patterns,[1] which you can apply to your .NET environment.

The focus of this chapter is on UML history and basics. We'll introduce the three basic types of models used with UML: functionality diagrams, behavior diagrams, and implementation diagrams. In the coming chapters, we'll drill down into the UML notation and show you how to use the various models and objects.

[1] Design patterns are language-independent guidelines for how to solve a specific programmatic task.


Introducing UML

UML is a language. Calling UML a language can seem strange at first, but the term is quite a good description of what UML really is. It's basically a standardized way of describing, visualizing, documenting, and specifying the parts that form a software solution. Just like any spoken language, such as English, UML has ways of describing the things that surround us.

As an example, you can use the English language to describe a car. You can use English words and punctuation to describe the car's functionality and operating instructions. In comparison, you can use UML to describe a Car object. When you use UML instead of English to describe the car, the ways you can express yourself are different. When you use UML, you don't use English words and punctuation, but instead you use graphical UML images and description methods to describe the car.

The normal English description of a car might include information about the color, length, width, height, and engine, as well as a description of the functions, such as accelerate, brake, and clutch. The description can look like this:

The car has several characteristics that make it possible to distinguish between different versions of a car. A car is described by its color and other physical attributes such as height, length, width, and engine type. Finally, the car has some functionality that the driver can control—for example, accelerate, brake, and clutch.

As you might have guessed, this description can be rather long, and the important information can be rather hard to pick out. Furthermore, readers of this description whose native tongue isn't English might have difficulty understanding it.

UML takes a different approach to describing a car. Figure 3-1 shows the Car object described using the UML notation for a class (object).

Figure 3-1: The Car object expressed using UML

As you can see from Figure 3-1, the UML language can simplify the written description quite a bit. "A picture is worth a thousand words," it's often said. This is true, especially when the picture gets more complicated. A good example is a database model that shows tables, columns, rows, constraints, relationships, and so on. If you tried to convey a database model in written English, you would end up with several pages of information, and it would be difficult to quickly pick out a particular aspect. But as you can see from the illustration of the database model in Figure 3-2, the graphical representation of the database model is much clearer.

Click To expand
Figure 3-2: A database model

When you look at the database model, everything becomes clear to you, assuming you "speak" the language of the database models. You know that a key symbol next to a field in a table means that the field is a primary key, that a primary key is always unique,[2] and that it can be used to look up records in the database. We've already written a couple of lines of text explaining this, and we might even have missed some valuable information in our description. In Figure 3-2, we can simply convey the same information by showing a key symbol next to a table field.

The same idea applies to UML. When you know the UML language, there's no easier way of describing the parts that form a software solution. However, the real strength of UML is that it's a standardized language used throughout industries, no matter which development language is targeted. With UML, you're using the same language as all other analysts.

[2]In most database management systems, primary keys must be unique.


The History of UML

As the word unified suggests, the UML language is a union of previously independent modeling languages. UML was invented in 1995 by Grady Booch, James Rumbaugh, and Ivar Jacobson. These three guys, widely known as "the three amigos," had individually created their own modeling languages. Around 1995, they decided to stop competing with each other and make the world a better place (for software developers, architects, and analysts) by uniting the three individual modeling languages into one by taking the best aspects from each language, thus creating the de facto modeling language in the software development industry. Besides this, they also joined a company, Rational Software Corporation (Rational),[3] which develops tools and software for making software design that is built on the new unified modeling language.

Rational's success is mostly due to its Rational Rose product, which has become the leading UML tool in the software industry. Rational has, from the start, capitalized on the UML language by making Rational Rose one of the best-selling UML products to date. The developers have succeeded in making Rational Rose evolve over the years with new features—for example, integration with programming languages such as Visual Basic, and, more recently, with VS .NET in IBM Rational's XDE product. (Chapter 18 explains in detail the concept of Rational XDE, which is the newest UML product from IBM Rational.)

Now let's look at the three modeling languages that were the forerunners of UML.

James Rumbaugh's OMT

American James Rumbaugh participated in inventing an early modeling language called Object Modeling Technique (OMT). Rumbaugh's goal was to make a modeling language that could be used to model object-oriented software solutions.

Object-oriented software builds on the concept that everything in the solution acts as objects. These objects incorporate both the data structure and the behavior of the object. This is slightly different from conventional programming,where the connection between an object and its behavior is vague. As an example, the previous UML description of a car shown in Figure 3-1 is an object in the object-oriented world. Notice that the behavior is incorporated into the object (Accelerate, Brake, and Clutch) and that the data structure and its attributes are also incorporated into the object. In conventional programming, the connection between the object and its data structure and behavior isn't as tight. For instance, the Car object might exist (say, in a table in a database), but the car's behavior (the code) is somewhere else. It's certainly not integrated with the Car object in the database. The car's behaviors simply exist as external behaviors that can be linked to the car.

Other characteristics of object-oriented software are the use of inheritance and polymorphism. Inheritance means that an object can inherit behaviors and data from other objects. The Car object can inherit from the Vehicle object and thereby inherit the behavior of a vehicle, such as the signal (horn). Polymorphismrelates to an object having several versions. Again, with the Car object as an example, if the car is of the type Cabin, it will additionally have the Windshield behavior, whereas a car of the type Racing won't have this behavior.

Rumbaugh took this object-oriented approach, and his OMT modeling language was created for designing object-oriented software solutions. OMT consists of the following steps:

  • Analysis

  • System design

  • Object design

  • Implementation

OMT also consists of the following models, which are used in the steps of analysis, system design, object design, and implementation:

Object model: This is a description of the static structure of the objects and their relationships, meaning that the model shows the various objects with relations to each other. In some ways, this is like a database model in that it shows what the system is capable of doing.

Dynamic model: This model describes how the behaviors of the objects in the system change over time. Dynamic models contain state diagrams. As its name indicates, the dynamic model shows the various states that an object can be in. It also shows the transitions between states, which are called events. Using the Car object example, one state can be Moving, and another state can be Stopped. Then we need an event to get from Moving to Stopped, and this is the Brake event.

Functional model: This model describes the data values within the system. It contains data flow diagrams. A data flow diagram is a special type of network diagram in which the processes are expressed through nodes. The links between nodes are drawn using arrows representing the data flows and dependencies.

Grady Booch's Booch Development Method

American Grady Booch is the inventor of the Booch Development Method, which he developed in the 1980s. This is also an object-oriented software solution development method. It's used to analyze, model, and document system requirements. Itincorporates analysis concepts such as associations, keys, and constraints from the OMT methodology.

The Booch method focuses on the analysis and design phases of object-oriented development. Critics point out that one of the difficulties of the Booch method is its heavy use of different symbols. It's true that Booch defines a lot of symbols to document almost every design decision. However, this is certainly one of its strengths—if the symbols are selected and used only when appropriate. The Booch method contains the following parts:

  • Logical modeling

  • Physical modeling

In the logical modeling part, Booch focuses on modeling the requirements in a logical way, without thinking about how the objects must be implemented in the final software solution. Imagine the need for a table with order information. In a logical model, this order information won't be modeled using normalization. In a physical model, however, this will be the case, because the physical model focuses on how the information will be implemented.

  • In general, Booch uses the following ways of designing:

  • Object diagram

  • State transition diagram

  • Interaction diagram

The object diagram and the state transition diagram have the same look and feel as those described in the OMT section. However, the notation is slightly different (remember that Booch is much keener on symbols for almost every occasion).

The interaction diagram shows how objects interact with each other. These diagrams are often used to describe the sequence of tasks that objects perform in relation to each other. Imagine, for instance, a Car object that interacts with a Driver object. First, the driver performs the task Accelerate, which makes the car move forward. Second, the user can perform the task Brake in order to make the car stop. Notice that this is the sequence that can take place, meaning that the car in our simple example can't be stopped before it is moving. This also means that this kind of interaction diagram is time-based, because tasks and interactions are time-dependent; the car must be moving before it can be stopped, and this happens over time. Another interaction diagram, the collaboration diagram in UML, is taken from the Booch methods. This diagram shows the interaction from the flow of information perspective, and it's not time-based.

Ivar Jacobson's OOSE Method

Swede Ivar Jacobson is widely regarded as one of the world's leading specialists in system development and object-oriented development. He worked for the Swedish telecommunications company Ericsson AB in the 1970s, and, through his work at Ericsson, he participated in developing the principles for object-oriented development. Later, Jacobson founded the company Objectory AB in Sweden. He also developed some of his principles into the method Object-Oriented Software Engineering (OOSE), a truly object-oriented software method. This method includes many of the principles as described in the OMT method. What makes OOSE stand out is the use case–driven approach that Ivar Jacobson incorporated in his method.

The concept of use cases was a milestone in designing software solutions. Use cases provide the missing link between requirements, development, and customer acceptance. Use cases are processes containing both requirements in a written form and in a sequential form. This allows the use case to be understood by users and other stakeholders, as well as tested systematically and used as a development structure. This has proven extremely effective in real-world software development.

Ivar Jacobson's approach to software design is in the analysis of how the solution will actually be used and the way the user's sequences are constructed. However, he also includes conceptual construction and application constructionin his OOSE method.

[3]Today, Rational is fully owned by IBM.


Going Public with OMG

The Object Management Group, or OMG (http://www.omg.org), is an independent, nonprofit organization whose goal it is to develop, maintain, and adopt standards and specifications for the software industry. As of the beginning of 2001, the consortium included about 800 members, and its board included companies such as IBM, Oracle, and Sun Microsystems, among others.

In 1997, Rational gave the rights to the UML language (version 1.1) to the OMG organization so that UML could serve as a publicly available standard. Since then, an OMG committee adopted changes to the UML standard and issued UML version 1.3 in 1998. The current version is UML 1.4 and version 2.0 is in progress. Version 2.0 is expected to be released in 2004. UML has been surprisingly stable over the years; for instance, the latest version (2.0) presents virtually nothing different to the regular user (it has extensions that principally benefit CASE tool manufacturers).

Because UML is a public standard, any company can support it in the company's products. Microsoft, for example, supports UML in Visio, BizTalk Server, and, of course, VSEA.


Using UML

So, where and for what can this apparently great langua ge be used? The spontaneous answer is "Everywhere, for everything!"

First of all, the UML language is excellent for designing a software solution, all the way from user requirements through the design of the solution to the physical implementation.

UML starts with focusing on the user, including the user requirements and how the user interacts with tasks and objects in order to perform the desired work. Notice that it's not tables and software we discuss here, because it's the user and the interactions that are important at this stage. Together with the UML capabilities of structuring and documenting the software specifics, UML is actually excellent for analyzing and describing a lot of things. Examples of areas in which UML can be used are as follows:

  • Workflow in an organization

  • Business analysis

  • User description

  • Database design

  • Object design

  • Components (such as COM+ components)

  • Deployment (domains and servers)

  • GUI design

The list obviously isn't comprehensive, but we're sure you know where this is going. Now you might be wondering if UML is designed for the Microsoft environment or the UNIX environment. The answer is both! Actually, because UML is a model and not an implementation, it's designed for all kinds of environments.

UML is programming language-independent in all aspects of the design, though at some point you'll need to make decisions in your UML models that reflect your technical and physical choices. This is the second very strong characteristic of UML. Not only does it mean that all developers—whether they program in C++, Visual Basic, Oracle, Java, or any other language—can use UML, but it also means that business analysts and technical architects can start analyzing and designing solutions without needing to choose a technical platform before all requirements, current states, future states, interactions, and constraints are known. This fact can easily be the turning point between project failure and project success.

Another feature that makes UML successful is the way it's constructed. UML is made up of graphical symbols that are understandable by developers, analysts, customers, users, and other stakeholders. This is a critical point: Too many software designs have gone wrong because the developers communicated in a high-tech language that the users and customers didn't understand, and the users and customers had difficulty expressing their needs to the developers. UML bridges this communication gap because it uses graphical symbols and descriptions that make it possible for users, customers, developers, and project members to speak the same language.

Finally, the fact that UML has become an industry standard through the OMG organization makes it used almost everywhere. So, using UML increases the chances that employees from other companies, trading partners, and other industries can use and understand your developed descriptions and documentation.


Taking a Look at UML Notation

In this section, we describe UML notation and the way UML is constructed. You should consider this section a brief introduction to what the language of UML looks like. UML, UML notation, and the various models will be described in detail in Chapters 4 and 5.

From a high-level perspective, UML consists of a set of models used to describe and design the various parts of a software solution. Some models have their strength in the early phases of a software design, such as when the project group members are talking to the users in order to gather the user requirements and expectations; other models have their strength in describing the physical software components and are designed to be used by the developers.

The models have one thing in common, though: To design and describe a software solution, no single model is enough! No single model is enough for describing a problem or designing the solution; you always need a collection of models. As you might expect, the question about which models to use is frequently asked by designers who are new to UML. This question always receives a very vague answer, because, unfortunately, the answer is that it depends. It depends on the complexity of the solution and the characteristics of the stakeholders. A solution in which the problem is simple and known, such as the creation of a software solution that shows a single Web page (ASP) with information about the opening hours for the canteen, might not include as many models and as much detail in those models as a software solution that calculates the annual tax payment for any individual or group. We discuss when to use which model in the case studies in this book. The rule of thumb is to make the number of models and level of detail sufficient for all stakeholders to deal with the solution.

The models contained in UML are listed in Table 3-1. We've divided them into three categories: functionality, behavior, and implementation. The functionality category contains the models used to gather requirements and describe functionality. The behavior category contains the models used for describing the behavior of the objects and users of the solution. Finally, the implementation category contains models used for the physical implementation of the functionality and behavior of the solution.

Table 3-1: UML Models
Category | Models
Functionality | Use case diagrams
 | Class diagrams
Behavior | Interaction diagrams: sequence diagrams and collaboration diagrams
 | Statechart diagrams
 | Activity diagrams
Implementation | Component diagrams
 | Deployment diagrams

In the following sections, we present more detailed descriptions of these models.

Functionality Diagrams

The functionality diagrams model the functionality of the solution. In other words, if you want to know what your solution can do, look at the functionality diagrams. The functionality diagrams are the use case diagram and the class diagram. By looking at these diagrams, you'll know exactly what the solution does and how it's developed. Sequence diagrams also show the functionality, but we've put sequence diagrams under the behavior category because they are more behavior-oriented.

Use Case Diagrams

The use case model is usually the first to be made. It's used for gathering user requirements. A use case diagram is the solution viewed from the users' perspective. It's important to talk about the solution at a high level and in a language that users can understand. Talking about triggers, database constraints, and the like is prohibited at this stage. The use case model consists of actors and use cases, and relationships between them.

The actor[4] is someone or something that interacts with the system. The actor either receives information from the solution or delivers information to the system. The notation is a stick figure, as shown in Figure 3-3. The actor very often represents a human being, such as a user, but it can also represent another IT system. For instance, an Enterprise Resource Planning (ERP) system can receive data from an e-commerce solution, which means the ERP system is an actor to the e-commerce solution. An example of a human actor could be a customer who withdraws money from an automated teller machine (ATM). The customer here is an actor relating to the ATM system.

Figure 3-3: An actor

A use case is a process. The notation for a use case is an oval. You can see a use case in Figure 3-4. In this case, it's the process of placing an order. The use case includes a sequence of tasks in order to perform the placement of an order.

Figure 3-4: A process

Figure 3-5 shows a very simple example of a use case diagram. In this diagram, arelationship has been added between the actor (theCustomer) and the use case (Place Order), indicating that the customer interacts with this process; the customer starts the process of placing an order. This can be through clicking a Buy button in the e-commerce solution.

Click To expand
Figure 3-5: Simple use case diagram

Class Diagram

The class diagram is used during the gathering requirements phase. It raises questions as to what can happen and also verifies that the system really can do what it is being asked to do. Class diagrams are seen from the project team and developers' perspectives.

In class diagrams, the logical and physical existence and relationships of the objects in the solution are diagrammed. This means that the classes identified from the use case diagrams are modeled. In our example, the candidate objects would include Customer and Order. So, in the class diagram, you would model the classes Customer and Order. These might be traditional object-oriented classes, or they could be classes that are not object-oriented, such as ASP pages, database tables, or COM+ components.

The notation for a UML class is a rectangle, as shown in Figure 3-6. In Figure 3-6, you can also see that the class has some attributes (CustomerID, Date, and so on) and some methods (New, PlaceOrder, and Delete).

Figure 3-6: A UML class

In class diagrams, classes can have relationships with each other. For instance, a Customer can place zero or many Orders in our system. The notation for a relationship is a solid line, as shown in Figure 3-7.

Click To expand
Figure 3-7: A simple class diagram

Behavior Diagrams

Behavior diagrams describe how the solution behaves or interacts. This type of diagram models what happens inside the solution. Only by knowing this can youdevelop the solution.

Interaction Diagrams

UML has two types of interaction diagrams: sequence diagrams and collaboration diagrams. The difference between the two types of diagrams is that sequence diagrams are time-based and show tasks as they occur over time in chronological order, whereas collaboration diagrams show how tasks and information (objects) interact with each other. In collaboration diagrams, time is shown in encoded form and is not as easy to pick out. Aside from this fundamental difference, both diagrams are used for showing how the objects and users interact with each other in order to perform a task.

Figures 3-8 shows a sequence diagram indicating the interactions performed for a customer to place an order. Notice that another object has been added. To place an order, the customer must first place an item in the shopping basket. Here, you can see that the actor is a stick figure and that the objects are solid boxes. The interactions or tasks performed are shown as solid lines with an arrow indicating the direction of the interaction.

Click To expand
Figure 3-8: A sequence diagram

The interactions in Figure 3-8 are shown in a sequential order, meaning that "Place item in shopping basket" must occur before the placement of an order can happen.

Figure 3-9 shows the same interaction as Figure 3-8, but this time it's a collaboration diagram. This type of diagram better shows which objects interact with which other objects. It shows less clearly the order in which these interactions take place.

Click To expand
Figure 3-9: A collaboration diagram
Start Sidebar
Choosing the Right Interaction Diagram

When you're new to UML, it can be hard to remember which interaction diagram to use, but fortunately there's an easy way to get around this problem. As you would expect, the diagrams are very appropriately named. The sequence diagram describes how interactions are performed in sequence, so it's time-based. The collaboration diagram shows how information and tasks collaborate, with less emphasis on time. More often than not, you'll be using both types of diagrams, but use this little trick when you need to model interaction:

If Time-based Then
 Sequence diagram
Else '(interested in the organizational aspects)
 Collaboration diagram
End If
End Sidebar

Statechart Diagrams

You use statechart diagrams to show the lifetime of an object when you design object-oriented solutions. In Figure 3-10, you can see a simple statechart diagram showing the Car object. You can see the states the Car object can be in: Started, Moving, and Stopped. You can also see the transitions from one state to another. You can see that Accelerate on the Car transitions it from the state Started to the state Moving. These statechart diagrams are useful when designing object-oriented software for determining an object's lifetime and life cycle.

Click To expand
Figure 3-10: A statechart diagram

The notation is a solid box showing the state and solid arrows showing the transitions. Furthermore, a solid circle indicates a starting point, and a solid circle with a surrounding circle indicates a stopping point.

Note

Statechart diagrams are used solely for showing the various states an object can be in and how it transitions from one state to another. In other words, the lifetime of an object is expressed using a statechart diagram.

Activity Diagrams

Activity diagrams can seem confusing at first. They are simply a way of describingthe workflow and who carries out the work, just like the popular data flow diagrams. In fact, you can regard an activity diagram as a kind of data flow diagram.

As you can see from Figure 3-11, the notation used in an activity diagram is a lot like the notation used in a statechart diagram. In an activity diagram, activities areshown as elongated ovals, and states are displayed as boxes with rounded corners. An activity is, as the word suggests, an act that is performed, such as validating an order. A state expresses the state an object can be in; for example, when the validation of an order has been performed, the order is in the Validated Order state. Interesting elements of the activity diagram are the swimlanes, which are represented by vertical lines. By using swimlanes, you have a general view of the various actors/departments in the system and which tasks they perform. Furthermore, you can see where there are an unnecessary number of actors participating or frequent switches between the lanes, both of which can lead to errors and delays. This analysis can help streamline the business process.

Click To expand
Figure 3-11: An activity diagram

Activity diagrams are very useful for getting an overview of the system and the workflow, and they are sometimes used in process modeling.

Implementation Diagrams

Implementation diagrams outline how the solution should be packaged and implemented. They're very helpful for implementation and recovery of the solution.

Component Diagrams

Component diagrams are, as the name suggests, a way of modeling the actual physical components in the solution. Component diagrams can illustrate source-code components, COM+ components, and other binary components and executables. Component diagrams also show the interfaces of the components. Interfaces are the means through which a component can communicate. For instance, the interface for a car is the dashboard and pedals. You can "communicate" with your car through this interface. The Order component can have a method for deleting orders, and the interface specifies that an order ID is needed to perform this action. This means that for the Order object to delete an order, you'll need to pass the order ID for the order you want to delete.

Component diagrams are used to design the actual implementation of the solution components. Figure 3-12 shows the notation of a component (it can be a COM+ component). Interfaces and relations between components can be applied. This way, you can specify how a component calls another component and through which interfaces it will be called. In Figure 3-12, you can see that the Order component is dependent on the E-mail component because the Order component uses this component to send out e-mail messages. You can also see the interface on the E-mail component.

Click To expand
Figure 3-12: A component diagram

Deployment Diagrams

Deployment diagrams show how the solution will be deployed and consist of the processors, devices, and connectors. The processors are hardware items that canexecute components. Devices are hardware devices without the capability to execute components such as modems and printers. Connectors are the relationships between processors and devices.

Deployment diagrams are used for describing which physical machines the components are run on and how the solution interacts with hardware. You will notice the multiplicities on the diagram—the deployment diagram allows you to specify how many of each node type the solution will contain.

The notation is a box showing the physical parts. As you can see from Figure 3-13, the diagram focuses on the physical instances (nodes). For each node, you'll describe which components are running on it.

Click To expand
Figure 3-13: A simple deployment diagram

[4]The actor refers to a role in the solution. For example, if your solution is used by a customer and an employee in exactly the same way, you don't have two actors, but just one, because you just need to illustrate the role.


Summary

In this chapter, we introduced you to UML. UML was invented by "the three amigos," James Rumbaugh, Grady Booch, and Ivar Jacobson, in 1995 when they decided to unite their individual methods (OMT, Booch Development Method, and OOSE) and join Rational Software Corporation. UML was adopted as a public de facto standard by the OMG organization in 1997.

UML is a largely graphical language that is used for describing, documenting, designing, and structuring software solutions. The strength of UML lies in providing the users, developers, analysts, customers, and other stakeholders in the software development process with a common language that all parties can understand and communicate through. Furthermore, UML is programming language-independent, which makes it widely used and gives the project team the advantage of not needing to choose technology before the requirements, workflow, and constraints have been analyzed, described, and agreed upon.

This chapter provided a brief overview of UML's fundamental notation and models. In the following two chapters, you'll get to know the details of the various UML models supported by Visio, which is UML 1.2-compliant.

In the next chapter, you'll learn about the dynamic UML diagrams in detail. Chapter 5 provides details on the static diagrams.


Chapter 4: Examining the UML Models: Behavioral Models

Overview

In this chapter and the next, we'll introduce you to the various UML models that you can create in VEA 2003. We'll show you how to create the UML models in VEA and provide you with a description of each model, along with tips for when to use it.

In this chapter, we'll concentrate on the contents of the model, focusing on how to create the models from a UML point of view. Our intention isn't to provide you with a complete guide on how to use Visio or a complete guide to UML. The goal is to introduce you to the models and elements you'll need when developing enterprise solutions.

VEA supports the eight models included in UML version 1.2 (http://www.omg.org/uml). Generally, the eight UML models can be divided into two categories:

  • Behavioral (or dynamic) models, which include use case diagrams, sequence diagrams, collaboration diagrams, statechart diagrams, and activity diagrams

  • Static models, which include static structure diagrams, component diagrams, and deployment diagrams

You use the behavioral models to document and specify what goes on in your solution; they describe the flow of operations and the events that take place. You use the static models to document and specify the static structure of your solution. You can compare this to building a house, where the static structure is the walls, floors, doors, and so on. The behavioral models would describe what goes on in the house—for example, the traffic through the rooms and so on.

VEA and IBM Rational XDE currently don't support code generation from behavioral diagrams;
[1] This doesn't seem likely to change in the near future. you can generate code only from a static structure diagram (a class diagram).

In this chapter, we'll concentrate on the behavioral models. The behavioral models are usually the first diagrams to be created, because you need to capture the requirements and the flows through the system before you can develop the solution architecture.

Statechart diagrams are created in order to model an object's life cycle. You do this by specifying which states your object can be in and which transitions, caused by outside stimuli, make the object transform from one state to another. Statechart diagrams are related to a class or a use case, which also means it's possible to base a statechart diagram on a use case. Basically, you can base a statechart diagram on almost any UML element, but in general, it's only done for some classes (those with interesting behavior). Because of this, we'll cover statechart diagrams together with class diagrams in the next chapter.


Use Case Diagrams

As you learned in previous chapters, use case diagrams are used for capturing user requirements. They are the first diagrams to be created. Why is this so? Well, it's because the use case diagrams describe the user requirements in a high-level, nontechnical manner. This conceptual design is crucial to the project's success. As you learned in Chapter 2, it's important to be confident that you know about the requirements that are likely to affect your choices before you decide on whichtechnologies to use. The high-level nature of use case diagrams is excellent for seeing the project scope. These diagrams become the basis for the detailed models created later on as the project evolves.

Another use case diagram strength is that it uses plain text and simple drawings,without using any technical terms. As a result, use case diagrams are understandable to a broad audience.

  • Use case diagrams consist of the following basic items:

  • Actors

  • Relationships

  • Processes

  • Packages

  • System boundaries

The following sections describe each of these elements.

Actors

An actor is someone or something that interacts with your system. By interacts, we mean that the actor either receives information from or delivers information to your system. With this in mind, actors can be a person as well as a thing, such as another application. For example, the actor could be an accounting system that receives information from your solution. The notation for an UML actor is a stick figure, as shown in Figure 4-1.

Figure 4-1: The actor notation is a stick figure.
Note

The stick figure notation for an actor is the most common and the "official" notation. However, according to the UML specification, an actor can also be a rectangle with the Actor stereotype. This notation is similar to the notation of a class, which you'll see in Chapter 5 when we discuss class diagrams.

The actor shown in Figure 4-1 is a normal actor, meaning that it's a real actor that interacts directly with your solution. Other kinds of actors exist, namely business actors.

Business actors are actors in the business you're analyzing, meaning that all people or things participating in the business's daily processes are actors from the business point of view. The business actors aren't necessarily actors to your solution.
[2] A business actor will become an actor to your solution only if the role that the actor represents interacts with your solution or delivers or receives information from your solution. Instead, they are actors to the business. One example of this is accounting assistants. Accounting assistants may not be an actor to the solution you're developing, but they can easily be a business actor. So why would you pay any attention to accounting assistants? Well, they can be the subject of interviews that provide you with valuable information, even if the role isn't an actor to the solution. The knowledge of accounting assistants and their daily work might also offer valuable information to you when you optimize some of your processes.

The bottom line is that because you need to understand the entire business before you design your solution, you're conducting a business analysis. A business analysis is the process of documenting the business. The actors in a business analysis are business actors. They might become actors to your solution as well, but they might not. But how do you distinguish between actors and business actors in your UML model? The answer is by creating stereotypes. We introduce stereotypes in detail in Chapter 5, where we examine the structural models. For now, let's just say that stereotypes are like classifications you can apply to the elements in your UML model to make the elements more specific. If you apply the stereotype Business Actor to an actor, that actor is then a business actor.

Here is a list of typical actors to a solution:

  • Customer

  • User

  • Administrator

  • Accountant

  • Accounting System

  • Supervisor

As you can see, actors are the people or things (for example, other IT systems) that interact with your solution.

As an example, we'll develop a business analysis showing the business users in the accounting department. When you do business analysis, it's a good idea to generalize actors. This way, you have an easier job when selecting which business actors are actually actors to your solution. The reason for this is that an actor represents a role and that the generalized business actors represent the same role in relation to your solution. The accounting assistant and the accounting supervisor might represent the same role to your solution, while the accounting secretary might not be an actor to your solution.

To model this simple example, you start by placing all possible actors from the accounting department on the use case diagram. In Exercise 4-1, you'll start a use case diagram and add actors to it.

Exercise 4-1
Start example

  1. Open VEA (if is not already open).

  2. Create a new UML model (select File ®New® Software ® UML Model Diagram). Now you have a "sheet of paper" ready for your UML modeling. Next, you need to tell VEA which kind of UML model you want to create. In this case, it's a use case diagram.

  3. Open the Model Explorer (if it's not already shown) by selecting UML ®View ®Model Explorer.

  4. Right-click the place (package or subsystem) where you want to add a new use case diagram and select New ® Use Case Diagram from the pop-up menu.

    Note

    When you create a new UML model, the only package available is the Top Package, which represents the global namespace of your .NET solution. You must have at least one package in your UML model.

  5. Add four actors to the use case diagram: Accountant Assistant, Accountant Supervisor, Accountant Trainee, and Accountant Secretary. Do this by dragging the actors onto the diagram. Then double-click each actor and change the name. Your actors should look like Figure 4-2.

    Click To expand
    Figure 4-2: Business actors

End example

The next task is to group the actors and model their relationships. When analyzing and gathering requirements, you might want to interview all the different business actors from the accounting department, or at least you want to know that they exist. In your solution, however, you might just need one actor (role) representing the accounting department: an accountant actor. With this in mind,it makes sense to generalize business actors, which will make it easier for you to get an overview of your business actors and find the business actors that are also "real" actors in your solution. Exercise 4-2 demonstrates how to generalize the business actors.

Exercise 4-2
Start example

  1. Add an Accountant actor to the use case diagram created in Exercise 4-1.

  2. Group the actors on the use case diagram, as shown in Figure 4-3.

    Click To expand
    Figure 4-3: Business actors with generalization (inheritance)

  3. Add extends relationships between the following elements:

    • Accountant Assistant and Accountant Trainee

    • Accountant Assistant and Accountant

    • Accountant Supervisor and Accountant

    • Accountant Secretary and Accountant

  4. Change the stereotype for all of the extends relationships to Inherits. To do this, double-click each relationship and select inherits from the Stereotype list.

  5. Your use case diagram should now look like Figure 4-3, although the Inherits stereotype might be shown on your diagram. To change this, right-click the relationship and select Shape Display Options from the pop-up menu. Then deselect the Stereotype option in the General options group.

End example

To create the model shown in Figure 4-3, you simply created a new actor, the Accountant, and then you drew the generalize (in VEA, this is named inherits)relationship between the actors. Relationships are discussed in the next section, but before continuing, you need to complete your business actor diagram. As it stands now, you can't tell from the diagram that the actors are business actors and not normal actors. This is where stereotypes come into the picture. Stereotypes work like classifications and thus can be subclasses you can attach to your UML elements. In Exercise 4-3, you'll apply the Business Actor stereotype (as noted earlier, stereotypes will be explained in detail in Chapter 5).

Exercise 4-3
Start example

  1. Open the Stereotypes dialog box by selecting UML ® Stereotypes.

  2. Click New to create a new stereotype.

  3. Change the name of the new stereotype from Stereotype1 to Business Actor by typing it in the Stereotype column. Select Actor from the list in the Base Class column. Then click OK.

  4. Open the UML Actor Properties dialog box by double-clicking each of the five actors.

  5. Select Business Actor from the Stereotype list and click OK. Your use case diagram should now look like Figure 4-4. You can see the actors with the Business Actor stereotype, indicating that the actor is indeed a business actor and not an actor to your solution.

    Click To expand
    Figure 4-4: Business actors shown with stereotypes

End example

Relationships

You used relationships when you made the generalization of business actors in the previous section. Relationships are used to indicate to which elements an actor relates. An actor can relate to other actors, as you saw in the business use case example (Figure 4-4), and an actor can relate to use cases. The latter case is the most common. Actors relate to use cases to illustrate that they receive information from the use case or deliver input or information to the use case.

Use case diagrams include three types of relationships:

  • Communicates relationship

  • Uses relationship

  • Extends relationship

The three types of relationships are described in the following sections.

Communicates Relationship

The communicates relationship is indicated by a solid line in UML notation. It represents the relationship between an actor and a use case. This also means that a communicates relationship can't be modeled between two actors or two use cases. If you need a relationship between two use cases or two actors, you should use the uses relationship or the extends relationship.

A communicates relationship between an actor and a use case indicates that the actor either receives information from or provides input or information to the use case. Most likely, it indicates that the actor interacts with the use case, meaning that the actor performs the tasks included in the use case. In UML terminology, communicates relationships are often referred to as associations.

Figure 4-5 shows a communicates relationship between an actor and a use case. As in the creation of the business actors, you create the diagram by dragging the elements onto the diagram and dragging the connection points together.
[3] Connection points are the X-shaped points on the UML shapes to which you can attach other elements.

Click To expand
Figure 4-5: Communicates relationship between an actor and a use case

The example shows a communicates relationship between the actor Accountant and the use case Invoice, indicating that the actor Accountant either performs the tasks included in the Invoice use case (which is most likely) or receives information from the use case. This is, in general, all you need to do to model sound and solid use case diagrams.

Double-clicking the communicates relationship line gives you the opportunity to apply some attributes to the relationship. It's possible to specify some settings for the communicates relationship ends and specify the reading direction. VEA allows you to add information to associations, but use case diagrams should not have such information on their associations. You can specify operations, attributes, and multiplicity for your communicates relationships. Operations are the actions an actor performs, attributes are the properties of an actor, and multiplicity refers to the number of possible concurrent instances of an actor. Such additional information might be useful if your actor represents an application in which the knowledge of certain operations and attributes is valuable in the context of your solution. However, if an actor represents a person, these settings rarely make sense.

Uses Relationship

Another relationship type you can use when developing use case models is the uses relationship. This relationship type indicates that a use case uses the functionality provided by another use case. When will you use this kind of relationship? You can, and probably should, use it whenever you're about to include the same functionality in two or more use cases.

For example, say you need to check the credit limit of a customer account. This functionality can be in a separate use case. This use case can be used as it is, but other use cases might also use the functionality of checking the credit limit. These use cases can include the functionality by having a uses relationship to the use case that holds the credit limit check functionality. The benefit is that it simplifies your use cases, and you don't accidentally implement the same functionality in different classes later on when you develop the physical design.

The uses relationship can exist between two elements of the same type—that is, between two use cases. Again, you model the diagram simply by dragging the elements onto the diagram. Figure 4-6 shows an example of a uses relationship.

Click To expand
Figure 4-6: Uses relationship between use cases

Extends Relationship

The other relationship type in use case modeling is the extends relationship. The extends relationship indicates that a use case can use the functionality of another use case. But wasn't that just what you saw in the uses relationship example in Figure 4-6? Well, yes it was, but it's not exactly the same. Notice the wording a few sentences back: ". . .a use case can use the functionality of another use case." Can is the important word here, because the difference between a uses relationship and an extends relationship is that the extends relationship provides an optional decision on whether the related use case will use the other use case's functionality. Inthe uses relationship, the use case always uses the functionality from the related use case.

Figure 4-7 shows an example of an extends relationship. You can see that the Accountant creates the Invoice, and this actor can choose to print the invoice or not, because it's optional.

Click To expand
Figure 4-7: Extends relationship

The extends relationship can exist between two use cases and between two actors, although only the relationship between use cases is commonly used. We used the extends relationship in the actor generalization example because that is the best way to show generalization without creating new stereotypes. Notice that the uses relationship arrowhead points toward the use case that uses the base class, and the extends relationship arrowhead points from the use case that extends the base class toward the base class, as shown in Figure 4-7.

Processes

You've seen processes described plenty of times, so we won't annoy you by describing them yet again. Instead, you'll learn how a process—a sequence of tasks—is created.

To complete a use case, you need to outline all the tasks involved in the use case and specify what preconditions and postconditions exist, because a process always performs some transformation of the data. Preconditions are the conditions that must be met before the tasks in the process can start; for example, the actor promises to do this before calling the use case. Postconditions are the present conditions for the involved objects, after the process tasks have been completed; that is, the use case promises to achieve this always. You specify the preconditions,the postconditions, and the sequence of tasks needed to perform the use case. Everything is printed in the Documentation text box in the UML Use Case Properties dialog box, as shown in Figure 4-8. To open this dialog box, right-click the use case and select Properties from the pop-up menu, or double-click the use case.

Click To expand
Figure 4-8: Documentation text box for the Invoice use case

You can open the Documentation window by selecting UML® View ®Documentation. The Documentation window always shows the documentation related to the selected element, or rather the element with the focus on the diagram. As Figure 4-9 shows, when the Invoice use case is selected on the diagram, the documentation for this use case is shown in the Documentation window.

Click To expand
Figure 4-9: The Documentation window
Note

In VEA, you can't reference a Word document or a similar file instead of using the Documentation window. This is a major weakness of VEA; this functionality is available in many other UML tools.

When you double-click the use case, you can specify additional settings, such as properties and attributes. You may want to set attributes and operations for your use case to specify the behavior of the use case. An interesting setting is the extension points. Extension points are used for including action sequences from other use cases, and they must be unique. An extends use case breaks out from the base use case at the extension point, performs the tasks from the use case it includes, and then returns. To see the extension points, right-click the use case, select Properties from the pop-up menu to open the UML Use Case Properties dialog box (see Figure 4-8), and select the Extension Points category.

In the UML Use Case Properties dialog box, you also see the Tagged Values category. Tagged values are information you can specify about an element (they can be applied to any model element). You can create your own tagged values as well. One tagged value you might want to create when developing enterprise solutions is a rank tagged value, where you can specify how the use case is ranked. This can be valuable information when you develop iteration plans or make project tradeoffs (both concepts are covered in Chapter 20).

So, what if a use case is only relevant while doing business analysis and it doesn't end up as part of your solution? Then you have a business use case, and you set the stereotype to Business Use Case. (See Exercise 4-3 for an example of how to create and a apply stereotype, and Chapter 5 for a detailed discussion of stereotypes.) Figure 4-10 shows the Invoice use case with the Business Use Case stereotype.

Figure 4-10: Use case with the Business Use Case stereotype

Packages

Basically, packages are a way of organizing your UML models. You can imagine the mess when the UML model evolves, resulting in a huge number of use case diagrams, use cases, and actors. With packages, you have a way of organizing all of these items. Consider packages as file folders where you can organize diagrams, elements, and even other packages.

The concept of packages can be confusing, especially because packages are used for many different things. For example, you might recognize the word packagefrom the SQL Server world, where you can create Data Transformation Services (DTS) packages.
[4] DTS packages are created to perform transformation of data. They contain information about connection, workflow, and so on. If you're a project manager, you might have seen the word Testpackage, which refers to a collection of documents and scripts specifying the test sequence. However, in UML, packages are simply a way for you to group related models and elements. Figure 4-11 shows the notation for a package placed on the use case diagram (dragged from the Shapes window).

Figure 4-11: The package notation

In Exercise 4-4, you'll put a use case into a package.

Exercise 4-4
Start example

  1. In VEA, create a new UML model.

  2. Drag a Package shape from the Shapes window onto the open diagram.

  3. Name the package by double-clicking it, typing Administrator in the Name text field, and clicking OK.

  4. Drag a Class shape onto the diagram and name it Invoice.

  5. Create a new stereotype named Business Use Case (see Exercise 4-3 for instructions on how to create a stereotype).

  6. Apply the Business Use Case stereotype to the Invoice use case, making it look like Figure 4-10 (shown earlier).

  7. Drag the Invoice use case into the Administrator package in the Model Explorer. Notice how the Model Explorer and the Invoice use case change. Your use case diagram should now look like in Figure 4-12. You'll see that the package name in front of the use case name.

    Click To expand
    Figure 4-12: Use case in a package

End example

Packages not only provide a way of organizing the use cases and other UML elements, but they can also represent a specific scope. In other words, you can use packages to group elements that share the same specific behavior—for example, a namespace.[1] That's right! You can use packages to group elements that share the same namespace. In fact, this is exactly the way to do .NET modeling with UML.When using VEA, you can generate code with the correct namespace settings when you group elements into packages. The global namespace becomes the global package, which is named Top Package by default. The global namespace is typically the name of your organization. You'll see how this works when you model classes in the following chapters.

Another time you'll use packages is when you organize systems or subsystems. A system is the entire system you're modeling. A subsystem is a smaller, isolated part of your system. All your subsystems add up to your total system. When developing enterprise solutions, you're often developing the solution by developing a number of smaller projects. It's a good idea to document this in a use case diagram. The notation for a system is a package with the System stereotype, and the notation for a subsystem is a package with the Subsystem stereotype. However, VEA has a predefined subsystem element, so you can use this instead of a package with the Subsystem stereotype. Why has Microsoft chosen to do this? The reason is probably that subsystems can have operations, unlike packages, and subsystems can also have interfaces.

Let's say you're going to develop an enterprise solution called the ToyCar Enterprise System. This system will contain two different systems (just to keep it simple): the e-Commerce System and the Product Testing System, where the quality assurance (QA) people test the products. Users of the ToyCar Enterprise System can use both systems, but not simultaneously. All this information is valuable, and you want the developers to know about it, right? You also want all the UML diagrams in the same Visio model, but you don't want to mix the e-Commerce UML diagrams with the Product Testing diagrams. The solution is to document the separation of the subsystems and prepare the packages. Exercise 4-5 shows how to do this.

Exercise 4-5
Start example

  1. In VEA, create a new UML model.

  2. Rename the top package Company Enterprise System. To rename an element in the Model Explorer, select it and press F2. Then type in the new name and press Enter.

  3. Drag a Package shape onto the open diagram.

  4. Set the stereotype of the package to System and rename it ToyCar Enterprise System.

  5. Right-click the ToyCar Enterprise System package in the Model Explorer and insert two subsystems. To add a subsystem, right-click and select New®Subsystem.

  6. Rename the two subsystems e-Commerce System and Product Testing System, respectively, and drag them onto the diagram. Your UML model should look like Figure 4-13.

    Click To expand
    Figure 4-13: ToyCar Enterprise System packages on a static structure diagram

End example

In Figure 4-13, notice that the diagram is a static structure instead of a use case diagram. The reason is that system structure models are not ordinary use cases, but merely static structures. However, we feel that the description of system structures is actually use case modeling, even though it's the static structure that's being modeled.

If your subsystem e-Commerce System is actually made of two subsystems—an Administrator System and a Public Commerce System—you need to add the subsystems and dependency relationships. Exercise 4-6 demonstrates how to do this.

Exercise 4-6
Start example

  1. Right-click the e-Commerce System package of the UML model (created in Exercise 4-5) in the Model Explorer window and insert two subsystems.

  2. Rename the two subsystems Administrator System and Commerce System, respectively, and drag them onto the diagram.

  3. Add a dependency relationship between the following system and subsystems:

    • Administrator System and e-Commerce System

    • Commerce System and e-Commerce System

    • e-Commerce System and ToyCar Enterprise System

    • Product Testing System and ToyCar Enterprise Syste

  4. Your diagram should now look like Figure 4-14.

    Click To expand
    Figure 4-14: The final system structure

End example

System Boundaries

A system boundary is like a frame. You can place a system boundary around your use cases to indicate that the grouped use cases form a complete system. Exercise 4-7 demonstrates how to add a system boundary.

Exercise 4-7
Start example

  1. In VEA, create a new UML model.

  2. Drag an Actor shape onto the open diagram and name it Accountant.

  3. Drag two Use Case shapes onto the diagram and name them Invoice and Print Invoice.

  4. Add an extends relationship between the Invoice and Print Invoice use cases.

  5. Add a communicates relationship between the Accountant actor and the Invoice use case.

  6. Drag a System Boundary shape onto the diagram and name it Sales System (double-click the shape to rename it).

  7. Place Sales System so that the left side of the shape is between the Accountant actor and the Invoice use case. You might want to resize the System Boundary shape so that you can see all four sides. To resize the shape, place the mouse over the side you want to resize, and then drag it to the desired size.

  8. Your use case diagram should now look like in Figure 4-15, although the end names and multiplicity for the communicates relationship might be shown on your diagram. To change this, right-click the relationship and select Shape Display Options from the pop-up menu. Then deselect the First end name, Second end name, and End multiplicities options in the End options group.

    Click To expand
    Figure 4-15: System boundary

End example

In Figure 4-15, you can see that a system boundary encapsulates the use cases included in the system and that the actor, which is not part of the system,
[6] An actor is not part of the system seen from a development point of view. The actor is something or someone outside the system interacting with the system. is placed outside the system boundary.

Use Case Diagram Summary

In this first part of the chapter, you learned how to develop use case diagrams using VEA. You learned that a use case diagram consists of use cases and actors interacting with the use cases. These interactions are modeled as relationships. Three types of relationships exist: uses, extends, and communicates. The actions an actor performs are modeled as a sequence of actions specified in the documentation of the use case.

You also learned how packages and stereotypes can help you organize and describe your solution. You're now ready to start developing enterprise use case diagrams using VEA.

[1] A namespace is a way of organizing the element scopes. You can find an explanation of namespaces at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcn7/html/vaconNamespaces.asp.


Sequence Diagrams

Creating sequence diagrams is a way to document scenarios in a graphical way. Whenever you have a sequence of actions you would like to document, you can create a sequence diagram instead of a written scenario.
[7] You can develop sequence diagrams without having written scenarios, you can make scenarios without developing sequence diagrams, or you can make both—the choice is yours. When will you need to do that? In the use case section, you saw that use cases consist of a sequence of tasks (a scenario), and you might want to document this by creating a sequence diagram. Say you have a nice scenario like the one documented in text in Figure 4-8. Why bother creating a sequence diagram? We'll give you three reasons:

You want to document supporting objects. You can document all the assisting objects that you usually don't describe in a scenario. Referring to the scenario in Figure 4-8, you can see that you might need to have a table of orders that you extract a list from in order to choose which order from which to create an invoice. This can be documented in a sequence diagram more easily than it can be described in plain text in a scenario.

You want to document technical issues. As the project evolves, you might want to document some technical issues on your sequence diagrams. For instance, you can document the parameter types needed, the default values, and so on. If this kind of information is known at this stage, it really should be documented; eventually, the developers and testers will require it. Documenting this information on the sequence diagrams makes it a lot easier to understand what's going to be implemented.

A picture is worth a thousand words. Graphical diagrams can easily document issues you would use a bunch of words to describe if you were writing them out in plain text.

Sequence diagrams are part of the same family as collaboration diagrams, which you'll learn about later in this chapter. The difference between them is that sequence diagrams show the scenario in a time-based way, and collaboration diagrams show how the objects are associated with each other.
[8] The diagram syntax for sequence and collaboration diagrams is also different. By time-based, we mean that one thing happens first, and then another thing happens next—things happen over time in the exact order they are outlined.

We just told you that sequence diagrams are often related to use cases (the scenarios), which is true. However, you can use sequence diagrams for many other purposes. In the use case section, you learned that if you don't understand the business you're working with, or if the task is complex and you need some more information about the processes in the business, you can perform a businessanalysis. When performing a business analysis, you can document all the processes (which will probably be business use cases) using sequence diagrams. In fact, sequence diagrams are probably the strongest tool you have to document what itis you're going to implement.

Sequence diagrams contain the following elements:

  • Objects

  • Activations

  • Messages

  • Notes

The sections that follow describe these sequence diagram elements.

Objects

The objects in your solution are represented as rectangles, as shown in Figure 4-16. The objects in a sequence diagram are persistent elements in your solution. They can be tables, physical forms, or classes. Generally, objects represent classes in your solution, but they can also represent nodes, actors, tables, and so on. One of the key reasons for creating sequence diagrams is that you'll get a view of the possible candidate objects represented as objects on the sequence diagram.

Click To expand
Figure 4-16: Sequence diagram with class lifeline

Exercise 4-8 shows how to insert an object on a sequence diagram.

Exercise 4-8
Start example

  1. In VEA, create a new UML model.

    Note

    When performing this Exercise on a new model, the diagram shown will automatically be a sequence diagram. Otherwise, you can insert a sequence diagram by right-clicking the package where you want the sequence diagram inserted and selecting New ® Sequence Diagram.

  2. Drag an Object Lifeline shape from the UML Sequence tab in the Shapes window onto the diagram.

  3. Double-click the object lifeline, and change the object lifeline's name, which must be unique, to Class1.

    Note

    When your UML model doesn't contain any classes, as in this example, the UML Class Properties dialog box automatically opens when you open the UML Classifier Role Properties dialog box (such as by double-clicking an Object Lifeline shape). This is because each object must relate to a classifier (class). If you already have classes in your UML model, the UML Class Properties dialog box doesn't automatically open when you double-click the Object Lifeline shape. In this case, you can set the classifier by selecting it in the Classifier list in the UML Classifier Role Properties dialog box. If it doesn't exist, you can create it by clicking the New button and specifying the settings.

  4. In the UML Class Properties dialog box, which opened automatically, you can accept the default name of Class1 for the new class (classifier) being created. Click OK. Your sequence diagram should now look like Figure 4-16.

    Tip

    When you hold down both the Ctrl and Shift keys, the pointer turns into a magnifying glass, and clicking the left mouse button enlarges the view; clicking the right mouse button reduces the view. Whether you enlarge or reduce, the new view is centered wherever you click.
End example

A classifier is an indication of what the class lifeline represents. In this case, the class lifeline represents the Class1 class. As you learned in Chapter 2, objects can be things or people, so an object can be a class. However, it can also be an actor. In Exercise 4-9, you'll add an actor object to the sequence diagram.

Exercise 4-9
Start example

  1. Create an actor in Model Explorer by right-clicking the package in which you want to place the actor and selecting New ® Actor from the pop-up menu.

  2. Click OK in the UML Actor Properties dialog box to accept the default name (Actor1).

  3. Drag an Object Lifeline shape onto the sequence diagram.

  4. Double-click the Object Lifeline shape, change its name to Actor1, and set the classifier to Actor1. (It isn't necessary to give the Object Lifeline shape the same name as its classifier, but it must have a unique name.) Your diagram should now look like Figure 4-17.

    Figure 4-17: Sequence diagram with class and actor lifelines

End example

In Figure 4-17, you can see that the Object Lifeline shape has changed to an Actor shape, because it represents an actor through the classifier setting. In addition, notice the dashed vertical line under the Object Lifeline shapes; this is the lifeline (surprisingly!). The lifeline represents time, and the length of the lifeline should reflect the actual time (the time your object lives before it's destroyed).You can't connect actions to a lifeline directly; you need activations (which are covered next) for that purpose.

Activations

Activations are thin rectangles you can connect to an object lifeline. When you do so, the object lifeline (object) is able to participate in actions. An action is similarto an event, and like events, an action can be triggered by a user (for example, when a user clicks a button), by another system, or by a signal (for instance, a specific time of day or date).

Exercise 4-10 demonstrates how to add activations to an object.

Exercise 4-10
Start example

  1. Drag an Activation shape onto the Class1 object lifeline on the sequence diagram created in Exercise 4-8 and edited in Exercise 4-9.

  2. Attach the endpoints of the Activation shape to the object lifeline's connection points. Both connection points must be connected. (You might need to extend the Object Lifeline shape by dragging it to make it larger than the Activation shape.)

  3. Resize the length of the Activation shape to represent the time it takes to perform the action. You can't specify a specific amount of time, such as 30 minutes, but you can indicate how much of the object's lifeline the action will take. For example, if it covers the entire lifeline, the action takes 100% of the time the object is alive. Your diagram should now look like Figure 4-18.

    Figure 4-18: Sequence diagram with an Activation shape

End example

In Figure 4-18, you can see the Class1 object is prepared to participate in actions, and deliver messages to and receive messages from other objects.

Messages

Objects—such as classes, tables, and so on—are the persistent elements of your solution. Messages are the actions performed between the objects, and they will often be methods of your classes, which are uninstantiated objects or functions in code modules. A message signals communication between two objects and thus represents an action. On sequence diagrams, a message represents exactly one message.
[9] In collaboration diagrams, a message can represent several messages.

The following types of messages, illustrated in Figure 4-19, exist for sequence diagrams:

Figure 4-19: The six sequence diagram message types

Message: This is an ordinary message. It's connected to connection points on two different object lifelines. In Figure 4-19, you can see an example of a Message shown as Message1. This type of message represents an action and is related to a method or operation on the receiving object (to which the arrowhead points). This means that the object receiving the message performs an action on this request. The message can contain parameters passed to the method to be executed.

Message (call): Message calls are messages where the flow type is a procedural call, meaning that the message call is part of a procedural call. Despite this, message calls behave like ordinary messages. Message2 and Message3 in Figure 4-19 are message calls. Message3 differs from Message2 in that it's a message call to the sending object itself (for example, to give some polymorphic behavior).

Message (return): Return messages are messages that return information to an object, usually after performing an action. Because the return messages don't perform actions (they simply return information), they aren't related to methods or operations as ordinary messages are. In Figure 4-19, Message4 and Message6 are return messages, but Message6 is a return message to the sending object itself.

Message (asynchronous): Asynchronous calls are messages where the flow type is set to asynchronous. This means that the sending object sends a message to the receiving object without needing to wait for the receiving object to respond. The sending object can continue with other operations, while the receiving object performs the action requested by the sent message. In Figure 4-19, Message5 is an asynchronous message. Asynchronous messages differ from ordinary messages (and message calls) in the way that asynchronous messages are not really methods (operations). Instead, they're so-called receptions. A reception is simply an indication that the classifier (operation) is able to react to a specific signal.

To add a message to a sequence diagram, simply drag the Message shape from the UML Sequence tab to the diagram and connect the connection points. Messages can contain arguments or parameters, and if you make sure to add the required arguments to the messages, your developers can actually use this kind of documentation to create class diagrams. You can also specify sequence numbers, which are helpful for representing the order in which messages are sent and what messages are related. Use the numbers on sequence diagrams just as quick references—the sequence is evident from where the messages are (on collaboration diagrams, the sequence numbers are much more important). Specify sequence numbers by double-clicking the message and typing a number into the Sequence expression text box.

Let's say you have an object, a class named Order, and this object contains a method or operation called GetList, which retrieves a list of orders for a specific date. To retrieve the list of orders, you need to extract information from the Orders table, which contains all of your orders. The Orders table is an object as well. You can document it as shown in Exercise 4-11.

Exercise 4-11
Start example

  1. In VEA, create a new UML model.

  2. Create a new class in the Top Package package with the name Order and with the Implementation Class stereotype.

  3. Create another class in the Top Package package with the name Orders.

  4. Drag an Object Lifeline shape onto the open diagram and name it Order. Set the classifier to Top Package::Order.

  5. Drag an Object Lifeline shape onto the diagram and name it Orders. Set the classifier to Top Package::Orders. Your diagram should now look like Figure 4-20.

    Figure 4-20: Sequence diagram with objects

End example
Note

In Figure 4-20, the Implementation Class stereotype is used to indicate that the class is an implementation class. A class could instead be a type class, representing a type. An implementation class could be an implementation of that particular type, modeled by a realizes relationship between the type class and the implementation class.

The next step is to add the GetList action, which retrieves all of the orders for a specific date from the Orders table. To add an action, you must first place Activation shapes on the Object Lifeline shapes. You can then place the GetList message on the diagram by dragging a Message shape from the UML Sequence tab and connecting the connection points of the two objects that participate in the message exchange. Exercise 4-12 demonstrates how to do this.

Exercise 4-12
Start example

  1. Drag an Activation shape onto the Order object lifeline of the sequence diagram created in Exercise 4-11.

  2. Drag an Activation shape onto the Orders object lifeline. Your diagram should now look like Figure 4-21.

    Figure 4-21: Sequence diagram with objects and activations

  3. Drag a Message shape onto the diagram and connect the Order object lifeline with the Orders object lifeline. Your diagram should now look like Figure 4-22. You can see the Message1 message being sent from the Order object to the Orders object. However, it doesn't yet perform any operations on the Orders object.

    Figure 4-22: Sequence diagram with a message

  4. Rename the message to GetList.

  5. Double-click the Message shape to open the UML Message Properties dialog box.

    Note

    When the object that the Message shape is sent to doesn't contain any operations, as in this example, the UML Operation Properties dialog box automatically opens when you open the UML Message Properties dialog box. If the object that the Message shape is sent to does contain one or more operations, but not the one you want to perform, you can click the New button in the UML Message Properties dialog box to create a new operation.

  6. In the UML Operation Properties dialog box, which opened automatically, name the operation GetList and click OK.

  7. The new operation created in step 6 is now automatically selected in the Operation list of the UML Message Properties dialog box. Click OK to accept it as the operation for this message. Your diagram should now look like Figure 4-23.

    Figure 4-23: Message with a message name

End example

In Figure 4-23, you have a message from the Order class performing the GetList operation or method on the Orders table object. What does the Orders table object do when it receives this message? Well, nothing yet. In order to have the Orders table object execute the GetList method and send back the data requested, you need to add a return message. Exercise 4-13 demonstrates how to add the desired return message to the diagram.

Exercise 4-13
Start example

  1. Drag a Return Message shape onto the diagram.

  2. Connect the Order object lifeline with the Orders object lifeline on the sequence diagram created in Exercise 4-11 and edited in Exercise 4-12.

  3. Name the return message Orders (DataSet) to indicate that a DataSet containing the requested orders is returned. Your diagram should now look like Figure 4-24.

    Click To expand
    Figure 4-24: Return message on the sequence diagram

End example

In Figure 4-24, you can see the Orders return message returning the requested orders in a DataSet. Earlier, we stated that the GetList method of the Orders object retrieved all orders matching a specific date. However, you haven't actually specified this yet. Exercise 4-14 shows how to add an argument/parameter to the operation performed by the message.

Exercise 4-14
Start example

  1. Open the UML Operation Properties dialog box for the GetList operation of the Orders object on the sequence diagram created in Exercise 4-11 and edited in Exercises 4-12 and 4-13. Double-click the message shown below the Orders object in the Model Explorer to open the dialog box.

  2. Select Parameters in the Categories list and click New.

  3. Name the parameter FromDate and select VB::Date from the Type list. Your diagram should now look like Figure 4-25.

    Click To expand
    Figure 4-25: Parameter setting on a message

End example

In Figure 4-25, you can see that the GetList message now has the parameter FromDate, which is of the VB Date data type.
[10] You can't actually tell what the parameter's data type is from the Model Explorer or the sequence diagram. You need to open the UML Operation Properties dialog box or the UML Parameter Properties dialog box to see or edit the data type. Notice that your Orders class in the Model Explorer window displays the parameter as well.

Notes

Notes are simply small notes you can attach to an element, just like the rather well-known Post-It notes. They are simple, yet very useful. To add a note, simply drag the Note shape from the UML Sequence tab to the diagram, as shown in Figure 4-26.

Click To expand
Figure 4-26: Note on a sequence diagram

In the middle of the Note shape (when selected), you'll find a connection point (a yellow diamond), which you can connect to the connection points of the objects to which you want to attach your note. You can connect a single note to as many elements as you want. In Figure 4-27, the note is connected to the Orders object lifeline. When you double-click the note, you can type in the note text in the Documentation text field.

Click To expand
Figure 4-27: Attached Note shape with text

Sequence Diagram Summary

In this section, you learned about the basics of sequence diagrams. You learned that objects can be classes, actors, or even forms represented by object lifelines. You can attach activations to object lifelines to place actions on them. The activations (loosely) illustrate the time it takes to perform the actions. Activations can be connected with messages. A message indicates that one object sends a message to another object, and that an action might follow, depending on the message flow type. Finally, you learned that messages can contain parameters.

A sequence diagram is two-dimensional. The horizontal dimension represents the objects. The vertical dimension represents the time aspect. Time progresses from the top to the bottom. It's that simple.


Collaboration Diagrams

Collaboration diagrams have a lot in common with sequence diagrams. They're both used to document how objects interact. However, unlike the time-based sequence diagrams, collaboration diagrams show the objects and their corresponding associations without emphasizing time. Collaboration diagrams show a sequence of messages that implement an interaction. This is the only difference between the two types of diagrams, so all that you've learned about sequence diagrams also applies to collaboration diagrams. The two types of diagrams are simply two different ways of expressing the same thing. You'll use collaboration diagrams to view the dynamic content of the system. Because messages in collaboration diagrams don't focus on the time aspect, they're numbered so you'll know the sequence in which they occur.
[11] Messages in sequence diagrams can be numbered as well, but in collaboration diagrams they must be.

  • Collaboration diagrams have three basic elements:

  • Objects

  • Links (between the objects)

  • Messages

Objects

Objects have names, states, and behaviors. Each object in a diagram indicates an instance of a class. That's why the classifier of an object needs to point to a class. You must tell VEA from which class your object is instantiated. You can create a collaboration diagram by right-clicking the package in which you want to insert your collaboration diagram and choosing New ®Collaboration Diagram from the pop-up menu. Two shapes represent objects: the Classifier Role shape and the Multi-Object shape. In Figure 4-28, you see a Classifier Role shape, Object1, and a Multi-Object shape, Object2, added to the diagram.

Figure 4-28: The Classifier Role shape and the Multi-Object shape on a collaboration diagram

The difference between objects represented by a Classifier Role shape and objects represented by a Multi-Object shape is that the Classifier Role shape represents a single object, whereas the Multi-Object shape represents a set of objects that are instances of the same class. The connection from the classifier to the class and the setting of properties are the same as in sequence diagrams, described in the previous section.

Links

Links, represented by the Association Role shape, indicate that the objects are related to each other. This relationship often indicates that the objects exchange messages.

To add a link, drag an Association Role shape onto the diagram and connect the two connection points to a connection point on each of the two Classifier Role shapes. You'll see an error if you haven't associated the Association Role with an existing association between the two underlying classes to which the classifier roles point. The reason for this is that you need the link to point to a real association (a classifier).

In Exercise 4-15, you'll create a collaboration diagram and add objects and links.

Exercise 4-15
Start example

  1. In VEA, create a new UML model.

  2. Create a new collaboration diagram in the Top Package package.

  3. Create a new static structure diagram in the Top Package package.

  4. Drag two Class shapes onto the static structure diagram. By default, they're named Class1 and Class2, which is fine for this Exercise.

  5. Drag a Binary Association shape from the UML Static Structure tab of the Model Explorer onto the static structure diagram, connecting the two classes created in the previous step. Don't display the end names or the multiplicity for the association (right-click, select Shape Display Options, and deselect First end name, Second end name, and End multiplicities). Your diagram should now look like Figure 4-29.

    Click To expand
    Figure 4-29: Static structure diagram with an association

  6. Drag two Classifier Role shapes onto the collaboration diagram. By default, they're named Object1 and Object2, which is fine for our Exercise. Set the classifier for Object1 and Object2 to Class1 and Class2, respectively.

  7. Drag an Association Role shape from the Collaboration tab of the Model Explorer onto the collaboration diagram, connecting the two objects created in the previous step.

  8. Set the base association of the Association Role shape to the binary association created in step 5 (Association1). Double-click the Association Role shape to open the UML Association Role Properties dialog box, shown in Figure 4-30, and select Association1 in the Base association list.

    Click To expand
    Figure 4-30: UML Association Role Properties dialog box

End example

In Figure 4-30, you can see the properties for the Association Role shape on the collaboration diagram. Notice that the base association is set to an existing association: Association1 (which was created between the classes on the class diagram in Exercise 4-15).

Figure 4-31 shows the collaboration diagram without errors, because the base association has been set to an existing association on the static structure diagram. If you don't set the base association of the Association Role shape, it will be displayed with a red marking, and an error will be displayed in the Output window.

Figure 4-31: Collaboration diagram with an association

Messages

Messages are the information that flows between objects, resulting in actions. As we outlined earlier, links (associations) in collaboration diagrams can carry multiple messages. By double-clicking the Association Role shape (see Figure 4-31) and selecting the Messages category in the UML Association Role Properties dialog box (see Figure 4-30), you can create messages, as shown in Figure 4-32.

Click To expand
Figure 4-32: Creating messages for a collaboration diagram

Notice the sequence expression setting (the Seq. Expr. column) in Figure 4-32. It's helpful to know which messages occur first when you look at the final collaboration diagram, shown in Figure 4-33.

Figure 4-33: Collaboration diagram with a message

Collaboration Diagram Summary

Collaboration diagrams are similar to sequence diagrams, despite the fact that sequence diagrams are time-based and collaboration diagrams are not based on time. You'll create collaboration diagrams when you document the tasks involved in a process. Collaboration diagrams are more object-oriented than sequence diagrams because the focus is on the messages and the objects, whereas sequence diagrams focus on the process path because of their time-based way of documenting the process.


Activity Diagrams

Activity diagrams are used to model the workflow of a business process. A business process is a process describing how the business is performing a certain task. An example can be a process called Shipping Orders that describes which business actors and business processes are involved in shipping an order. The difference between a business process and an ordinary process is that the business process describes all the actors and processes involved, whereas the ordinary process (system process) describes only the actors and processes relevant for the solution you're developing.

Activity diagrams are a bit similar to the flowchart diagrams widely used by analysts in the way that you document the workflow from activity to activity. The fact that activity diagrams focus on activities makes them different from state-chart diagrams, which focus on the states an object can be in, even though the two diagrams cover the same thing: object behavior. VEA treats the activity diagram as a special case of the statechart diagram.

You can use activity diagrams to document the workflow of a process, and you'll often create activity diagrams if you need additional information or knowledge to be able to create sequence diagrams. Activity diagrams consist of the following elements:

  • Swimlanes

  • Activities

  • Transitions

  • States

  • Decisions

These elements are described in the following sections.

Swimlanes

You use swimlanes if you want to illustrate the responsibility in the diagram. Each swimlane represents an object, and that object is responsible for everything that happens in its swimlane.
[12] With swimlanes, you can see what happens with the activities before and after the processing in a particular swimlane (object). In this case, an object can be a role or a department from the business. Swimlanes are not mandatory, although they're increasingly popular and supported by all high-end modeling tools. Figure 4-34 shows an example of two swimlanes. The first represents the accounting department, and the second represents the shipping department.

Click To expand
Figure 4-34: Swimlanes on an activity diagram

Activities

After you place the swimlanes (if you chose to do so), it's time to place the activities into the corresponding swimlanes. In Figure 4-35, two Action State shapes are placed on the activity diagram, one in each swimlane. The accounting department is responsible for the Create invoice activity, and the shipping department is responsible for the Ship items and invoice activity.

Click To expand
Figure 4-35: Action State shapes on an activity diagram

Transitions

The next step is to place transitions on the activity diagram. Each activity in an activity diagram must have exactly one outgoing transition.
[13] However, a forked transition has multiple destination states; the outgoing transition is simply aimed at multiple destinations. In Figure 4-36, you can see that a transition (a control flow) is drawn from a connection point on the Create invoice Action State shape to a connection point on the Ship items and invoice Action State shape. Because each activity state must have an outgoing transition, you need to draw an outgoing transition for the Ship items and invoice Action State shape as well, and because this is the last activity in the sequence of activities, you'll indicate this by drawing the transition to a Final State shape.

Click To expand
Figure 4-36: Transitions on an activity diagram

Two kinds of transitions exist:

Object flow: This transition indicates a relationship between the activity and the object related to that activity. For example, an Invoice object can be related to a Mark invoice as sent activity. This relationship or object flow is represented by the Object Flow shape transition, which appears on the diagram as a dashed line with an arrowhead.

Control flow: This transition illustrates an activity that results in triggering another activity (which is the case in Figure 4-36) or in a transition to a new object state. For example, an Invoice object can be used by a Mark invoice as sent activity, and this activity results in a new state for the Invoice object, namely Invoice marked as sent. The control flow transition notation is a solid arrow.

States

You learned a little about state in the previous section. Objects can be in different states. In general, state is a concept where an object either has state or is said to be stateless.

If an object has state, it means that the object "remembers" changes to attributes and internal variables, such as when an operation is performed or an attribute is set to a specific value. Stateless objects don't have state, meaning every time you use a stateless object, the object knows nothing about previous operations that might have been performed or attributes that might have been set. However, stateless objects often save values to a database or a file, and these values are then read from the database or file when a new object instance is created. Objects thathave state move or transition from one state to another when one or more operations are performed or one or more attributes are set.

In the example from the previous section, the Invoice object entered a new state after the Mark invoice as sent activity had been performed.

In Figure 4-37, the Invoice to shipping object has been added to the activity diagram by using the Object In State shape. The Object In State shape differs from the State shape in that the Object In State shape represents a physical object and can be related to an object. The State shape only represents a state (of the process). In Figure 4-37, the transition from the Create invoice state now points to the new Invoice object state, Invoice to shipping, which is used in the Ship items and invoice activity. The transition to that activity is indicated using object flow.

Click To expand
Figure 4-37: State on the activity diagram

Decisions

It's possible to place decisions on activity diagrams. Decisions are used if your activity can evolve in different directions based on a condition. In Figure 4-38, a Decision shape is placed on the activity diagram to check if a shipping method is selected.

Click To expand
Figure 4-38: Decision shape on the activity diagram

When you place a Decision shape, you need to add one incoming transition and at least two outgoing transitions. The outgoing transitions must be created with a guard expression. The guard expression is the condition for the decision branch. Double-click a transition to create a guard expression like the one shown in the UML Transition Properties dialog box in Figure 4-39.

Click To expand
Figure 4-39: UML Transition Properties dialog box with a guard expression

Activity Diagram Summary

Activity diagrams are a way to document the workflow of a business process or system process. You'll also create activity diagrams if you need additional knowledge about the business in order to be able to create sequence diagrams. Activity diagrams focus on the tasks.


UML Elements Compared to .NET

In this chapter, you learned that in the behavioral models, some of the UML elements can be mapped directly to the .NET language. Table 4-1 shows how some of the UML elements from the behavioral models map to the .NET language.

In the next chapter, this will become even clearer, because there we'll cover the static structure diagram (class diagram) from which you can generate .NET code directly.

Table 4-1: UML to .NET Mapping
UML Behavior Element | .NET Language Mapping
Package | Namespace (or system)
Sequence diagram: object | Often an instance of a .NET class
Sequence diagram: message | Often a method (or an event or a property) of a .NET class


Summary

In this chapter, you learned about the behavioral UML models, which describe the dynamic aspect of your solution. You learned how to gather requirements for your solution by creating the behavioral diagrams: the use case diagram and the sequence diagram. You also explored how to learn more about the business you are working with by creating activity diagrams. Finally, you learned that many of the elements in the various models act as input to other models, and that some of the elements can be mapped to .NET language specifics. We know this isn't the most exciting stuff to read about, but you need to know the terminology before you can start putting these concepts into action.

In the next chapter, you'll learn about the static UML models. The static models describe the structure or architecture of your solution.


Chapter 5: Examining the UML Models: Static Models

Overview

In this chapter, we'll introduce you to the UML diagrams known as structural diagrams, which describe the structure (static structure) of your solution. The following UML diagrams are structural diagrams:

  • Class diagram

  • Statechart diagram

  • Component diagram

  • Deployment diagram

As in Chapter 4, we'll describe the frequently used diagrams in detail and use VEA 2003 for the Exercises. These Exercises are simple, yet they do teach you how to work with the UML models in VEA. Do yourself a favor and follow the Exercises, especially if you're new to UML and/or VEA.

In this chapter, you'll see the code generation, which you didn't see in Chapter 4. The reason for this is that all code generation is based on the static structure diagrams (class diagrams).[1] You'll also learn about stereotypes, which are basically a way to extend the UML specification by making a subtype appear as an ordinary element. At the end of the chapter, we'll show you how .NET code maps to UML.

[1]Static structure diagrams can be class diagrams or another diagram type covering the static structure (for example, an object diagram showing physical real-life objects).


Class Diagrams

The class diagram is the most essential part of UML modeling, because you determine in your class diagram how the (static) structure of your solution should look, modeled at the most detailed level. In your class diagram, you can see which classes, COM+ components, ASP pages, and so on will be implemented and how they interact with each other. COM+ components, ASP pages, and so on are simply classes with another stereotype, as you'll learn in this chapter.

When the developers develop the solution, their main source of information is the class diagram. The class diagram provides developers with detailed information about what operation code to develop, along with information about data types, parameters, and namespaces. If the developers need some supportinginformation about the behavior of the solution, they will look at the behavioral diagrams, such as the sequence diagrams and activity diagrams.

Another reason why class diagrams are the most important part of your UML modeling is that you can generate code only from your static structure diagrams, and your class diagrams are the only diagram type from which you'll have a code skeleton for ready use in VS .NET.[2] Class diagrams basically consist of the following elements:

  • Packages

  • Classes

  • Relationships

We'll look at each of these elements in the following sections.

Packages

You've already been introduced to packages in Chapter 4. Packages can relate to different issues, depending on which diagram are implemented. For class diagrams,a package has two functions:

  • A package can be created to group related elements. This can be very useful if you want to form a general view of the model.

  • A package can represent a namespace.

In Exercise 5-1, you'll create a class diagram named MyClassDiagram with a package named MyNamespace, as shown in Figure 5-1.

Click To expand
Figure 5-1: Class diagram with a namespace (package)
Exercise 5-1
Start example

  1. Open VEA, if it is not already open.

  2. Create a class diagram named MyClassDiagram.

  3. Create a package named MyNamespace.

  4. Drag a class to the MyClassDiagram diagram and name this class Customer.

  5. Drag the Customer class in the Model Explorer window onto the MyNamespace package. Notice that the Customer class placed on the MyClassDiagram diagram now has the Namespace specification attached.

    Note

    We've noticed a bug in VEA: If you create a package in an empty model, the package classifier might not show on the class. To solve this problem, create a new package and delete the first one.

  6. You can generate the code for the class and namespace by selecting UML ®Code ® Generate. In the Generate dialog box, choose Visual Basic as the target language, check the Customer check box, and specify the path as \EDWVSNETUMLMSF\Chapter 05\, as shown in Figure 5-2. Click OK.

    Click To expand
    Figure 5-2: Generate dialog box with the Customer class

  7. VEA now generates the file \EDWVSNETUMLMSF\Chapter 05\ TopPackage\MyNamespace\Customer.vb, containing the code shown in Figure 5-3. Double-click to open the file in VS .NET.

    Click To expand
    Figure 5-3: VB .NET code generated for the Customer class

End example

Figure 5-4 shows the code for the Customer class generated with C# as the target language.

Click To expand
Figure 5-4: C# code generated for the Customer class

As you might have noticed, Package shapes are located in the Model Explorer window as well. You can see the MyNamespace package and the Top Package. As you learned in Chapter 4, the global namespace is the global package, and it is named Top Package by default. You're allowed to have multiple nested packages. To nesta package, just drag a Package shape under another Package shape in the Model Explorer window. (In Chapter 12, you'll learn what the other Package shapes in the Model Explorer window represent.)

Classes

The next step in your class diagram modeling is to place the classes on the diagram. You can drag the classes from the Shapes window onto the diagram, or you can right-click the package in which you want your new class created, and then choose New® Class from the pop-up menu. If you create a new class in a package, it's automatically related to that namespace (package). If you double-click a class, you'll see the UML Class Properties dialog box, as shown in Figure 5-5.

Click To expand
Figure 5-5: UML Class Properties dialog box for the Customer class

The basic settings for a class are the class name and optionally a class stereotype. We'll cover the stereotype concept in the "Stereotypes" section later in this chapter. For now, just consider stereotypes as a way of specifying a commonly occurring subtype of an element. For instance, your class can be of the stereotype COM+, indicating that it's a class specialized to type COM+.

Classes are represented by a box shape, which is divided into three parts:

  • Name

  • Attributes

  • Operations

The name part is self-explanatory. The following sections describe the attributes and operations.

Attributes

Attributes are also known as properties in .NET development. You specify the attributes for the class by selecting Attributes from the Categories list of the UML Class Properties dialog box (see Figure 5-5). In Exercise 5-2, you'll specify attributes for the Customer class. We'll make the Customer class attributes public, in order to make them accessible to the users of the class.

Exercise 5-2
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Attributes category.

  3. Click New to create a new public attribute named Name, of data type VB::String. (You would make the type C#::string, if you wanted to code in C#.)

  4. Click New to create a new public attribute named Address, of data type VB::String (or C#::string for C# code). Figure 5-6 shows the attributes set for the Customer class.

    Click To expand
    Figure 5-6: UML Class Properties dialog box with attributes for the Customer class

  5. You can generate new code for the Customer class by selecting UML ®Code ® Generate. In the Generate dialog box (shown earlier in Figure 5-2), choose Visual Basic as the target language, check the Customer check box, specify the path as \EDWVSNETUMLMSF\Chapter 05\, and click OK. VEA then generates the code, as shown in Figure 5-7.

    Click To expand
    Figure 5-7: Generated code for the Customer class with attributes

End example

After you've generated the code, you'll notice that there are now two VB code files: Customer.vb and Customer~1.vb. The newest generated file will be Customer.vb. VEA renames existing files with a tilde and number: Customer~1.vb,Customer~2.vb, and so forth.

Start Sidebar
Stateless Classes

If a class has attributes, it must keep an instance in memory of every single class instantiation in order to save the attribute values. A class doing this is known as a stateful class. Stateless classes are better for scalability than stateful classes.

Keep in mind that when you're developing enterprise solutions, performance and scalability are always issues. Classes should be stateless. This applies to all kinds of classes, regardless of whether they are COM+ classes, VB/C# classes, Web services, or other kinds of classes. Actually, Web services assume a stateless programming model, although state can be added to a Web service.

If your components must maintain state, the state information can be stored in a database such as SQL Server, or even in a simple text file. If your component is an ASP.NET Web service, you can store state using the built-in ASP.NET functionality for state, using the Session and Application objects.

In the old days (before .NET, that is), Microsoft encouraged developers to use the Shared Property Manager (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cossdk/htm/pgservices_spm_5stu.asp ) to store state. The Shared Property Manager functionality is still available in .NET through the System.EnterpriseServices namespace, which provides you with important infrastructure for enterprise applications. However, the Shared Property Manager does not do well when it is accessed heavily, especially in enterprise environments with multiple processors and servers. This is simply because it doesn't scale very well. Microsoft suggests that you do not use the Shared Property Manager for storing database connection string information, which will be accessed frequently. We recommend storing state in the database, rather than using the Shared Property Manager.

End Sidebar

Operations

Operations are often referred to as methods. Technically, the operation is the interface, and the method is the code, but these terms are often used interchangeably. In UML class modeling, an operation can be one of the following .NET types:

  • Constructor

  • Destructor

  • Event[1]

  • Procedure

  • Property procedure

You specify the operations for the class by selecting Operations in the Categories window of the UML Class Properties dialog box (shown earlier in Figure 5-5). In Exercise 5-3, you'll specify operations for the Customer class.

Exercise 5-3
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Click New to create a new public operation named GetList, of data type VB::Object (C#::object if you want to code in C#).

  4. Click New to create a new public operation named CustomerStatus, of data type VB::Boolean (C#::bool if you want to code in C#).

  5. Click New to create a new public operation named New. This will be our class constructor. (If you want to code in C#, the name doesn't matter; the code generator will ignore it and name the constructor after the class.)

  6. Click New to create a new public operation named Finalize. This will be our class destructor. (Again, If you want to code in C#, the name doesn't matter, because the code generator will ignore it and name the destructor after the class.) Your dialog box should look like Figure 5-8.

    Click To expand
    Figure 5-8: UML Class Properties dialog box with operations for the Customer class

    Note

    In general, you don't need to override the default destructor in your .NET classes. You would need to do this only when you need to perform some sort of housekeeping, such as destroying any references to classes in COM components. However, we create a class destructor in this example, just to demonstrate how it is done.

  7. Click OK.

End example

The GetList operation is a method that provides you with a DataSet of all customers of a certain type. You specify the type via a parameter setting when calling the operation. You specify that an operation expects a parameter via the UML Operations Properties dialog box (which appears when you select the operation and click the Properties button in the Operations category of the UML Class Properties dialog box). In Exercise 5-4, you'll specify a parameter for GetList.

Exercise 5-4
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Select the GetList operation.

  4. Click Properties to open the UML Operation Properties dialog box, as shown in Figure 5-9.

    Click To expand
    Figure 5-9: UML Operation Properties dialog box

  5. Select the Parameters category.

  6. Click New to create a new parameter customerTypeID of data type VB::Integer (C#::int if you want to code in C#). Set the Kind to in, for in-going (read-only), as shown in Figure 5-10.

    Click To expand
    Figure 5-10: UML Operation Properties dialog box with the customerTypeID parameter

  7. Click OK twice.

End example

Setting the parameter Kind to in indicates that it's an in-going (read-only) parameter. When generating code for this class, you want this operation to be a method. You can tell VEA that the code generation engine must create this operation as a procedure (method) through the Code Generation Options of the UML Operation Properties dialog box. Exercise 5-5 shows how to make sure GetList is a method.

Exercise 5-5
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Select the GetList operation.

  4. Click Properties to open the UML Operation Properties dialog box (see Figure 5-9).

  5. Select the Code Generation Options category.

  6. Select Visual Basic (or C#, if you prefer) from the Target language list.

  7. Select Procedure from the Kind list. Your code generation settings should look like Figure 5-11.

    Click To expand
    Figure 5-11: UML Operation Properties dialog box with code generation settings

  8. Click OK twice.

  9. Click the Preview code button to see what the generated code will look like, as shown in Figure 5-12. If you choose C# as the target language, the code generation preview will look like the code shown in Figure 5-13.

    Click To expand
    Figure 5-12: Code preview for the GetList operation (VB code)

    Click To expand
    Figure 5-13: Code preview for the GetList operation (C# code)

End example

The operation will be generated as a public Function[2] procedure, because you've specified that the procedure has a return value (it will be generated as a Sub[3] procedure if it doesn't return anything).

CustomerStatus is an operation showing the customer's online status. This operation will be a property of the class. To make sure the code generation engine generates it as a property, you can specify this in the UML Operation Properties dialog box. You'll do this in Exercise 5-6.

Exercise 5-6
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Select the CustomerStatus operation.

  4. Click Properties to open the UML Operation Properties dialog box (see Figure 5-9).

  5. Select the Code Generation Options category.

  6. Select Visual Basic (or C#, if you prefer) from the Target language list.

  7. Select Property from the Kind list.

  8. Check the Create Get Method option. Your dialog box should look like Figure 5-14.

    Click To expand
    Figure 5-14: UML Operation Properties dialog box for the CustomerStatus operation

  9. Click OK twice.

  10. Click the Preview code button to see the code shown in Figure 5-15.

    Click To expand
    Figure 5-15: Code Preview for the CustomerStatus operation (VB code)

End example

In the UML Operation Properties dialog box (Figure 5-14), you can choose if you want to create Set or Get methods. A Set method allows you to set the property,and a Get method allows you to get/read the property. This particular property should be read-only, so you just need to check the Create Get Method option.

As you learned earlier, operations can also be of type constructor or destructor. Aconstructor is responsible for setting an object to its initial state. In other words, a constructor is a method that is called when the object is created. (Class instantiation is another term for this.) In VB, the constructor is named New. Although you can call the operation anything you like in VEA, the constructor will always be called New, once the code is generated,[4] so you might as well call it New in the first place, if you're working with VB code. As noted earlier, in C#, a constructor is named after the class. In Exercise 5-7, you'll specify that the New operation is a constructor.

Exercise 5-7
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Select the New operation.

  4. Click Properties to open the UML Operation Properties dialog box (see Figure 5-9).

  5. Select the Code Generation Options category.

  6. Select Visual Basic (or C#) from the Target language list.

  7. Select Constructor from the Kind list.

  8. Click OK twice.

  9. Click the Preview code button to see the code shown in Figure 5-16.

    Click To expand
    Figure 5-16: Code preview for the New constructor (VB code)

End example

A destructor operation is called when the class is destroyed. Well, at least in theory; it might not be called, depending on how the object was disposed of. In VB, the destructor will be generated as a method with the name Finalize. If you're working with C#, it will be named after the class. In Exercise 5-8, you'll specify that the Finalize operation is a destructor.[5]

Exercise 5-8
Start example

  1. Open the UML Class Properties dialog box for the Customer class by double-clicking the class.

  2. Select the Operations category.

  3. Select the Finalize operation.

  4. Click Properties to open the UML Operation Properties dialog box (see Figure 5-9).

  5. Select the Code Generation Options category.

  6. Select Visual Basic (or C#) from the Target language list.

  7. Select Destructor from the Kind list.

  8. Click OK twice.

  9. Click the Preview code button to see the code shown in Figure 5-17.

    Click To expand
    Figure 5-17: Code preview for the Finalize destructor (VB code)

End example

Notice in Figure 5-17 how the Overrides keyword is automatically added to the operation signature, because the operation is a destructor. All .NET Frameworkclasses inherit from the Object base class, which has an overridable destructor, so you must override it; you cannot shadow it.[8]

Note

Please see your .NET Framework documentation for more information about the Finalize method, destructors, and garbage collection.

Listing 5-1 shows the complete code generated for the Customer class. To generate the code, select UML ® Code ®Generate. In the Generate dialog box (shown earlier in Figure 5-2), choose Visual Basic as the target language, select the Customer option, specify the path as \EDWVSNETUMLMSF\Chapter 05\, and click OK.

Listing 5-1. Code Generated for the Customer Class
Start example
 1 Namespace MyNamespace
 2
 3    Public Class Customer
 4
 5       Public Name As String
 6
 7       Public Address As String
 8
 9       Public Function GetList (ByVal customerTypeID As Integer) As Object 10 11 End Function
12
13       Public ReadOnly Property CustomerStatus () As Boolean
14          Get
15
16          End Get
17
18       End Property 19 20 Public Sub New ()
21
22       End Sub
23
24       Protected Overrides Sub Finalize ()
25
26       End Sub
27
28    End Class
29
30 End Namespace
End example

Now that you've seen how the packages and classes elements of class diagrams work, we'll look at the final element of these diagrams: relationships.

Relationships

The classes on your class diagrams can have three basic kinds of relationships:

  • Binary association

  • Dependency

  • Generalization

These relationships are discussed in the following sections.

Binary Association

The binary association is the most common class relationship. It simply specifies that (exactly) two classes are associated, meaning that they interact or are related in some way. You usually create a binary association relationship between two classes when an instance of one class eventually will communicate with an instance of the other class.

For example, a Customer class can have a binary association relationship to a ShoppingBasket class, to indicate that an object of type Customer communicates with one of type ShoppingBasket class. Your binary associations can also specify the way that the classes will be implemented. If you double-click a binary association, you'll see the UML Association Properties dialog box, where you can specify the properties for the association, determining not only the business semantics of the association, but also the design decisions about the way the association is implemented.

In Exercise 5-9, you'll add a ShoppingBasket class to your class diagram and give it a binary association relationship to the Customer class.

Exercise 5-9
Start example

  1. Open the MyClassDiagram static structure diagram.

  2. Add a new class named ShoppingBasket to the diagram.

  3. Add a binary association between the Customer and ShoppingBasket classes.

  4. Right-click the binary association and select Shape Display Options from the pop-up menu to open the UML Shape Display Options dialog box.

  5. Select the Name option. Deselect the First end name option and the Second end name option. Then click OK.

  6. Double-click the binary association to open the UML Association Properties dialog box.

  7. Type Buying in the Name field.

  8. Select forward from the Name Reading Direction list.

  9. In the Association Ends section, select the End1 association end and change its name to Customer. Change its multiplicity to 1.

  10. Select the End2 association end and change its name to ShoppingBasket. Change its multiplicity to 0..*. Select the IsNavigable property. Your UML Association Properties dialog box should look like Figure 5-18.

    Click To expand
    Figure 5-18: UML Association Properties dialog box

  11. Click OK.

End example

Figure 5-19 shows the binary association between the Customer and ShoppingBasket classes. The association is named Buying. The association ends indicate how the association will be implemented. By specifying that the ShoppingBasket association end is navigable (IsNavigable is selected), you indicate that the Customer class is able to navigate to the ShoppingBasket class. Furthermore, VEA adds an arrowhead to the association end. The Customer association end isn't navigable, which means that the ShoppingBasket class doesn't have navigation access to the related Customer class. The multiplicity of 1 for Customer means that each instance of ShoppingBasket relates to only one Customer. The multiplicity of 0..* for ShoppingBasket means that each Customer can have zero or many ShoppingBasket instances.

Click To expand
Figure 5-19: Binary association between the Customer and ShoppingBasket classes

If you double-click the Customer class, select the Code Generation Options category in the UML Class Properties dialog box, and click the Preview code button, your generated code will look like Listing 5-2. Remember that you need to connect the association ends to the two classes to generate the code shown in Listing 5-2.

Listing 5-2. Code Generated for the Customer Class with a Binary Association
Start example
 1 Imports TopPackage.MyNamespace
 2 Namespace MyNamespace
 3
 4    Public Class Customer
 5
 6       Public Name As String
 7
 8       Public Address As String
 9
10       Private ShoppingBasket As System.Collections.ArrayList
11
12       Public Function GetList (ByVal customerTypeID As Integer) As Object
13
14       End Function
15
16       Public ReadOnly Property CustomerStatus () As Boolean
17           Get
18
19          End Get
20
21       End Property
22
23       Public Sub New ()
24
25       End Sub
26
27       Protected Overrides Sub Finalize ()
28
29       End Sub
30
31    End Class ' END CLASS DEFINITION Customer
32
33 End Namespace ' MyNamespace
End example

You can see that the binary association is implemented through line 10, which is an array of objects (the instantiated ShoppingBasket classes). If you set the multiplicity of ShoppingBasket to 1, your code will be generated like this instead:

Private ShoppingBasket As MyNamespace.ShoppingBasket

Dependency Relationship

The dependency relationship specifies that one class has a build dependency on another class, but does not maintain a permanent link to an object of that class. Changes to a class will affect all classes that are dependent on that specific class. Usually, the dependency relationship indicates that the dependent class is invoking at least one operation on the class on which it depends. The dependency relationship doesn't have any impact on the code generation, although it features in the project references.

In Exercise 5-10, you'll add two classes, named VIPCustomer and Bonus, to your class diagram and create a dependency relationship between those two classes.

Exercise 5-10
Start example

  1. In the MyClassDiagram static structure diagram, add a new class named VIPCustomer.

  2. Add a new class named Bonus to the diagram.

  3. Add a dependency relationship between the VIPCustomer and Bonus classes.

End example

In Figure 5-20, you can see that the class VIPCustomer is dependent on the Bonusclass. VIPCustomer would be dependent on Bonus, if, for example, Bonus provides access to some customer bonus points that must be present for the VIPCustomer class to function properly. Having the dependency relationship between the VIPCustomerand Bonus classes tells the developers that any changes made to the Bonus class might affect the VIPCustomer class. This fact must be taken into consideration when deciding on whether to implement the change and how it should be tested.

Click To expand
Figure 5-20: Dependency relationship between the VIPCustomer and the Bonus classes

Generalization Relationship

The generalization relationship specifies that a class is a subclass of another class and inherits the base class's public operations and attributes. For example, if you have a base class and you want all other classes to inherit from that class, you'll place a generalization relationship between the two classes. The same applies if your classes represent ASP.NET pages and you want all ASP.NET pages to inherit from a base ASP.NET Web page.

In Exercise 5-10, you added the VIPCustomer class to your class diagram. This class represents important customers who might be involved in a bonus program. Still, VIP customers are indeed customers as well, so inheritance from the Customerbase class makes sense. In Exercise 5-11, you'll add a generalization relationship between the Customer and VIPCustomer classes.

Exercise 5-11
Start example

  1. In the MyClassDiagram static structure diagram, add a generalization relationship between the Customer and VIPCustomer classes.

  2. Double-click the generalization relationship to open the UML Generalization Properties dialog box.

  3. Select inherits from the Stereotype list, to show this stereotype on the diagram.

  4. Click OK.

End example

In Figure 5-21, you can see the VIPCustomer inherits the Customer through the generalization class, and thereby gets access to the operations and attributes from the Customer class.

Click To expand
Figure 5-21: Generalization relationship between the Customer and VIPCustomer classes

In Figure 5-22, you can see the code generation preview for the VIPCustomerclass. Notice that the class inherits from Customer and that it imports the MyNamespacenamespace, because Customer is created within this namespace.

Click To expand
Figure 5-22: Code preview for the VIPCustomer class
Note

For code-generation purposes, you don't need to specify the inherits stereotype. The correct code will be generated as long as you specify the appropriate generalization relationship.

Start Sidebar
Generalization, OOP Inheritance, and Polymorphism

In OOP, inheritance is modeled via generalization. You can create multiple inheritances (nested). However, too many levels of inheritance make your code and model difficult to read and maintain. You should avoid nesting inheritance more than three levels deep.

You can inherit a class you don't even have the source code for and use it in your own class. Can you see the advantage? Find a class that almost does what you want. Create your own class that inherits from the one you've found, and add the functionality it's missing. This is the essence of OOP.

Polymorphism is tightly related to inheritance. Polymorphism means that an operation can exist in several versions. For example, suppose that you have a class named SoccerPlayer with an operation named Run. The Run operation tells the soccer player where to run. If the player is a defender, he will run to a different location on the field than a midfielder will run. So, add two more classes called Defender and Midfielder, both inheriting from the SoccerPlayer class. Wouldn't it be nice if both classes have an operation called Run that overrides the Run operation from the SoccerPlayer class? Yes, it would, because that way, you only need to call the Run operation in your program, and your player will always run to the right location. This is polymorphism, because your Run operation exists in different versions and overrides the parent Run operation.

To implement polymorphism, simply add an operation with the same name in both the parent class and the child class, and mark the operation in the parent class as IsPolymorphic (from the UML Class Properties dialog box or the UML Operation Properties dialog box). The code generator adds the Overridable keyword to the operation in VB; no keyword is necessary in C#.

End Sidebar

[2]This is true for all UML CASE tools and not just a disadvantage for VEA users.

[1]In VEA, events are operations, because of UML 1.2 compliance. However, this isn't the case in UML 1.4 and later.

[2] Methods are functions by default in C#.

[3] In C#, this is a method with the void keyword in the signature to indicate that it doesn't return a value.

[4] Well, your code wouldn't work as intended if not, would it?

[5]With garbage collection, the Finalize method isn't really a destructor in the true sense, but we'll stay with the OOP terminology.

[8]Shadowing means that the operation in the base class with the same name as an operation in the derived class is hidden, but still accessible. A shadowed operation can be called directly from the caller of the derived class, unlike an overridden operation, which can be called only on the derived class.


Statechart Diagrams

A statechart diagram is created to identify and document the internal behavior of an object. This way, you can get an overview of the object life cycle and identify the functionality to be implemented. Statechart diagrams are popular when developing truly object-oriented software, because they describe the dynamic behavior of an object in detail.

The content of a statechart diagram is a sequence of states that the object goes through during its lifetime. Legal state changes are shown by transitions. Events cause the object to change from one state into another. Statechart diagrams consist of the following:

  • States

  • Transitions

  • Decisions

Figure 5-23 shows a statechart diagram with these elements. The following sections describe how they work.

Click To expand
Figure 5-23: Statechart diagram

States

States are "situations" an object can be in. For example, if you have an Invoiceobject, it can be in the "Due for payment" state, if it has reached the due date for payment. If the customer pays the invoice, the Invoice object transitions to the "Paid" state, which means it can no longer be opened for editing.

A statechart diagram must consist of one initial state and may have one or more final states. In Exercise 5-12, you'll create a statechart diagram and add states to it.

Exercise 5-12
Start example

  1. Open VEA, if is not already open.

  2. Create a statechart diagram (static structure diagram) named MyStatechartDiagram.

  3. Drag an Initial State shape onto MyStatechartDiagram.

  4. Drag a State shape onto MyStatechartDiagram and double-click the shape to open the UML State Properties dialog box.

  5. Type Due for payment in the Name field and click OK.

  6. Add two more State shapes and name them Paid and Unpaid.

  7. Drag a Decision shape onto MyStatechartDiagram.

End example

In Figure 5-23, you can see an Initial State shape, which is the starting point, illustrated by a solid dot, and a Final State shape, illustrated by a solid dot surrounded by a circle (colloquially called the fried egg). In between are the states the Invoice object goes through: Paid and Unpaid.

Transitions

You create transitions to specify how the object transitions from one state into another. Actually, a transition represents an event. Something happens (triggers) the object to transition into a new state. You may attach more than one transition from a state, if the transitions are unique and the triggering events are different. In Exercise 5-13, you'll add transitions to your statechart diagram.

Exercise 5-13
Start example

  1. On MyStatechartDiagram, create a transition between the initial state and the Due for payment state.

  2. Create a transition between the Due for payment state and the Decision shape.

  3. Create a transition between the Decision shape and the Paid state.

  4. Create a transition between the Decision shape and the Unpaid state.

  5. Create a transition between the Paid state and the final state.

  6. Create a transition between the Unpaid state and the final state.

End example

In Figure 5-23, you can see transitions, illustrated by solid lines with arrowheads, pointing to the new states. Transitions can also contain guard expressions, as explained in the next section.

Decisions

Decisions are created to illustrate that a transition can end in one of several possible states, depending on a decision. When creating a decision, you must add guard expressions to the transitions going out from the decision; otherwise, you would not be able to tell from the diagram which rule decides which state the transition leads to. Guard expressions specify a condition for the transition; that is, when a transition can occur. In Exercise 5-14, you'll add decisions to your statechart diagram.

Exercise 5-14
Start example

  1. On MyStatechartDiagram, double-click the transition between the Decision shape and the Paid state to open the UML Transition Properties dialog box.

  2. Select Pseudocode from the Language list and select the Guard option.

  3. Type If payment is registered in the Body text field. The UML Transition Properties dialog box should look like Figure 5-24.

    Click To expand
    Figure 5-24: Guard expression for outgoing transition

  4. Click OK.

  5. Double-click transition between the Decision shape and the Unpaid state to open the UML Transition Properties dialog box.

  6. Select Pseudocode from the Language list and select the Guard option.

  7. Type If payment is not registered in the Body text field.

  8. Click OK. The MyStatechartDiagram should now look like the one shown in Figure 5-23.

End example

The Decision shape is a diamond. In Figure 5-23, you can see a Decision shape indicating that the transition from the Due for payment state can transform into two different states, depending on the payment status.


Component Diagrams

In the old days (before .NET, that is), components always referred to COM+ components in a Microsoft enterprise environment. These components could be implemented as .exe or .dll files. When developing .NET applications, you can still create COM+ components (in fact, you'll often need to use existing COM+ components when developing enterprise applications), but you'll also develop classes in .NET and Web services.

In .NET, the classes and Web services (.NET components) are not deployed in .dll files as COM+ components are. Instead they are deployed in assemblies, which are the smallest possible unit of deployment in .NET, and, in fact, they are often .dll files. Is this confusing? Well, just think of assemblies as physical files.
[9] NET assemblies can consist of one or more physical files, or even be in dynamic assemblies that are contained in memory. However, for the sake of this discussion, an assembly equals one physical file.Assemblies contain the metadata in a data structure called manifests. This means that .NET components are self-describing and don't need to be registered on the server; you simply copy the assemblies to the server. This is often referred to as the .NET way to eliminate the infamous DLL hell, by the way.[10]

Note

Shared assemblies still need to be "installed" in the Global Assembly Cache (GAC). See your .NET Framework documentation for more information.

The purpose of creating component diagrams is to show how you'll implement your components (which contain classes). Components consist of one or more classes, which, in turn, can be instantiated in your application.

Let's say you have 20 classes in your application (diagrammed in your class diagram, a static structure diagram in VEA). Before physically implementing your classes, you'll need to decide which classes will be implemented in which physical files. That's exactly what you do in the component diagrams. So, in fact, generating code doesn't make much sense unless you've decided in which components you want to implement your classes; otherwise, you don't know which physical files to generate.[11]

When developing .NET solutions, your component diagrams will represent COM+ .dll files and assemblies (which are often .dll files as well). Component diagrams consist of the following:

  • Components

  • Nodes

  • Dependencies

  • Interfaces

A component diagram may represent all the components or just some of the components in a system. Figure 5-25 shows an example of a component diagram.

Click To expand
Figure 5-25: Component diagram

Components

The key element of component diagrams is the component element. A component element represents some kind of software. It can represent a code module, an executable, a DLL, and so on. The following are the key properties of a component:

  • Name: Typically, the physical name of the file (such as customer.dll)

  • Stereotype: Specifies the subtype of the component, for example, EXE or DLL

  • Nodes: Specifies on which node (server) the component will be implemented

  • Classes: Specifies which classes make up your component

These properties are all accessible from the UML Component Properties dialog box, which opens when you double-click a component on a diagram.

In Exercise 5-15, you'll create a component diagram and add three component elements.

Exercise 5-15
Start example

  1. Open VEA, if isn't already open.

  2. Create a component diagram named MyComponentDiagram.

  3. Add a component named Component1 to the diagram.

  4. Add a component named Component2 to the diagram.

  5. Add a component named Imageshrink.dll to the diagram.

End example

You can see the notation of each component in Figure 5-25.

Nodes

The node element identifies a physical, runtime object representing a processing resource. A node will typically be a server on which your components are processed or to which they are related. The following are some of the key node properties:

  • Name: The name of the node

  • Location: The node location

  • Components: Specifies which components are related to the node

In Exercise 5-16, you'll add a node to your component diagram, and then specify which component will execute on this node.

Exercise 5-16
Start example

  1. On MyComponentDiagram, add a node named Node1.

  2. Double-click Node1 to open the UML Node Properties dialog box.

  3. Select the Components category.

  4. Select Imageshrink.dll, as shown in Figure 5-26.

    Click To expand
    Figure 5-26: Components category of the UML Node Properties dialog box for Node1

  5. Click OK.

End example

You can see the notation of the node in Figure 5-25. Because you set the Components property for Node1 to the Imageshrink.dll component, the Imageshrink.dll file will execute on this server/node.

Dependencies

Dependency is a relationship indicating that one element is dependent on another element to function. Say Component1 is dependent on Component2, which means that changes in Component2 will affect Component1, because Component1 uses services orfacilities in Component2, and not the other way around.

For example, you might have a component in which some of the classes call a class in another component. Well, why not package all classes in the same component then?[12] It defeats the idea of creating unique components that hold only classes that can be grouped because they expose the same kind of functionality. It's like when you're at the grocery store; you don't look for apples in the basket with oranges, do you?

Establishing dependencies has another benefit in that if your component crashes, it will directly affect only one type of functionality. It shouldn't bring other types of functionality down with it.

In Exercise 5-17, you'll add a dependency between two components in your component diagram.

Exercise 5-17
Start example

  1. Open MyComponentDiagram.

  2. Add a dependency between Component1 and Component2.

End example

In Figure 5-25, you can see that Component1 is dependent on Component2, illustrated by the dependency (dashed line).

Interfaces

Of course, you know about your model's public interfaces by looking at your public functions in the classes. However, if you have a component representing a third-party DLL, you might not know about the public interfaces, because you haven't modeled the classes and functions. That's when the interface element of a component diagram can be useful.

Like any class, an interface needs at least one operation, and operations can have parameters. In Figure 5-25, the Imageshrink.dll component represents a COM+ component purchased from an external vendor. The _Imageshrink interface isthe COM+ type library. A type library is required to expose the interfaces to users of the component. The interfaces exposed are illustrated as operations on the Interface shape. In Exercise 5-18, you'll add an interface that has one public operation, Shrink, to your component diagram. This operation will represent a function and have three parameters.

Exercise 5-18
Start example

  1. On MyComponentDiagram, add an interface named _Imageshrink to the Imageshrink.dll component. The Interface shape is the lollipop, as shown in Figure 5-25.

  2. Double-click the _Imageshrink interface to open the UML Interface Properties dialog box.

  3. Select the Operations category.

  4. Click New to add a new operation named Shrink, of data type VB::Object (C#::object if you want to code in C#), as shown in Figure 5-27.

    Click To expand
    Figure 5-27: Operations category of the UML Interface Properties dialog box

  5. Click OK.

    Note

    You can't tell from the Model Explorer whether the operation returns a value. You need to open the UML Operation Properties dialog box to get that information.

  6. Double-click the _Imageshrink interface to open the UML Interface Properties dialog box and select the Operations category again.

  7. Select the Shrink operation.

  8. Click Properties to open the UML Operation Properties dialog box.

  9. Select the Parameters category.

  10. Click New to add a new in-going parameter named BMPImage of data type VB::Object (or C#::object if you want to code in C#).

  11. Click New to add a new in-going parameter named ShrinkPercentage of data type VB::Integer (or C#::int if you want to code in C#). Your UML Operation Properties dialog box should look like Figure 5-28.

    Click To expand
    Figure 5-28: Parameters category of the UML Operation Properties dialog box

  12. Click OK twice. In Figure 5-29, you can see how the _Imageshrink interface looks in the Model Explorer.

    Figure 5-29: Interface shown in the Model Explorer

    Note

    As you can see in the Model Explorer, the Shrink interface has three parameters: Shrink, BMPImage, and ShrinkPercent. What you can't tell from the Model Explorer is if a parameter is an input or output parameter. You need to open the UML Operation Properties dialog box to see this information.
End example

When developing COM+ components to run in the COM+ runtime environment of Component Services, you need to instantiate the ObjectControlinterface of the COM+ runtime environment and add three operations to your component: Activate, Deactivate, and CanBePooled. In Figure 5-30, you can see how the ObjectControl interface could be added to the Imageshrink.dll component in our example. You'll add the ObjectControl interface in Exercise 5-19, in the next section.

Click To expand
Figure 5-30: COM+ component with the ObjectControl interface

Code Generation from a Component Diagram

If you generate code from your component diagram alone, you can generate code for only the interfaces, not the components. This is very logical if you think about it, because the components on your component diagram just represent the physical file containing the classes and interfaces.

To generate code for your interfaces, select UML ® Code ® Generate. You can choose which model elements to generate code for from the Generate dialogbox. Figure 5-31 shows the Generate dialog box set for generating code for the _Imageshrink interface to the \EDWVSNETUMLMSF\Chapter 05\ path.

Click To expand
Figure 5-31: Generate dialog box with the _ImageShrink interface selected

After clicking OK in the Generate dialog box, you can open the code file in VS .NET (or any text editor, like Notepad, for that matter) from the path you've just specified. Figure 5-32 shows the _Imageshrink.vb file generated for the _Imageshrink interface using the settings in Figure 5-31.

Click To expand
Figure 5-32: VB code generated for the _Imageshrink interface

However, generating code for interfaces alone doesn't make much sense if your interface is connected to one of your own classes. It's more relevant to generate code for the class that incorporates the interface. In Exercise 5-19, you'll create a new class diagram with the Class1 class and incorporate the _ImageShrinkand ObjectControl interfaces described in the previous section. Then you'll generate the code for that class.

Exercise 5-19
Start example

  1. In VEA, create a class diagram named ClassInterfaceDiagram.

  2. Add a class named Class1 to the diagram.

  3. Add the _Imageshrink interface to the diagram, attaching it to Class1. You can copy the interface from the MyComponentDiagram diagram you created in the previous Exercises.

  4. Add an interface named ObjectControl to Class1.

  5. Double-click the ObjectControl interface to open the UML Interface Properties dialog box, and then select the Operations category.

  6. 6. Add three operations to the ObjectControl interface named Activate, Deactivate, and CanBePooled. (See Exercise 5-18 for instructions on how to add the operations.) Your diagram should now look like Figure 5-33.

    Click To expand
    Figure 5-33: Class diagram with Class1 class incorporating the ObjectControl and _Imageshrink interfaces

  7. Double-click Class1 to see its properties, as shown in Figure 5-34. As you can see, Class1 doesn't have any operations. All the operations shown in Figure 5-33 are implemented from the interfaces. Click Cancel to close the dialog box.

    Click To expand
    Figure 5-34: UML Class Properties dialog box for Class1, showing the class does not have any operations

  8. Select UML® Code ® Generate. In the Generate dialog box, select only Class1 in the tree view, and then click OK. Your generated code will look like the code in Figure 5-35.

    Click To expand
    Figure 5-35: Code generated for Class1 including interfaces

End example

As you can see, the code listed in Figure 5-35 makes more sense than the code listed in Figure 5-32. The code in Figure 5-35 shows how the class implements the interfaces and that the Shrink operation is automatically generated.

[10]"DLL hell" refers to the annoying struggle of registering and unregistering the different versions of .dll files in the Registry, often resulting in a DLL version incompatible with the application being registered. .NET solves this by making the assemblies (DLLs) self- describing through the use of a manifest, which means that registration is no longer necessary, and allows the use of side-by-side assemblies, or private assemblies.

[11]VEA allows you to generate code without assigning your classes to components. You simply choose the physical file names when generating code.

[12]To some extent, this will prevent you from distributing your classes to different physical machines. This isn't entirely true, however, because the same component can be running different machines at the same time.


Deployment Diagrams

The component diagram shows how the components are physically grouped and implemented. A deployment diagram takes this a step further and shows how the hardware and software elements of your solution will be configured and implemented. You can see how your components will be implemented in the runtime environment. As a rule of thumb, each UML model should contain only a single deployment diagram showing how the solution will look like from a runtime point of view.

A deployment diagram basically consists of three elements:

  • Nodes

  • Components

  • Relationships

Figure 5-36 shows elements in a deployment diagram, as discussed in the following sections.

Click To expand
Figure 5-36: Deployment diagram with two different node types

Nodes

Nodes in deployment diagrams represent hardware components capable of executing software code. The notation of a node is a shaded, three-dimensional box. You can choose between two types of node elements:

  • The node element, which represents a specific type of node, for example, a server

  • The node instance element, which represents an instance of a node type

In Exercise 5-20, you'll create a deployment diagram and add a node element and a node instance element.

Exercise 5-20
Start example

  1. Open VEA, if it is not already open.

  2. Create a deployment diagram named MyDeploymentDiagram.

  3. Add a node named Server to the diagram.

  4. Add a node instance named Web Server Alpha to the diagram. Your deployment diagram should look like Figure 5-36.

End example

As you can see in Figure 5-36, the node named Web Server Alpha is a node instance element and, as such, an instance of the Server node.

Note

In the Model Explorer, you can see only node elements, not node instance elements. This is because node instance elements are simply instances of other node elements.

Components

You can add components to your deployment diagram to specify on which servers the components will be physically running. As is the case with nodes, there are two kinds of components:

  • The component element represents a physical component.

  • The component instance element represents a runtime instance of a physical component.

You can document on which server (node) the components will be running by applying them to the specific node.

In Exercise 5-21, you'll add two components to your deployment diagram: Customer and Discount (see Figure 5-35).

Exercise 5-21
Start example

  1. On MyDeploymentDiagram, add a component named Customer.

  2. Add a component named Discount to the diagram.

  3. Double-click the Customer component to open the UML Component Properties dialog box.

  4. Select the Nodes category.

  5. Select the Server node. The UML Component Properties dialog box should now look like Figure 5-37.

    Click To expand
    Figure 5-37: UML Component Properties dialog box

  6. Click OK.

End example

In the Exercise, you used the UML Component Properties dialog box to specify on which node the Customer component would run. Another way to do this is through the UML Node Properties dialog box. Double-click the node on which the component is running and select the Components category, as shown in Figure 5-38.

Click To expand
Figure 5-38: UML Node Properties dialog box

Relationships

Deployment diagrams have two basic relationship types:

Communicates: The communicates relationship is for specifying how two elements communicate with each other. In Figure 5-36, you can see a communicates relationship between the two node elements. This indicates that the two nodes are communicating with each other. Actually, when placing a communicates relationship between two nodes (which represent hardware components, remember?), it usually means that the two nodes are connected in some way. That's why we've made the example of a server connected to an overhead projector (for example, using USB). Figure 5-36 also shows a communicates relationship between the Server component and the Customer component, illustrating that the component is installed on the server and is processed there.

Dependency: The dependency relationship specifies a dependency between two elements. In Figure 5-36, the Customer component is dependent on the Discount component, and therefore affected by its availability or by changes to its functionality. You can use the dependency relationship freely to specify important issues, helpful for your implementation. For example, in Figure 5-36, we've added a dependency relationship between the Server node and the Web Server Alpha node instance to indicate that the server implementation will take place on the server named Web Server Alpha.

In Exercise 5-22, you'll add relationships to your deployment diagram.

Exercise 5-22
Start example

  1. On MyDeploymentDiagram, add a communicates relationship between the Server and Overhead Projector nodes.

  2. Right-click the relationship and select Shape Display Options from the pop-up menu to show the Shape Display Options dialog box.

  3. Deselect the following options: First end name, Second end name, and End multiplicities. Then click OK.

  4. Add a communicates relationship between the Server node and the Customer component.

  5. Right-click the relationship and select Shape Display Options from the pop-up menu to show the Shape Display Options dialog box.

  6. Deselect the First end name, Second end name, and End multiplicities options. Then click OK.

  7. Add a dependency relationship between the Server node and Web Server Alpha node instance.

  8. Add a dependency relationship between the Customer and Discount components. MyDeploymentDiagram should now look like Figure 5-36.

End example


Stereotypes

We have mentioned stereotypes several times in this chapter and previous chapters. Stereotypes are simply a subtype you specify for a type.

For example, a use case is of the type Use Case. If you then specify the stereotype to be Business Use Case, the use case is still a use case, but it's a use case of the type Business Use Case. Similarly, you can specify that a class is a Class but also a class of the type struct.

Stereotypes are just a way for you to specify subtypes for your types. The notation for a stereotype is <<stereotype name>>. Stereotypes exist for almost all elements. You can apply the built-in stereotypes provided by VEA or define your own stereotypes, as described in the following sections.

Built-in Stereotypes

The built-in stereotypes are predefined by VEA and vary from element type to element type. For example, the struct stereotype is one of the stereotypes available for classes in the UML Class Properties dialog box, as shown in Figure 5-39.

Click To expand
Figure 5-39: Stereotypes in the UML Class Properties dialog box

Figure 5-40 shows the Class1 class with the struct stereotype.

Click To expand
Figure 5-40: Class1 class with the struct stereotype

User-Defined Stereotypes

Creating your own stereotypes is useful if you want to specify a stereotype for a commonly used element that is not predefined by VEA. For example, you might want to specify that a class will be implemented as an ASP.NET page. VEA doesn't have a built-in stereotype to represent an ASP.NET page, but you can easily create one. The only disadvantage of using user-defined stereotypes is that, because VEA doesn't know about the user-defined stereotypes, they can't be reflected in the generated code. In other words, it's a visual thing only.

To create a new stereotype, select UML ® Stereotypes to open the UML Stereotypes dialog box, as shown in Figure 5-41. Then click New. Type the stereotype name in the stereotype field of the new stereotype row, which is created at the top of the Stereotypes list. The important thing to remember is to choose to which base class the new stereotype belongs from the Base Class list; otherwise, it will not be accessible from the Stereotype list for the element.

Click To expand
Figure 5-41: UML Stereotypes dialog box

In Figure 5-42, you can see that the Class1 class has the ASP.NET Page stereotype.

Figure 5-42: Class1 class with the ASP.NET Page stereotype


UML Code Mapping to .NET

In this chapter, you've learned that some of the UML elements can be mapped directly to the .NET language. In Table 5-1, you can see how some of the UML elements from the structural models map to the .NET language. You'll need to know about code mapping if you want to generate code from your UML diagrams.

Table 5-1. UML Code Mapping to .NET
UML Element | VB .NET Code | C# Code
Package | Namespace keyword | namespace keyword
Class | Class keyword | class keyword
Procedure operation without return parameter (class) | Sub keyword | Prefix procedure name with void keyword
Procedure operation with return parameter (class) | Function keyword | This is the default operation, so no keyword or prefix is necessary
Destructor operation (class) | Sub Finalize procedure | No keyword is necessary; it has the same name as the class, prefixed with a ~character
Constructor operation (class) | Sub New procedure | No keyword is necessary; it has the same name as the class
Event operation (class) | Event keyword | event keyword
Property operation (class) | Property keyword | property keyword
Generalization relation (class) | Inherits | No keyword is necessary; simply add a colon after the class name and then the name of the base class
Attribute (class) | Declare as variable | Declare as variable
Binary association (with bounded multiplicity and IsNavigable selected) |  | Data member (variable)
Binary association (with unbounded multiplicity and IsNavigable selected) |  | Data member(System.Collections.ArrayList)
Abstract operation (class) | MustOverride keyword | abstract keyword
Abstract class | MustInherit keyword | abstract keyword
Operation (IsPolymorphic) | Overridable keyword | virtual keyword
UML data type with <<enum>> stereotype | Enum keyword | enum keyword
UML class with <<struct>> stereotype | Structure keyword | struct keyword
Interface | Interface keyword | interfacekeyword
Attribute (class, with frozen setting set) | Const keyword | const keyword
Attribute (multiplicity set to [*]) | Data member (System.Collections.ArrayList) | Data member (System.Collections.ArrayList)
Delegate (class with <<delegate>> stereotype) | Delegate keyword | delegate keyword
Union (class with <<union>> stereotype) | union keyword (C++ Managed Extensions only) | union keyword (C++ Managed Extensions only)
Struct (class with<<struct>> stereotype) | struct keyword (C++ Managed Extensions only) | struct keyword (C++ Managed Extensions only)

Table 5-2 lists the file types you can generate.

Table 5-2: Code File Types
File Type | File Extension
C# source file | *.cs
C++ source file | *.cpp
Header file | *.h
VB .NET source file * | .vb


Summary

In Chapter 4, you learned about the behavior diagrams, and you saw how the behavior diagrams serve two purposes: they give you an overview of the solution you're planning, and they enable you to create the structural diagrams, because they provide you with information about what happens in your solution.

In this chapter, you've learned about the structural UML models, which describe the static structure of your solution. You've learned how to generate code for your solution by creating the static structure diagram–—the class diagram. You've also seen how the structural diagrams directly build on the information you've gathered for your solution duringthe creation of the behavioral diagrams. Finally, you've seen how the UML elements map to .NET code and declarations.

You've now learned about the UML diagrams in detail. In the next chapter, you'll learn how to plan an enterprise solution with the knowledge you've just obtained.


Chapter 6: Planning a VB .NET or C# Project

Overview

This chapter shows you how to plan a Visual Basic .NET or C# project. The information found in this chapter primarily consists of what you should do and in what order you should do it. You'll find references to many of the other chapters in this book, which also means that this chapter is an overview chapter that binds the information in other chapters together. So, read this chapter as a TO-DO list, but remember that while this is how we most often start out planning our projects, we're not methodology bigots. We don't claim that this is an exhaustive list, nor do we mean to imply that you absolutely must follow all the instructions given for every project. You should go through this chapter with an open mind, taking notes, and then create your own project planning TO-DO list.


The Planning Process

The planning process we'll review in this chapter consists of the following steps:[1]

  • Gather requirements: The first task is to gather requirements for the solution.

  • Design the solution: After you've gathered the requirements, you can design the solution.

  • Code iteration plan: After designing the solution, you need to break up the development process into smaller, easier-to-manage iterations.

  • Prepare for coding: When you have the iterations defined, it's time to prepare for coding.

  • Choose data access: Your choice of data access is often governed by what your client already uses. If not, it's up to you to choose the right data source for the solution, including drivers, providers, and so on.

  • Plan the deployment: Once you've prepared your solution for coding and chosen the data access method, you need to start planning how the solution should be deployed.

  • Set up your test plan: With all the other steps completed, you need to create a test plan for testing your solution.

Now, we'll look at how to accomplish each of these steps in the planning process.

Gathering the Requirements

Your first task is to gather the requirements for the project you're about to plan. This is obviously important, because you cannot possibly create the desired solution, let alone plan it, if you don't understand the customer's requirements. Chapter 2 provides more information about how to go about this, including the steps or phases you should perform to design the desired solution. The steps mentioned in Chapter 2 are based on the MSF, which is covered in detail in Chapter 20.

When you sit down with your customers, it's important that you present them with your ideas and interpretation of their requirements in a way that is easily understood. This is where use case modeling comes to the rescue. Use cases at a high-level perspective are easy to model and understand, so you should use them to communicate your ideas and interpretation of the requirements to customers. You can find more information about use cases in Chapters 3 and 4. Chapter 3 is an introduction to UML, and Chapter 4 is a more thorough examination of the behavioral models of UML, including use cases.

Designing the Solution

When you've finished gathering the requirements, you need to design the solution. Design in this case doesn't mean designing the user interface (UI), although that is part of the design phase. The design we talk about here is the conceptual and, possibly, the logical design. You can find detailed information about solution design in Chapters 2 and 20.

Creating an Iteration Plan

Once you have gathered all the requirements and designed the desired solution, you need to sit down and find out how you can split up the development into four or five[2] parts, or iterations.

The most important iteration is the first one, also referred to as the core iteration, which must contain all the core functionality. This can be tricky, because some of the functionality that is considered part of the core iteration also relies on functionality that really belongs in a different iteration. This means that sometimes you come up with a core iteration that contains maybe two-thirds of all the functionality, which is hardly ever the right approach.

Another consideration for the core iteration is the element that is regarded as the highest risk to the project, whatever that may be. Quite often, this is the fact that customers don't really understand what they are paying for, and you really need to address this in the core or second iteration. A good rule of thumb is the more risky you find a feature, the more likely it is to be a core iteration or second iteration feature. Also, the more difficult you consider a feature to be, the more likely it is to be a core or second iteration feature.

It obviously depends on your customer how much functionality should be put in the core iteration, but experience tells us that usually up to half of the functionality should be included in the core iteration. However, this also depends on the kind of system you're planning. If it deals with security, you obviously need a secure core iteration, and that might mean including up to as much as 80% of the functionality in the core iteration. Often, a small system constitutes including a large percentage of the functionality in the core iteration, but it's up to you as the analyst, in close cooperation with your customer, to work this out.

Despite our reluctance to be cast as methodology bigots, here is one guideline we feel strongly about: You should thoroughly test and get customer sign-off oneach iteration, before proceeding to the next iteration.

Preparing for Coding

Once you've identified the iterations, you should start preparing for coding. There are a number of questions you need to answer, including the following:

  • Which programming language should you use?

  • What project type should you use?

  • Should all projects be in the same solution?

  • Can you find existing reusable code?

  • If your solution may be presented in more than one (spoken) language, do you plan to use resource files?

  • Will your application be used in different countries, which use different formatting of numbers, dates, and times?

Of course, you might have already made some of these decisions, such as the programming language to use, earlier in the process. But these are all important decisions, which are discussed in the following sections.

Choosing the Programming Language(s)

With the advent of the .NET Framework and VS .NET, you now have the same framework and IDE for a number of different programming languages. They all produce the same code once compiled to MSIL, so from that perspective, it doesn't matter which language you choose. Microsoft ships VS .NET 2003 with VB .NET, C#, C++, and J#. This book is exclusively about using VB .NET and/or C#, so we won't be commenting on why you should be using any of the other languages, or even one of the many third-party .NET programming languages.

However, there are a few other issues related to language that you need to consider, including the following:

Multiplatform solutions: Will the solution run on multiple platforms, or do you foresee this as an upcoming request from your customer? If so, you'll need to take into account that currently only C# is being ported to other platforms. We think that it's unlikely that VB .NET will ever be ported to a platform other than Windows.

Development team language skills: The current skills that your development team possesses are obviously another factor that needs to be taken into account when deciding on which programming language(s) to use for developing the solution. If they have only VB .NET skills, the answer will most likely be to develop in VB .NET, unless you have a long- term goal of coaching at least some of your development team to use other languages. If your development team has a Java background, your programming language should probably be C#, as it is quite Java-like.[3]

Unsafe code: Will you be using unsafe code, such as pointers in your solution? Unsafe code is code that bypasses the type safety features of the CLR. If so, you effectively rule out VB .NET, because it doesn't support unsafe code. Perhaps your choice should then be C#. (See your documentation for more information about unmanaged/unsafe code.)

It is very likely that some of the answers conflict, and you then need to figureout which factor has the highest priority. Also, keep in mind that there is no rule that dictates the use of just one programming language in your solution. In fact, it can be to your advantage to use more than one, depending on the factors mentioned here.

Start Sidebar
Learn More Than One Programming Language

It's easy to master more than one .NET programming language. Once you can work with the .NET Framework and are familiar with some of the many namespaces, it's very advantageous to learn at least two languages.

From our experience, most developers using either VB .NET or C# can easily learn the other language. Converting a smaller solution from VB .NET to C# or vice versa is an excellent way of learning a new language. Decent programmers should be able to pick up the new language within a week. That's not to say they will be fluent in the new language, but they will know the basics and where to look for answers to any problems that might arise.

End Sidebar

Choosing the Project Type(s)

Depending on what type of solution you've planned—Web-based, Windows-based, n-tier, traditional client/server, and so on—you need to make sure you choose the right project type(s) for your solution. In many cases, it's fairly easy to make these decisions, and the many templates in the VS .NET IDE certainly help. The "Enterprise Template Projects" section later in this chapter provides an introduction to the VS. NET project templates.

Here is a list of questions that relate to the choice of project type(s):

  • Will you be using Web services to expose functionality? If so, you obviously need to have one or more Web service projects in your solution.

  • Will you be compiling your classes as components? This way, you can encapsulate functionality to be used by any number of projects in your solution or even in other solutions. If so, you should create your solution as a Class Library project, or add a Class Library project to your solution.

  • Will you be creating your own UI controls? This is a good way of extending the behavior of existing controls, if you want to make the new functionality readily available. If so, you need to add one or more Control Library projects to your solution.

  • Will you need to expose some or all of the functionality through a console/ command prompt? If so, the Console Application project is your choice.

  • Do you need to target PocketPCs or SmartPhones? If so, the Smart Device Application project or ASP.NET Mobile Web Application project should be your preferred project template.

Choosing a Single Solution or Multiple Solutions

This is a question you often hear in the Microsoft language newsgroups: Is there any reason why I would choose to have all my projects in the same solution? Thesimple answer is no, because there's no performance penalty if you choose to have them in different solutions.

Note

The newsgroup for VB .NET is news://msnews.microsoft.com/microsoft.public.dotnet.languages.vb. The newsgroup for C# is news://msnews.microsoft.com/microsoft.public.dotnet.languages-.csharp.

Usually, projects are easier to manage when all of their parts are in the same solution, especially if you're debugging. However, if you prefer to have individual developers or developer teams work on their part of the entire solution in "their own" VS .NET solution, then multiple solutions are the way to go.

Looking for Existing Reusable Code

If you follow the MSF phases, you should know if you have any existing components or applications that can be used as part of your solution. Customers might request that you use some of their existing code. Your developers might have created some general functionality, such as file-handling routines, that can be used in most projects. You should identify and use any existing code that is reusable, thus saving yourself expensive development time.

Also keep in mind that a lot of functionality already exists in the many name-spaces in the .NET Framework. Looking through the content of the namespaces might also save you time, because quite often, you can find the required functionality there. Even if you spend a good few hours looking through the namespaces, it will most often pay off. Another benefit of this approach is that it will improve your knowledge of the .NET Framework for later projects.

You should also take into account that you or the customer might have existing COM components that can be reused in the solution.

Using Resource Files

Will your solution be presented in more than one (spoken) language, or do you foresee that this might be a request from the customer sometime after the solution has been developed? If so, it will save you many development hours if you decide up front to use resource files for all your string resources, such as dialog box text, messages, and so on.

Tip

Resource files are not just for strings; they can also be used for graphics, such as icons and images.

Another reason for using resource files is that it's easier to hand the XML-based resource files to a nonprogrammer, such as a translator or documentation specialist for editing. In Figure 6-1, you can see a resource file open in the XML text editor of the XML designer.

Click To expand
Figure 6-1: An XML-based resource file

International Formatting

Will your application be used in different countries? If so, along with the possible need to accommodate different languages, as discussed in the previous section, you also need to consider formatting. Many countries have different formatting of numbers, dates, and times.

Tip

We recommend that you refer to Internationalization and Localization Using Microsoft .NET, written by Nick Symmonds, published January 2002 (ISBN: 1-59059-002-3). For more information about this book, visit http://www.apress.com/book/bookDisplay.-html?bID=62.

Choosing Data Access

In many cases, your customer will already have a database management system (DBMS) and will insist on using that DBMS for the solution if database access is required. Even if the customer hasn't requested a specific DBMS, you'll more than likely already have chosen and agreed on a DBMS for the solution. However, there is still the question of how you access the DBMS from code.

With VS .NET you get ADO.NET, which is a disconnected data access architecture, but you can also choose to use classic ADO through COM Interop services.

Tip

We won't be discussing the pros and cons of using either ADO.NET or COM Interop. You can find more information about these techniques in these two books written by Carsten Thomsen: Database Programming with Visual Basic .NET, Second Edition, published October 2002 (ISBN: 1-59059-032-5), and Database Programming with C# published April 2002 (ISBN: 1-59059-010-4). Another good resource is COM and .NET Interoperability, written by Andrew Troelsen, published April 2002 (ISBN: 1-59059-011-2). For more information about these books, see http://www.apress.com/book/bookDisplay-.html?bID=100, http://www.apress.com/book/bookDisplay.html?bID=63, and http://www.apress.com/book/bookDisplay.html?bID=81, respectively.

If you plan to use ADO.NET, you still need to decide which .NET data provider you will use to access the DBMS.

  • If you use Microsoft SQL Server 7.0 or later, you can choose to use the SQL Server .NET data provider, the ODBC .NET data provider, or the OLE DB .NET data provider. They all come with VS .NET.

  • If you use Oracle 8.1.7 or later, you can use Oracle's own .NET data provider (visit http://otn.oracle.com/tech/windows/Oracle_dotnet.pdf for more information). You can also choose to use the ODBC .NET data provider, the OLE DB .NET data provider, or the Microsoft .NET data provider for Oracle.

  • If you use MySQL, you can use the ODBC .NET data provider, the OLE DB .NET data provider, or native MySQL .NET data providers. You can find more information about the native providers at http://www.mysql.com/articles/dotnet/#ADO.NET.

There are obviously more DBMSs than those listed here. The point is that you often have more than one data provider option, no matter which DBMS you'll be accessing from your solution. So, you need to decide which data provider you will use before any of the developers start coding, or you might end up with a solution that uses more than one data provider for the very same DBMS.

When you work with ADO.NET, you can choose to work with typed DataSetobjects or ordinary DataSet objects. You should decide whether you'll use one or the other, or allow the use of both types, which we recommend. (See the help documentation for more information about the DataSet class.)

Planning Deployment

Deployment of your solution is obviously an important aspect of your solution—your customer won't be fully satisfied until the solution has been deployed and can be used as intended. In general, the deployment has already been discussed when going through the MSF phases (see Chapters 2 and 20), and you should refer to the UML deployment diagram (see Chapter 5), if one exists.

Planning deployment with VS .NET isn't as big a task as it used to be for traditional Windows development. This is because you can now create a deployment project as part of your solution, by adding one of the Setup and Deployment Projects that come with VS .NET, as shown in Figure 6-2. Choose theproject that is the most appropriate to your solution or to your project, if you plan on deploying each of your solution projects. The Setup and Deployment projects can help you with a lot of the general details, such as the name displayed in the dialog boxes, what program groups your application icons should be added to, and so on. See the "Enterprise Template Projects" section later in this chapter for more information about VS. NET templates.

Click To expand
Figure 6-2: VS .NET Setup and Deployment projects

For planning deployment, you need to know the platforms on which you plan to deploy your solutions. This information includes any security issues and other platform-specific details. We cover deployment in detail in Chapter 15.

Testing

In recent years, software testing has received the recognition it deserves. You cannot create good software without proper testing, and generally, you need to spend as much time on testing as you do on development.

Although the principles of deriving tests via equivalence classes, boundary values, decision flows, and so on have been around for years, many recent innovations can help you to improve quality. Use case scenarios are a great source of functional threads and data. Debuggers are now extremely sophisticated. Automated solutions such as static and dynamic analyzers can assess aspects like coverage, memory, and variable usage.

Unit testing is another way of ensuring all parts of your solution work as intended. In general, unit testing means that developers create a test for the input and output of the class they are about to develop. Obviously, the first test will fail, because there is no code. However, developers then keep adding code to the class,[4] until the test succeeds. For VS .NET, you can use NUnit, a unit-testing framework for all .NET programming languages.

Tip

MSDN has a number of good articles about testing, such as "Tools for Capacity Planning" (http://msdn.microsoft.com/library/ default.asp?url=/library/en-us/dnbda/html/ bdadotnetarch081.asp) and "Going Live: Instrumentation, Testing, and Deployment" (http://msdn.microsoft.com/library/ default.asp?url=/library/en-us/dnvsent/ html/foodmovers6.asp). For more information about unit testing, see Beck Testing Framework (http://www.xprogramming.com/ testfram.htm). For NUnit information, see http://www.nunit.org.

Investing in one or more of these software-testing solutions is a good idea, although they can be quite expensive. Ask your colleagues which tools they use and which they recommend. Often, what they use and what they recommend will be different, because managers are generally reluctant to allocate large amounts of money for software testing tools. In the past, such tools were rather inflexible and not portable, and they could take as long as a programming language (or longer) to learn. However, the software and its usability have improved, and long-term trial versions are often available. So, consider trying to convince your company to invest in some decent tools. The money invested in testing tools and training in how to use them will be returned manyfold in terms of fewerbugs in deployed solutions, reputation, lower maintenance costs, and so on.

Caution

Not testing your software is the right way to commit software suicide; don't be a fool! Testing is by far the single biggest task of any software development project. If this isn't true in your company, we seriously suggest that you rethink your strategy.

[1]We would like to hear from you if you have suggestions for how the list might be improved.

[2]Using four or five iterations is only a rule of thumb; there's nothing stopping you from having fewer or more iterations.

[3]Well, there's also J#, but our view is that it's nothing more than a marketing stunt from Microsoft, and that C# will have more support in the future.

[4]Unit testing can be done on any kind of unit, but it's widely recommended and accepted that a unit is a class.


Enterprise Template Projects

As noted in the "Preparing for Coding" section earlier in this chapter, the project templates provided in the VS. NET IDE help you create the correct project type for your solution. Enterprise project templates are a new feature beginning with VS .NET 2002, and we'll cover them in more detail in Chapters 8, 9, and 10. In the meantime, here's a short introduction.

VS .NET Enterprise Developer (VSED) and VS .NET Enterprise Architects (VSEA) editions both come with a number of enterprise template projects that are targeted at different types of solutions, as shown in Figure 6-3. An enterprise template project should be used when you want to guide and/or restrict your developers in what projects, project items, controls, and other elements they can add to a solution. In other words, these templates are associated with establishing and maintaining enterprise coding standards.

Click To expand
Figure 6-3: Enterprise template projects

Template projects offer a unique way of ensuring that your developers do as you want them to do. One example is that you can prevent developers from adding Web service projects or the Windows data grid to your solution.

If you have VSEA, you can even create your own enterprise template projects and be very specific about how your solution should be created. Although you cannot create enterprise template projects with VSED, you can still use the ones you create with VSEA in VSED.


Configuration Files

Configuration files can ease maintenance of your projects and the external resources they use, such as database servers. You can store various types of information in your configuration files and thus dynamically change the setup of your project. Although strictly speaking configuration files are not part of the planning process, they are something you should consider using in your projects.

The .NET Framework has a number of configuration files (with the extension .config) that you can use for storing general application configuration information. These files are XML-based. You should consider them as a replacement for the Registry when you are configuring custom applications, especially if you plan to use your solution on platforms other than Windows.

There are three general types of configuration files: machine, application, and security. Figure 6-4 shows an example of a typical application-specific configuration file for a Web project, the Web.config file.

Click To expand
Figure 6-4: The Web.config configuration file

As you can see from Figure 6-4, the standard configuration files hold a lot of information, such as security setup. You can use these configuration files to store any kind of information, such as database connection strings, but they can also be used for a new concept called dynamic properties.

Dynamic properties are generally used for UI control properties. You can then set up these properties to be read from a configuration file. If you do, you can change the value of a property, andthus make changes to the UI without recompiling your solution. For example, you could set up dynamic properties for a Label control on a Windows form, such as the control shown in Figure 6-5.

Figure 6-5: Label control on a Windows form

To access dynamic properties for a control, open the Properties dialog box for the control and click the ellipsis (...) button, as shown in Figure 6-6. This brings up the Dynamic Properties dialog box, as shown in Figure 6-7.

Click To expand
Figure 6-6: Accessing dynamic properties for a control
Click To expand
Figure 6-7: Dynamic Properties dialog box

Figure 6-7 shows the Dynamic Properties dialog box with the Text property of the Label1 control set up as a dynamic property. When you set up a property as a dynamic property, it is added to the configuration file for the project, as shown in Figure 6-8.

Click To expand
Figure 6-8: The app.config configuration file with a dynamic property

In Figure 6-8, you can see that the Text property of the Label1 control has been added as an XML node. This means that you can change the Text property dynamically by changing the text for the value attribute. This is a simple but very powerful technique.

Tip

We highly recommend that you use configuration files as a part of your solution. They provide an excellent way of extending and changing your solution without recompiling it.


Maintenance

Maintenance is an important part of how your customers perceive you and your solutions, and thus should be part of your planning. As is the case with good testing, it's also vital that you plan how to upgrade your solutions once new versions are released, as well as how to manage patches. We'll cover how to deploy new releases and patches in Chapter 15. Here, we'll look at how to get information from your customers that indicates that a patch is needed or that a new feature is desirable.

Finding Out About New Functionality

You can collect information about functionality for a new release of an existing software solution in many ways. Here's a short list of some procedures we've come across:

  • Set up a designated e-mail account.

  • Add one or more pages to a Web site.

  • Add functionality to an existing solution.

Personally, we feel that the first procedure is the most time-consuming to handle, because it will most often result in unstructured messages/e-mails that cannot be dealt with automatically. Unlike with a Web form, the requested information is hardly ever located in specific areas of the message. This makes it more difficult to copy the information to a database or input it in a defect-tracking tool. There is too much manual work involved with this procedure.

A combination of a page on a Web site and information-collection functionality in existing software solutions is an elegant way of collecting this kind of information, and this approach can save you a fair bit of time, especially if you automate responses through e-mails. If you do resort to incorporating information-collection functionality in existing software, make sure that it doesn't send an e-mail, but instead uses a Web service to upload the information. The Web page is still needed, if you have implemented the new feature request functionality in the software, because the users might not be using the software when they discuss the functionality. In addition, the address of this Web page can be documented in the software documentation, such as the help files and user guides, whether they come in electronic form or as a hard copy.

Caution

It's vital to some organizations that you give the users and/or administrators the possibility of collecting the information for later uploading. You'll need to have some sort of temporary storage if this is desirable. This lets users upload from any machine in the organization, which is often a security issue for your customers.

Whichever procedure you choose to use, make sure to structure the information you receive so that it's easy to handle and store. Generally, this kind of information is stored in a database from where it can be viewed and manipulated. Many companies have their own database set up for this purpose, but you can also choose to use a defect-tracking tool to deal with new features. See the "Defects" section at the end of this chapter for more information about defect-tracking tools.

So, what kind of information do you need in a new functionality request? Here are some of the details we feel are needed and/or helpful (not presented in order of importance):

  • Name, title, and e-mail address of submitter

  • Existing software version

  • Current workaround, if any

  • Will submitter help beta test?

  • Importance

  • Detailed feature description

  • Submission date

  • Expected frequency of use

When a new feature request is received, it's important that an acknowledgment be sent to the submitter, informing him or her that you received the request for new functionality and when they can expect to hear back from you.

Note

Keep in mind that a new feature request might be a request for functionality that already exists in the software that the submitter is using; he or she is simply not aware of it. In addition, the submitter might be using an older version of your software, in which case, the functionality might already have been implemented in a newer version.

Instrumentation

Once your application has been deployed, it's vital that you have some way of monitoring the application when in use. Monitoring, in this case, means ensuring that potential errors can be avoided. How can you achieve that? You can implement monitoring using instrumentation; that is, you add code to your application that takes care of informing you, the user, and/or application administrator of issues that needs to be addressed. This can be memory running low, disk space running low, and… well, you know what issues might affect your application.

With Windows and VS .NET, you have two tools you can use for instrumentation:

  • The Enterprise Instrumentation framework (EIF), http://www.microsoft.com/downloads/details.aspx?FamilyId=80DF04BC-267D-4919-8BB4-1F84B7EB1368&displaylang=en

  • Windows Management Instrumentation (WMI), http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconbrowsingthe-wmischema.asp

Defects

Dealing with software defects, or bugs or issues as they're also commonly called, is by far the single most time-consuming work related to software development.[5]We have yet to hear about any piece of software that has been released without any defects. Why is that so? Well, quite often, defects are known at the time of release, but they're minor and an update has already been planned. So, in order to keep to the schedule, the software is released. However, it's much more time-consuming to track down and fix unknown defects.

Depending on the number of users that come across a particular defect and the severity of the defect, it can significantly influence the view your customers have of you as a reliable software vendor. Now, even if it's a severe defect, you can still save your reputation as a reliable software vendor by responding swiftly to the initial defect report, informing the user when you'll have more information. Sometimes, you might even be able to provide information about when a fix will be available in the initial defect response, but if not, this information should follow soon after the initial response. In cases where the defect is hard to track down and time becomes an issue, it's important that you contact customers to inform them of your progress and possibly get them to help with "real" data that can provoke the defect. Afterwards, they might help you test your fix and close the defect report when the problem is solved.

You can collect information about defects in a number ways. Here's a short list of some procedures we've come across:

  • Set up a designated e-mail account.

  • Add one or more pages to a Web site.

  • Add manual defect-reporting functionality to software.

  • Add automatic defect-reporting functionality to software.

Incorporating the automatic defect-reporting functionality into the deployed software is the best way of getting correct defect reports on time. However, you should be aware that many security software packages will block automatic attempts from the software to connect to the Internet.[6] In many countries, it's also illegal to send these types of reports back to you, unless the user is informed. Obviously, the method you choose for collecting defect information also depends onwhat kind of software you have deployed, such as Windows-based or Web-based.

As is the case with new functionality information collection, it's important that you make sure to structure the information you receive so that it's easy to handle and store. Generally, this kind of information is stored in a database from where it can be viewed and manipulated, and we suggest that you take a look at one of the many defect-tracking tools to help you with this task. You can obviously create your own database and tool for this purpose, but it really is a time-consuming job.

There is much more to defect tracking than we've introduced here, but you should now have a good idea of how you can put some defect-handling procedures in place. What is missing is a defect-tracking tool, of which there are many on the market. In recent years, we've seen these tools being integrated with other types of software, such as source code review and profiling software. You can find a list of defect-tracking tools at the Software Testing FAQ: Defect Tracking Tools Web site, http://www.testingfaqs.org/t-track.htm, including commercial software, shareware, and freeware. One of the tools not mentioned on the list is Axosoft OnTime Defect Tracking and Feature Management (http://www.axosoft.com/OnTime.htm), which includes automatic defect-reporting functionality using the Software Development Kit (SDK). This is an excellent, fairly inexpensive product that we've had the pleasure of working with over the past few years. We have alsohad good experiences with Compuware DevPartner and its TrackRecord application (http://www.compuware.com/products/devpartner/1969_ENG_2003.htm).

Which tool you use is obviously your choice, but do make sure that you carefully think about what you need, before you start out. For instance, do you need automatic defect-reporting functionality? As stated earlier in this section, we feel that is an excellent way of collecting defect reports, but not all the software on the market supports this approach.

[5]Proper planning and good procedures in place can reduce defect handling to a minimum, but you can never avoid defects.

[6]This is generally true for only client-based software.


Summary

This chapter presented you with a number of things to consider and decide on before starting to develop a VB .NET or C# project. These include the following:

  • Creating a development iteration plan

  • Deciding on one or more programming languages

  • Using one or more development solutions

  • Deciding on one or more project types

  • Finding existing code, components, and/or applications for reuse

  • Creating a multilanguage solution

  • Planning deployment

  • Testing your solution

You also were introduced to enterprise project templates and configuration files, which you can consider using for your solutions. Finally, we talked about maintenance considerations, including new functionality and defect tracking.

The next chapter discusses how you can maintain your UML models once they are created.


Chapter 7: Maintaining the UML Documentation

Overview

As you develop your solution, your UML model will be subject to refinements and changes. Then, after deploying the solution, you'll want to maintain the UML model in order to reflect error corrections and the customer change requests you've chosen to apply. Maintaining your UML documentation to keep it up-to-date is not an easy task.

In this chapter, we'll provide some guidelines and tips for UML model maintenance. We'll discuss when and what to update, and who should be responsible for maintenance. We'll also address the challenges of team development when using VEA.


When Should You Update?

As you go through the iterative process of UML development, you'll continue to discover information that is relevant to your solution:

  • You may discover ways to optimize your solution.

  • You might identify new features you need to implement.

  • You'll obtain more detailed information for your solution as the project evolves, when you finally determine the exact parameters and data types needed.

All of these are examples of new information you need to implement in your UML model to keep it up-to-date, and your UML documentation should follow.

We strongly advise you to update your UML model immediately after identifying the information to be documented; otherwise, you risk ending up with a model that doesn't reflect all the issues. Updating your UML model repeatedly and immediately will ensure that your UML model reflects the current development and evolves over time.

Start Sidebar
Another Approach: Updating in Stages

You might consider updating your UML model in stages. For example, you may know the detailed data type information for some (but not all) of your classes at an early stage, but choose to delay updating until you know the detailed data type information for all of your classes. In fact, this happens in many projects and may work fine for small-scale solutions. However, for large projects, you really do need to update your UML model often and immediately after you identify new information.

End Sidebar


What Should You Update?

Remember that a change (update) to your UML model can have an impact on different levels. You've learned that classes are often identified through sequence diagrams, which in turn reflect the information in a use case. With this in mind, suppose that you fundamentally change the way a class works. This will definitely require an update to the class itself and maybe to the class diagram. However, you might also need to change the corresponding sequence diagram, use case, and use case diagram.

In Figure 7-1, you can see a use case diagram with the use case documentation in the Documentation window. The tasks performed by the use case are receiving a password from the user and then checking its validity against a password file.

Click To expand
Figure 7-1: Use case diagram with documentation

In Figure 7-2, you can see the corresponding sequence diagram. Figure 7-3 shows the corresponding class diagram.

Click To expand
Figure 7-2: Sequence diagram based on the use case diagram
Click To expand
Figure 7-3: Class diagram based on sequence diagram

What happens if you decide to change the functionality so that the password is checked against a database instead of the password file? In this case, you need to change not only the class diagram, but also the sequence diagram and the use case narrative (the documentation).

Tip

A change to a detailed UML element can cause changes to the corresponding class diagram, sequence diagram, and use case diagram.


Who Is Responsible for Maintenance?

It's not an easy job to keep the UML model up-to-date, but establishing the responsibilities can help you quite a bit. As a rule of thumb, the individual making the physical change to the code is responsible for updating the UML model as well. This doesn't mean that he or she is the one actually making the update to the UML model, but that person must ensure that someone does.

In Chapter 2, you learned that the Microsoft Solutions Framework (MSF) consists of phases and roles, and that the roles are involved at different levels in the MSF phases. The five MSF phases are envisioning, planning, developing, stabilizing, and deploying. These phases will be discussed in detail in Chapter 20. For now, all you need to know is that the particular phase affects which role is responsible for maintaining the UML. Basically, the responsibilities align with the roles, as specified in Table 7-1.

Table 7-1. UML Update Responsibilities
MSF Phase | Roles Changing the UML | Model Roles Responsible for Updates
Envisioning | Product manager and program manager | Product manager
Planning | Program manager | Program manager
Developing | Developers | Developer (one distinct person)
Stabilizing | Program manager and tester developers | Program manager
Deploying | Release manager | Release manager

Notice that the product manager and the program manager are involved in UML modeling until the developing phase, when the developers are in charge of the UML model. In the stabilizing phase, the model is mainly updated by the program manager and the testers. Keep in mind that these are just roles and not job titles, and that a person can have more than one role.

Note

Some companies assign analysts, architects, and so on to do the analyses. In MSF terminology, these people can be represented by the title program manager, if the intent is that they perform the project management tasks as well; otherwise, they will be developers, thus specialized developers.

In Table 7-2, you can see some of the typical situations in which the UML model needs to be updated, along with a suggestion of who should perform the update. If your organization is new to UML, some of your team members may not be able to update the UML model correctly. In that case, you can assign one person to perform and coordinate all updating, but that person will still need information from the person or people suggested in the table.

Table 7-2. Situations Causing Updates to the UML Model
Situation | Most Likely to Update the UML Model
Envisioning the solution with the customer[a] | Product manager
Creating use cases based on information from customer meetings | Product manager
Refining use case diagrams | Program manager and/or the whole project group
Creating workflow diagrams | Product manager and/or program manager
Creating collaboration diagrams based on use cases | Program manager in cooperation with the project group
Creating sequence diagrams based on use case diagrams | Program manager in cooperation with the project group
Refining sequence diagrams | Developers and/or program manager
Creating class diagrams | Developers
Refining class diagrams | Developers
Creating component diagrams | Developers
Creating deployment diagrams | Developers and testers
[a] If you are developing internal solutions, the customer will be the sponsor or a sponsor representative.


How to Maintain UML in a Team

In larger projects, which enterprise development projects most often are, members of the project group will need to update the model at different levels simultaneously.[1] For example, three developers may want to update the model. Allowing several people to access and update the UML model at the same time requires team development facilities such as locking, version control, and file sharing.

VEA, which we're focusing on in this book, isn't really a team development tool; it's merely a documentation tool. In fact, VEA doesn't have the team facilities that some of the other (more expensive!) UML tools have. However, we think that VEA is still sufficient as a UML tool for enterprise projects. In this section, we'll offer some suggestions for team development with VEA.

Locking Your UML Model

Locking refers to the capability that enables you to lock parts of your model, allowing a number of people to work on the model at the same time without being able to interfere with parts locked by others. For example, you could lock the Manager package and the Interface package. This way, a person working on the Manager package could see everything in the Interface package but wouldn't be able to edit that package because it had been locked by another user. Locking requires that your model be split into several files or that your UML tool can handle it for you. VEA can do neither.

The UML tool IBM Rational XDE has this locking capability. IBM Rational XDE can save parts of the model in units that are distinct files. A unit can be almost anything. By placing the units under source control (for example, using Visual SourceSafe, which is introduced in Chapter 11), you can control the access to the different parts of your model.

In VEA, which doesn't have multiple file support or locking capabilities, you'll need to be a bit creative to make it possible to work in a team. VEA can save a model (file) as read-only. You can take advantage of this to ensure consistency. We suggest the following strategy to work with VEA files in a project team:

  • Maintain one master model and place this under version control. (See Chapter 11 for more details.)

  • Save your UML model as read-only whenever you distribute the model within the team as well as outside the team.

To save the UML model as read-only, select File ® Save As, and then select Read only from the drop-down list next to the Save button in the Save As dialog box, as shown in Figure 7-4.

Click To expand
Figure 7-4: Saving a model as read-only

Supporting Multiple Users

A key issue in any team development is multiuser support to enable users to simultaneously work on the same files. Again, we're sorry to report that VEA doesn't support that functionality. Any user opening a VEA file is opening that particular file exclusively, and the file can't be opened by others.

As described in the previous section, you can handle team development and multiuser development in VEA by placing the VEA file under source control and letting the source control software handle the multiuser issue. Yes, we know that this isn't impressive, but it works sufficiently in many cases.

Versioning Your Models

In larger projects, having versioned versions of the UML model can be advantageous. Versioned versions means that each time you save the model after making significant changes, you save the model in a new file and name it according to your version history.[2]

For example, suppose that your UML model (VEA file) is named MySolution_v1.vsd. After making significant changes to the model, you save it in a new file (using File ® Save As) and name the model MySolution_v2.vsd. This way, you can always step back in time if you've made some changes you want to redo or if your current file gets corrupted.

Tip

Make sure your UML model exists in different versions reflecting the development history. This way, you can always return to a previous version and go in different directions.

Another way to maintain version information is by using a background page for your UML models. The background page should contain the project name, version number, and last edit date and time. You can find more information about background pages at http://www.amazingvisio.com/visio_HowTo _BackgroundPage.htm.

[1]When developers are making simultaneous updates, you still need to make it clear who is responsible for maintaining the UML model updates.

[2]Of course, source control does the trick for you. If you use SourceSafe, make sure to enter descriptive text when you check in the file. See Chapter 11 for details.


How to Maintain Different Views of Your Model

When developing your solution, you can model different views. For example, in the envisioning phase, you might want to model the workflow of the business. This is called business modeling. Modeling different views in separate VEA models is no different from modeling with other UML tools.

So, how can you maintain these different views? Table 7-3 offers some suggestions. It describes the various views you can model and indicates whether you should keep the models in the same VEA model. When you place views in the same model, you should separate them by placing the diagrams and elements belonging to a specific view in a package. For example, you can create a package to contain all the physical views, including the physical class diagram and the physical database diagram.

Table 7-3. Maintaining Different Model Views
View | Description | Phase | Location
Analysis view | Model of current state and infrastructure assessments (business modeling) | Envisioning phase | Preferably , in a model separate from your solution model
Design view/logical view | The solution model | Planning phase | In the solution model
Component view/physical view | The solution model | Developing phase | In the solution model


How to Update the Model after Deployment

When your solution is deployed, and the test and delivery have been signed off byyour customer (as good MSF habits suggest), you're home free—you don't have to look at your UML model ever again, right? Well, not quite. Your model will stillbe the subject of changes. Maybe you'll identify errors and correct them, requiring updates to your UML model. Also, it's more than likely that your customer or users will demand changes or new features (and if you have some experience working with users, this will be no surprise).

A very important piece of project management advice (which also applies to MSF) is to collect change demands through formal (written) change requests. If you accept only change requests that are sent to you using a predefined change request form,[3] you're in control of the change flow. You'll know exactly which changes have been implemented and if those changes are reflected in the UML model.

Tip

Control the changes by collecting changes through change request forms and updating the UML model when they are implemented.

[3]A change request form should at least contain information about the change type, a change description, the date, and the name of the submitter. Consider collecting nonvital change requests and implementing them together in a new iteration (project). Most companies have their own standards in place to control changes.


Summary

In this chapter, you learned how to maintain your UML documentation. You learned that it's important to update your UML model frequently and immediately after identifying any changes. You also saw some suggestions for establishing maintenance responsibilities according to the MSF roles.

We also discussed team development. Unfortunately, VEA, which is the tool we focus on in this book, isn't a real team development tool, but merely a documentation tool. This means that you'll need to be creative when you work in teams. We suggested distributing only read-only versions of your UML model and using SourceSafe to keep track of your changes. If you don't use SourceSafe (or source control in general), we strongly advise you to manually maintain your own version history by saving a versioned model after each significant change.

The following points sum up the UML maintenance guidelines presented in this chapter:

  • Update your UML model immediately after identifying information to be documented.

  • A change to a detailed UML element can cause changes to the corresponding class diagram, sequence diagram, and use case diagram.

  • Be sure to know who is responsible for updating the UML model at each project phase.

  • Use source control (or at least manually keep a version history).

  • Use a background page for all pages.

  • Distribute only read-only versions of the UML model.

  • After deployment, collect changes through change request forms and update the UML model when the changes are implemented.

The next chapter is the beginning of Part III of this book, which covers VS .NET enterprise features. The first feature you'll learn about is enterprise templates, which are extremely useful when planning and controlling the development environment. Templates should be used by developers as well as program managers.


Part lll: VS. NET Enterprise Features

Chapter List

Chapter 8: Using Enterprise Template Projects
Chapter 9: Using Policy Files
Chapter 10: Using Custom Help Topics
Chapter 11: Visual SourceSafe
Chapter 12: Visio for Enterprise Architects 20039
Chapter 13: Application Center Test
Chapter 14: Visual Studio Analyzer
Chapter 15: Deploying Your Applications


Chapter 8: Using Enterprise Template Projects

Overview

In this chapter, you'll be introduced to enterprise template projects, which are solution templates for simplifying the task of creating distributed VS .NET applications typically consisting of several projects. You can use enterprise template projects with both enterprise editions of VS .NET—VSED and VSEA—but you can create and edit enterprise template projects only with VSEA.

Enterprise templates are used for creating solutions based on the task the solution must perform. This is important, because many other enterprise options are based on the programming language used for creating the solution. It means that a complex enterprise solution is broken into pieces or projects that are more manageable, each performing one or more of the solution tasks. This way, you usethe predefined project templates for the task they were designed to do.

We'll take a look at the prebuilt templates provided with VSED and VSEA, and examine a typical solution produced by a prebuilt template. This might seem a bit dry reading, but it will get interesting in the following sections, where you'll learn how to create custom enterprise template projects. But first, let's look at why you should bother with enterprise template projects.


Why Use Enterprise Template Projects?

Enterprise template projects are really solution templates, used for creating your own distributed solutions. They offer the following advantages:

  • Simplify creating an enterprise solution, by reducing the complexity

  • Enforce development policies

  • Provide guidelines for using template projects

VS .NET enterprise templates provide these advantages through their three components: an application prototype, a policy file, and custom help. The application prototype is the initial application structure, including the various projects with forms, controls, and so on. The policy file governs which controls, components, project types, and so on can be added to a solution, and what VS .NET IDE functionality is available to you. The custom help is basically help topics you canhave displayed in the dynamic Help window in the VS .NET IDE, as guidelines for how to use your custom enterprise template projects.

Overall, the real advantage you get from using enterprise template projects is that they save you a lot of time, because of the automated creation of the various projects. However, although you can use enterprise template projects for creating solutions that match the initial project outline, you shouldn't use the enterprise template projects to guide or steer your analysis or design. This means that you shouldn't start out by selecting an enterprise template project, and then force your distributed application into the boundaries of the enterprise template project. Instead, you should do your analysis, planning, and design first. Then when the time comes for selecting the appropriate technology for your design (the physical design phase of the MSF design process), you can choose your enterprise template project. (See Chapter 2 for an introduction to planning and design, and Chapter 20 for a detailed description of MSF.) This template project can help you set up the initial and perhaps complex application structure, and thus save you hours of manual work, because you don't need to create the initial application structure from scratch.

Basically, an enterprise template project is used for grouping projects and project wizards, thus creating a more complex initial application structure than a standard project. You can furthermore associate a policy file with an enterprise template project, and thereby govern what can and cannot be added to a solution, and add custom help topics to guide the developer. The grouping can be done with a standard VS .NET solution using virtual folders, but with policies, you can also restrict the developers from adding certain toolbox items and project items to a solution. In this chapter, we'll focus on the application prototype component. Chapter 9 discusses policy files, and Chapter 10 describes custom help.


Prebuilt Enterprise Template Projects

VSEA and VSED come with a number of prebuilt, ready-to-use enterprise templateprojects you can use for creating enterprise solutions, resulting in distributed applications. These enterprise template project files are located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects folder.

Choosing a Template Project

If you want to base your solution on one of these templates, you need to create anew solution and choose the right template. Each template consists of seven layers, or projects: Business facade, Business rules, Data access, System framework, Web services, Web user interface, and Windows user interface. The "Simple" project templates allow you to use only one programming language for the layers; the other distributed application templates let you choose a language for each layer. We'll look at these layers in the next section. Each template also has an associated template policy file named DAP.tdl, which is the standard template policy file for distributed applications, hence the name: Distributed Applications. Policy files are discussed in the next chapter.

The following prebuilt templates are available:

  • C# Distributed Application: You should use this template for larger-scale, nontrivial, distributed applications when most of the code, if not all, is written in C#.

  • C# Simple Distributed Application: As the name suggests, this is a simpler version of the C# Distributed Application template project. You should this template when creating smaller-scale, and perhaps even trivial, distributed applications when most of the code, if not all, is written in C#.

  • Distributed Application: This is the template for a nonprogramming language-specific distributed application. You should use this template project for larger scale, nontrivial, distributed applications when you haven't made an initial choice of programming language. This template project provides the same structure as the C# and VB .NET templates, but without the initial choice of a programming language.

  • Visual Basic Distributed Application: You should use this template project for larger-scale, nontrivial, distributed applications when most of the code, if not all, is written in VB .NET.

  • Visual Basic Simple Distributed Application: This is a simpler version of the Visual Basic Distributed Application template project. You should use this template when creating smaller-scale, and perhaps even trivial, distributed applications when most of the code, if not all, is written in VB .NET.

  • Enterprise Template Project: This template project is used for creating your own custom enterprise template projects, as discussed later in this chapter.

In Exercise 8-1, you'll choose to use a Visual Basic Distributed Application project template.

Exercise 8-1
Start example

  1. Open VS .NET, if it is not already open.

  2. Select File ®New ® Project or press Ctrl-Shift-N. This brings up the New Project dialog box.

  3. In the Project Types list, expand the Other Projects element, and select the Enterprise Template Projects element.

  4. Select the Visual Basic Distributed Application template in the Templates pane, as shown in Figure 8-1.

    Click To expand
    Figure 8-1: Selecting the Visual Basic Distributed Application in the New Project dialog box

  5. Type VBDA as the name for the solution in the Name text box, and select the location by browsing to it using the Browse button, or by typing it in the Location text box.

  6. Click OK to create the solution. VS .NET now creates the projects, including folders and files, and prompts you for the location of the Web user interface and the Web services.

  7. Enter the URL for these two layers in the two Enter Web Project dialog boxes, and then click OK.

End example

Examining a Solution Created with an Enterprise Template

When your solution has been created from an enterprise template, the Solution Explorer will show its seven layers, or projects. Figure 8-2 shows how a Visual Basic Distributed Application (VBDA) solution appears in the Solution Explorer.

Figure 8-2: Solution Explorer with a new Visual Basic Distributed Application solution
Note

In this chapter, we use the word solution for an enterprise template project, but these terms are really synonymous. The enterprise template project results in a VS .NET solution when you create a project using the enterprise template.

If you examine the various projects in the Solution Explorer, you'll find that not only have the project icons changed from the standard ones, but the project files also have different names. They have an .etp extension, as opposed to the default extension of .csproj for C# files or .vbproj for VB .NET files. The solution file uses the standard extension .sln.

The projects initially consist of different files:

  • Two UI projects: one for Windows and one for the Web. Each consists of a form and related files.

  • A Web service project. This consists of a Web service function file (.asmx) and related files.

  • A business facade project, a business rules project, and a system framework project. These consist of a class file and other project-related files.

  • The data access project, consisting of a component file. This is basically a class file like the Web service function file.[1]

All in all, the different projects consist of the files that make up the default project types.

Start Sidebar
Too Many Solution Layers

Sometimes, and probably more often than not, the enterprise template projects have too many layers or projects, but that's easy to fix. If you need to remove a project from the solution that is created from an enterprise template project, such as the Windows UI, simply right-click the unwanted project in the Solution Explorer and select Remove from the pop-up menu. You'll be required to confirm the removal. This removes the project from the solution; it doesn't delete the project from disk. Therefore, if you want to delete the project from disk, after removing it from the solution, you must do it manually.

If you find yourself removing the same layer(s) or project(s) from a new solution time after time, it's probably a good idea to edit the enterprise template project or even create a new one yourself. See the "Custom Enterprise Template Projects" section later in this chapter for more information.

End Sidebar

Looking at an Enterprise Template Project File

The enterprise template project file, the file with an .etp extension, is nothing more than a plain text file in XML format. It looks like a standard project file (.vbproj or .csproj), but there are some differences. Although you don't need to know what this file looks like to use the project template, understanding how this file works gives you some insight into your project's construction and can be particularly helpful if the solution becomes corrupted for some reason. Also, you do need this information if you want to create your own enterprise template project files, as explained later in this chapter.

A Visual Basic Distributed Application Enterprise Template File

In Listing 8-1, you can see the content of the XML-based enterprise template file for the Visual Basic Distributed Application (although some of the lines wrap here, because of the page width restrictions). You can find the Visual Basic Distributed Application.etp file in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\Visual Basic Distributed Application folder.

Note

You cannot add your own elements to an enterprise template file, because the associated enterprise template policy file governs which elements are allowed in the template file. The policy file associated with an enterprise template is specified with the GLOBALENTRY element. Chapter 9 covers policy files.

Listing 8-1. Visual Basic Distributed Application Enterprise Template File
Start example
<?xml version="1.0"?>
<EFPROJECT>
    <GENERAL>
        <BANNER>Microsoft Visual Studio Distributed Application Template File
        </BANNER>
        <VERSION>1.00</VERSION>
        <Views>
            <ProjectExplorer>
                <File>BusinessFacadeProjects\BusinessFacadeProjects.etp</File>
                <File>SystemFrameworksProjects\SystemFrameworksProjects.etp
                </File>
                <File>BusinessRulesProjects\BusinessRulesProjects.etp</File>
                <File>DataAccessProjects\DataAccessProjects.etp</File>
                <File>WebServiceProjects\WebServiceProjects.etp</File>
                <File>WinUIProjects\WinUIProjects.etp</File>
                <File>WebUIProjects\WebUIProjects.etp</File>
            </ProjectExplorer>
       </Views>
       <REFERENCES>
           <Reference>
               <FILE>BusinessFacadeProjects\BusinessFacadeProjects.etp</FILE>
               <GUIDPROJECTID>{258052BE-272A-4CF1-8F19-56998B4DF080}
               </GUIDPROJECTID>
            </Reference>
            <Reference>
                <FILE>SystemFrameworksProjects\SystemFrameworksProjects.etp</FILE>
                <GUIDPROJECTID>{B9472665-9A92-4D21-A0F9-73D8EADB1C18}
                </GUIDPROJECTID>
            </Reference>
            <Reference>
              <FILE>BusinessRulesProjects\BusinessRulesProjects.etp</FILE>
                <GUIDPROJECTID>{D1723258-A6AE-4B6C-8454-3FF1CB8695CC}
                </GUIDPROJECTID>
            </Reference>
            <Reference>
                <FILE>DataAccessProjects\DataAccessProjects.etp</FILE>
                <GUIDPROJECTID>{98842FB2-AC35-4BE4-A60A-29BC7A84DBEE}
                </GUIDPROJECTID>
            </Reference>
            <Reference>
                <FILE>WebServiceProjects\WebServiceProjects.etp</FILE>
                <GUIDPROJECTID>{CA0349FD-D550-420A-A7E9-F1873D137A25}
                </GUIDPROJECTID>
            </Reference>
            <Reference>
                <FILE>WinUIProjects\WinUIProjects.etp</FILE>
                <GUIDPROJECTID>{9DDAF723-53A1-4EDC-94D3-C5287332F860}
                </GUIDPROJECTID>
            </Reference>
            <Reference>
                <FILE>WebUIProjects\WebUIProjects.etp</FILE>
                <GUIDPROJECTID>{16C2F9D3-37D1-4B65-B35A-2B2B0C36113E}
                </GUIDPROJECTID>
            </Reference>
        </REFERENCES>
    </GENERAL>
    <GLOBALS>
        <GLOBALENTRY>
            <NAME>TDLFILE</NAME>
            <VALUE>DAP.tdl</VALUE>
        </GLOBALENTRY>
        <GLOBALENTRY>
            <NAME>TDLELEMENTTYPE</NAME>
            <VALUE>DistributedApplicationFull</VALUE>
        </GLOBALENTRY>
    </GLOBALS>
</EFPROJECT>
End example

This enterprise template file starts with the XML identifier on the first line. Then it has the root element, EFPROJECT, which defines the structure and contents of the enterprise template. There are two child elements to the root element, GENERAL and GLOBALS. Table 8-1 shows all the valid child elements of an enterprise template project file.

Note

We're using the word element, but you often hear the words node and tag used to refer to the various elements in a text file in XML format.

Table 8-1. Child Elements in an Enterprise Template File
Name | Parent Element | Description | Child Element
AUXPATH | SOURCECONTROLSETTINGS | For internal use by the enterprise template only; automatically created when you're using source control for your solution. Basically, this is the path to the source control database. Chapter 11 covers using Microsoft Visual SourceSafe for source control. |
BANNER | PROJECTEXPLORER | For internal use by the enterprise template only. |
FILE | GENERAL | Specifies the name and path for a file grouped in the virtual folder specified with the FOLDER parent element. |
FILE | FOLDER | Specifies the name and path for a file grouped in the virtual folder specified with the PROJECTEXPLORER parent element. |
FILE | REFERENCE | Specifies the actual file name of the project reference, specified with the REFERENCE parent element. |
FILE | WIZARD | Specifies the actual file name of the wizard (.vsz), specified with the WIZARD parent element. |
FOLDER | PROJECTEXPLORER | Specifies a virtual folder within the project's structure. This can be a subfolder in the main project folder that has the enterprise template, or a subfolder to a subfolder in the main project folder. Th is folder doesn't actually exist on disk, only as part of your enterprise template project, which also means that any items added to it aren't actually located in the folder. It's only for display and grouping purposes. This element supports nesting as deep as you want it. The fo lder and its contents are displayed in the Solution Expl orer. The folder must have a key field in the associated policy file, unless you also specify the FOLDERNAME child element in the enterprise template file. The policy file can be specified using a GLOBALENTRY element (see Chapter 9). | FILE ,FOLDERNAME , and FOLDER
FOLDERNAME | FOLDER | Specifies the actual name of the virtual folder specified with parent FOLDER element, as it appears in the Solution Explorer. |
GENERAL | EFPROJECT | A container for all projects and wizards in an enterprise template project. It can also contain information about source control settings. | BANNER REFERENCES ,SOURCECONTROLSETTINGS SUBPROJECTWIZARDS VERSION and VIEWS
GLOBALENTRY | GLOBALS | A name and value pair, used for specifying a global constant used by the enterprise template project. This is an optional element, but you can specify as many elements of this type as yo u want. The constants are valid for all projects within the enterprise template project. | NAME and VALUE
GLOBALS | EFPROJECT | A container for global variables and values associated with an enterprise template project. | GLOBALENTRY
GUIDPROJECTID | REFERENCE | For internal use by the enterprise template only; automatically created. It's a globally unique ID used for referencing the projrct. |
LOCALPATH | SOURCECONTROLSETTINGS | For internal use by the enterprise template only; automatically created when you're using source control for your solution. Basically, this is the local path, where the source code is written to or read from when checking in to or out from the source control database. (See Chapter 11.) |
NAME | GLOBALENTRY | A unique name used for identifying the element. This element is use in conjunction with the VALUE element for specifying a global name and value pair. |
PREFERREDSTARTUP | PROJECTEXPLORER | Specifies which project should be initially selected in the Solution Explorer, when you op en your solution in the VS .NET IDE. You specify the project as a FILE that has been defined in a REFERENCE element or as a FILE in the SUBPROJECTWIZARDS element. You can't use this element to specify a project file that is part of a subenterprise template project file; the project file must be part of the same enterprise template file. This element can't be used to specify a subenter prise template project (.etp); it must be a standard VS .NET programming language specific project file, with a .csproj or .vbproj extension. However, you can use an asterisk (*) to specify any programming language project file in the specified location, as in ProjectFolder\ProjectFileName.* . This optional element can be specified only once. If you add it more than once, an error is triggered when you open the solution. |
PROJECTEXPLORER | VIEWS | The element for the Solution Explorer, or rather the project view of the Solution Explorer in the VS .NET IDE. It determines how the enterprise solution created with the enterprise template is displayed in the Solution Explorer. | FILE FOLDER , and PREFERREDSTARTUP
PROJECTNAME | SOURCECONTROLSETTINGS | For internal use by the enterprise template only; automatically created when you're using source control for your solution. Basically, th is is the name used for the project in the source control database. (See Chapter 11.) |
PROVIDER | SOURCECONTROLSETTINGS | For internal use by the enterprise template only; automatically created when you're using source control for your solution. Basically, this is the name of the provider of the source control features. (See Chapter 11.) |
REFERENCE | REFERENCES | Specifies a project reference in the solution built with the enterprise template. Basically, this element can be used for specifying a standard project (programming language-specific), another en terprise template project, or a single project item. | FILE GUIDPROJECTID , REQUIRESURL , and UNLOADED
REFERENCES | GENERAL | A collection of zero or more REFERENCE child elements | REFERENCE
REQUIRESURL | REFERENCE | Specifies if the project reference, specified with the REFERENCE parent element, needs a URL where the project must be located. This element should contain a boolean value of 1 to make sure you're prompted for a URL, for each project in th e enterprise template that contains at least one reference to this element. You should child elements. element use this element for Web projects, such as Web services and Web pages. The URL is validated after you enter it in the Enter Web Project URL dialog box and click OK, so make sure you type in the correct address and that you use it for a Web project, or you will receive an error message. |
REQUIRESURL | WIZARD | Specifies if the wizard reference, specified with the WIZARD parent element, needs a URL where the wizard must be located. It works the same as the REQUIRESURL element specified with the REFERENCE parent element. |
SERVICEGUID | STARTUPSERVICES | For internal use by the enterprise template only. |
SOURCECONTROLSETTINGS | GENERAL | For internal use by the enterprise template only; automatically created when you're using source control for your solution. (See Chapter 11.) | AUXPATH LOCALPATH ,PROJECTNAME , and PROVIDER
STARTUPSERVICES | EFPROJECT | For internal use by the enterprise template only. | SERVICEGUID
SUBPROJECTWIZARD | GENERAL | A collection of zero or more WIZARD child elements. | WIZARD
UNLOADED | REFERENCES | For internal use by the enterprise template only. |
VALUE | GLOBALENTRY | The value for a unique name. This element is used in conjunction with the NAME element for spec ifying a global name and value pair. |
VERSION | GENERAL | The version number of the enterprise template project. It isn't currently used, but it may have a meaning when the template is loaded in the VS .NET IDE after a newer version of the Template Description Language ( TDL) is released. You should leave the value of this element intact. |
VIEWS | GENERAL | Defines how the project and subprojects are displayed. This element must be classi fied as more of a future feature, perhaps for VS .NET one, because curr ently only the Solution Explorer is supported, through the child element PROJECTEXPLORER | PROJECTEXPLORER
WIZARD | SUBPROJECTWIZARD | A reference to a project that will run when the enterprise template project is opened. The wizard or project is speci- fied using the child FILE and REQUIRESURL elements. | FILE and REQUIRESURL
Note

You need to set the value of the REQUIRESURL element to 0, or leave out this optional element, if you don't want to be prompted for a URL. Our experience with the REQUIRESURL element is that values of both 1 and 0 will make the enterprise template prompt you for a URL, so take out this element unless you really need to specify a URL. But be aware that you will get an error if you don't specify this element for a reference to a Web project. This prompts us to believe that if you specify a Web project and set the value of this element to 0, it's automatically overridden by the VS .NET IDE. You'll see how this element works in the "Adding Wizards to an Enterprise Template Project" section later in this chapter.

Figure 8-3 shows a graphical overview of how the root element and child elements are linked, or rather which child element belongs to which parent element.

Click To expand
Figure 8-3: Enterprise template project file hierarchy

Note that unlike many of the references in MSDN and on the Microsoft Web site, the VIEWS element does not contain a FILE subelement, as you'll also see from schema file in Listing 8-2.

Caution

If any element causes an error when the solution based on an enterprise template project is opened, you won't be able to access any part of the solution. This means you need to close the solution, resolve the error in the enterprise template project file, and reopen the solution.

An Enterprise Template Project Schema File

An enterprise template project is described using the projectschema.xsd schema file, which you can find in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Schemas folder. This file governs which elements can be added to the enterprise template project file and how they must appear in the subelement hierarchy. You can see the content of the schema file in Listing 8-2 (with some lines wrapping here, because of page width restrictions).

Listing 8-2. The projectschema.xsd Enterprise Template Project Schema File
Start example
 1 <?xml version="1.0" encoding="utf-8" ?>
 2 <xsd:schema id="ProjectSchema1"
      targetNamespace="http://tempuri.org/ProjectSchema1.xsd"
      xmlns="http://tempuri.org/ProjectSchema1.xsd"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      elementFormDefault="qualified">
 3    <xsd:simpleType name="PseudoBooleanType">
 4       <xsd:restriction base="xsd:string">
 5          <xsd:enumeration value="0" />
 6          <xsd:enumeration value="1" />
 7       </xsd:restriction>
 8    </xsd:simpleType>
 9    <xsd:complexType name="SourceControlSettingsType">
 10      <xsd:sequence>
 11         <xsd:element name="LOCALPATH" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 12         <xsd:element name="AUXPATH" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 13         <xsd:element name="PROJECTNAME" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 14         <xsd:element name="PROVIDER" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 15      </xsd:sequence>
 16      </xsd:complexType>
 17      <xsd:complexType name="ReferenceType">
 18         <xsd:sequence>
 19            <xsd:element name="FILE" type="xsd:string" minOccurs="0"
                  maxOccurs="1" />
 20         <xsd:element name="UNLOADED" type="xsd:string" minOccurs="0"
               maxOccurs="unbounded" />
 21         <xsd:element name="REQUIRESURL" type="PseudoBooleanType"
               minOccurs="0" maxOccurs="1" />
 22         <xsd:element name="GUIDPROJECTID" type="xsd:string" minOccurs="0"
               maxOccurs="1" />
 23      </xsd:sequence>
 24   </xsd:complexType>
 25   <xsd:complexType name="ReferencesType">
 26      <xsd:sequence>
 27         <xsd:element name="REFERENCE" type="ReferenceType" minOccurs="0"
               maxOccurs="unbounded" />
 28      </xsd:sequence>
 29   </xsd:complexType>
 30   <xsd:complexType name="FolderType">
 31      <xsd:sequence>
 32         <xsd:element name="FOLDERNAME" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 33         <xsd:element name="FILE" type="xsd:string" minOccurs="0"
               maxOccurs="unbounded" />
 34         <xsd:element name="FOLDER" type="FolderType" minOccurs="0"
               maxOccurs="unbounded" />
 35      </xsd:sequence>
 36   </xsd:complexType>
 37   <xsd:complexType name="ProjectExplorerType">
 38      <xsd:sequence>
 39         <xsd:element name="FILE" type="xsd:string" minOccurs="0"
               maxOccurs="unbounded" />
 40         <xsd:element name="FOLDER" type="FolderType" minOccurs="0"
               maxOccurs="unbounded" />
 41         <xsd:element name="PREFERREDSTARTUP" type="xsd:string" minOccurs="0"
               maxOccurs="1" />
 42      </xsd:sequence>
 43   </xsd:complexType>
 44   <xsd:complexType name="ViewsType">
 45      <xsd:sequence>
 46         <xsd:element name="PROJECTEXPLORER" type="ProjectExplorerType"
               minOccurs="0" maxOccurs="1" />
 47      </xsd:sequence>
 48   </xsd:complexType>
 49   <xsd:complexType name="WizardType">
 50      <xsd:sequence>
 51         <xsd:element name="FILE" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 52         <xsd:element name="REQUIRESURL" type="PseudoBooleanType"
               minOccurs="0" maxOccurs="1" />
 53      </xsd:sequence>
 54   </xsd:complexType>
 55   <xsd:complexType name="SubProjectWizardsType">
 56      <xsd:sequence>
 57         <xsd:element name="WIZARD" type="WizardType" minOccurs="0"
               maxOccurs="unbounded" />
 58      </xsd:sequence>
 59   </xsd:complexType>
 60   <xsd:complexType name="GeneralType">
 61      <xsd:sequence>
 62         <xsd:element name="BANNER" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 63         <xsd:element name="VERSION" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 64         <xsd:element name="SOURCECONTROLSETTINGS"
               type="SourceControlSettingsType" minOccurs="0" maxOccurs="1" />
 65         <xsd:element name="REFERENCES" type="ReferencesType" minOccurs="0"
               maxOccurs="1" />
 66         <xsd:element name="VIEWS" type="ViewsType" minOccurs="0"
               maxOccurs="1" />
 67         <xsd:element name="SUBPROJECTWIZARDS" type="SubProjectWizardsType"
               minOccurs="0" maxOccurs="1" />
 68      </xsd:sequence>
 69   </xsd:complexType>
 70   <xsd:complexType name="GlobalEntryType">
 71      <xsd:sequence>
 72         <xsd:element name="NAME" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 73         <xsd:element name="VALUE" type="xsd:string" minOccurs="1"
               maxOccurs="1" />
 74      </xsd:sequence>
 75   </xsd:complexType>
 76   <xsd:complexType name="GlobalsType">
 77      <xsd:sequence>
 78         <xsd:element name="GLOBALENTRY" type="GlobalEntryType" minOccurs="0"
 79            maxOccurs="unbounded" />
 80      </xsd:sequence>
 81   </xsd:complexType>
 82   <xsd:complexType name="StartupServicesType">
 83      <xsd:sequence>
 84         <xsd:element name="SERVICEGUID" type="xsd:string" minOccurs="0"
               maxOccurs="unbounded" />
 85      </xsd:sequence>
 86   </xsd:complexType>
 87   <xsd:complexType name="EFProjectType">
 88      <xsd:all>
 89         <xsd:element name="GENERAL" type="GeneralType" minOccurs="0"
               maxOccurs="1" />
 90         <xsd:element name="GLOBALS" type="GlobalsType" minOccurs="0"
               maxOccurs="1" />
 91         <xsd:element name="STARTUPSERVICES" type="StartupServicesType"
               minOccurs="0" maxOccurs="1" />
 92      </xsd:all>
 93   </xsd:complexType>
 94   <xsd:element name="EFPROJECT" type="EFProjectType"></xsd:element>
 95 </xsd:schema>
End example

At the top, you see an XML identifier on line 1, followed by the xsd root tag, which specifies the schema ID and namespaces, through attributes on line 2. Lines 3 through 8 are a simple custom data type definition named PseudoBooleanType, which is referenced later in the file. This Boolean-like data type accepts only 0 or 1 as input.

Lines 9 through 16 define the complex data type SourceControlSettingsType, which is one of the actual elements you can have in the enterprise template project file. This element can hold a sequence, meaning the subelements defined in the sequence occur as a group in the enterprise template project file. In this case, it means that the LOCALPATH, AUXPATH, PROJECTNAME, and PROVIDER elements act as one group in the SourceControlSettingsType complex data type or element. In these defined elements, you can also see the data type (string) and minimum and maximum occurrences (exactly one occurrence of each element). This means that if the SourceControlSettingsType element is specified in an enterprise template project file, all the subelements must be specified as well, exactly once. It's called a complex data type definition because it holds several values (also referred to as fields or members), a bit like an instance of a struct in C# or a Type in VB .NET.

The rest of the file contains more custom data type and element definitions. You can review the schema presented in Listing 8-2, together with the element list in Table 8-1 and diagram in Figure 8-3, to get a full overview of how an enterprise template project file is constructed.

The various reference parts of the enterprise template project reference either static or dynamic prototypes. The REFERENCES section refers to static projects orprototypes. The SUBPROJECTWIZARDS section refers to dynamic wizards or projects that prompt you for information and, based on this information, create a prototype project for you. You will see how this works in the "Adding Wizards to an Enterprise Template Project" section later in this chapter.

[1]A component file is a class file, but it has the Component Designer (canvas), onto which you can drop non-UI elements such as database connections. This means you can use the wizards for automatically generating some of your code.


Custom Enterprise Template Projects

If you find that the prebuilt enterprise template projects don't quite suit the applications your organization is creating, you can choose to either edit an existing enterprise template file or create a new one. There are two types of project references in an enterprise template project: static and dynamic. The static ones can be created and edited in the VS .NET IDE. The dynamic ones—the wizards—can be created and edited only manually using an XML or plain text editor, such as Notepad.

Editing an Existing Enterprise Template File

The simplest way to edit an existing enterprise template project file (.etp) is to open it in an XML or plain text editor. Editing the file in a text editor can be dangerous, unless you really know what you're doing. The reason for this is that you might delete parts of the file that are needed, or you might add elements that shouldn't be there, perhaps because of misspelling the element name. If you use a plain text editor, you won't be able to perform a check against the schema that an enterprise template project file must conform to,[2] so it's up to you to make sure that the enterprise template project file conforms to the schema.

An XML editor gives you a little more help than a plain text editor, because itcan color-code the various elements and you can check for a well-formed XML document. Additionally, many XML editors also let you associate an XML schema with the XML file, so you can check if the template file is valid.

Tip

We don't really have any preferences when it comes to XML editors, but we've tried xmlspy and found it quite good. The xmlspy program can be found at http://www.xmlspy.com.

Listing 8-1 shows an example of an enterprise template project file. In Table 8-1 and Figure 8-3 earlier in this chapter, you can see all the elements that make up theschema of an enterprise template project file, including a description and a graphical overview. This must be checked against the schema in Listing 8-2.When you edit the enterprise template project file, you must be careful not to accidentally delete any of the required elements:

  • EFPROJECT

Wait a minute, is that all that's really needed? Well, not really, but VS .NET will open the enterprise template project file as long as it contains an EFPROJECTelement. Once you have one of the three child elements of the root element—GENERAL, GLOBAL, or STARTUPSERVICES—you'll find there are subelements of these that must be present in the file. Refer to the schema in Listing 8-2 to see which subelements are required. Keep in mind that some of the elements are automatically added, changed, and removed by VS .NET, so don't start messing with these elements. Refer to Table 8-1 for information about the elements.

Caution

Always create a backup copy of the existing enterprise template project file, before attempting to edit it.

Instead of editing the enterprise template project manually, you can choose to open it in the VS .NET IDE. Figure 8-2, presented earlier in this chapter, shows how the VBDA solution, which is based on the Visual Basic Distributed Application enterprise template project, looks in the Solution Explorer. Although the VBDA enterprise template project file isn't the original enterprise template project file, youcan still add items to it and remove items from it.

Unless you edit the enterprise template project file directly, your new enterprise template project will not be added to the New Project dialog box. This is true even if you copy your entire project to the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects folder (where the prebuilt enterprise template projects are located). However, you can copy an enterprise template project, including all subprojects, to a designated folder on your disk, and then open the enterprise template project file (.etp) to create a new solution. If you want to add a new enterprise template project to the New Project dialog box, you must create it with VS .NET, using the Enterprise Template Project selection in the New Project dialog box, as described in the next section. You can also create an "initial" enterprise template project using the Enterprise Template Project, and then edit it manually.

If you've been editing one of the prebuilt enterprise template project files directly, your changes will be reflected in any solution that is created using the edited enterprise template project.

Creating a New Enterprise Template Project File Using VS .NET

To create your own enterprise template project, you must be using VSEA. In VSEA, you select the Enterprise Template Project in the New Project dialog box. This creates an empty project. In Exercise 8-2, you'll start a new enterprise template project.

Exercise 8-2
Start example

  1. Open VS .NET, if it is not already open.

  2. Select File® New ® Project, or press Ctrl-Shift-N. This brings up the New Project dialog box (see Figure 8-1 earlier in this chapter).

  3. In the Project Types list, expand the Other Projects element and select the Enterprise Template Projects element.

  4. Select Enterprise Template Project in the Templates pane.

  5. Type NewTemplateProject in the Name text box, and select the location (\Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Projects\) by browsing to it using the Browse button or by typing it in the Location text box. The enterprise template project must be placed in this folder, or it won't appear in the New Project dialog box.

  6. Click OK. VS .NET now creates the enterprise template project, as shown in Figure 8-4.

    Figure 8-4: New enterprise template project in the Solution Explorer

End example

As you can see in Figure 8-4, there's nothing in the new enterprise template project—it's just an initial structure for you to build on. You can add any project, wizard, or project element you can add to a standard solution or project. Once you're finished creating your enterprise template project, you will want to add it to the New Project dialog box on all the machines where your developers will use it. Building up your enterprise template project and adding it to the New Project dialog box are discussed in the following sections.

Caution

Keep in mind that if you add too many projects, wizards, or project items to the template, or customize the project items in the extreme, this can be constraining or just time-consuming for your developers. The developers will need to delete one or more projects, wizards, or project items, or spend time modifying your customized project items. Remember that you create an enterprise template project to guide the developers and to ease the building of the initial application structure.

Adding Projects and Project Items to an Enterprise Template Project

When you decide to add a project or project item to the enterprise template project, you can choose to add a standard VS .NET or enterprise template projector project item. The real difference here is how much you want to control the developers, meaning whether you want a policy file to govern the project or project item.

Tip

You can also add project items to the standard projects, and thus customize each project within your enterprise template project. This means that you can have your own Web or Windows forms with custom elements, like your company logo, added.

When you're creating an enterprise template project, you can build on its structure by using "building blocks." These are available through the Add New Project dialog box (opened by choosing File ® Add Project ® New Project), as shown in Figure 8-5.

Click To expand
Figure 8-5: Add New Project dialog box

Table 8-2 describes the building blocks you can add to your enterprise template projects. Note that these are programming language-specific; you must choose whether you want to add a C# or VB .NET building block.

Table 8-2. Enterprise Template Projects Building Blocks
Name | Description
Business Facade | Not a facade in the sense of a user interface; it's more of an interface that sits between the user interface and the business logic. This layer is often left out, depending on the overall application structure, but it can provide a more consistent access or interface to the underlying business logic, which can be created with the Business Rules building block.
Business Rules | Used for creating the business objects that apply to your business and the rules that govern your business.
Data Access | Used for creating the data access layer, consisting of one or more components that take care of accessing and updating the data in the database.
System | Used for creating objects that take care of the system service functionality. This can be caching, direct operating system interaction, or any other shared functionality. This layer should be accessible from any other layer in your application.
ASP.NET Web Service | Used for creating XML Web services with ASP.NET. More often than not, a Web service is merely an interface for accessing functionality exposed by your components, such as those in your data access layers. The advantage of using a Web service is that there's no UI; the Web service can be called from remote systems without any user intervention. It's a great way of making two otherwise incompatible systems exchange data.
WebUI | Used for creating a Web-based user interface. A Web user interface doesn't rule out a Windows user interface—you can have both.
WinUI | Used for creating a Windows-based user interface. Again, you can have both a Windows user interface and a Web user interface.

In Exercise 8-3, you'll add a building block to a new enterprise project template.

Exercise 8-3
Start example

  1. Open the NewTemplateProject enterprise template project you created in Exercise 8-2 (if is not already open in the VS .NET IDE).

  2. Right-click the NewTemplateProject template project (the node underneath the NewTemplateProject solution node) in the Solution Explorer, and select Add ® New Project from the pop-up menu. (You can also select File ® Add Project ®New Project.) This brings up the Add New Project dialog box.

  3. Expand the Enterprise Templates node, select the Visual Basic Building Blocks node, and select the Business Facade template (see Figure 8-5).

  4. Type BusinessFacade in the Name text box and click OK. The VB .NET business facade building block is now added to the enterprise template project and shown in the Solution Explorer.

End example

In Figure 8-5, you can see the Add New Project dialog box, which has been opened in the NewTemplateProject enterprise template project. This project is based on the Enterprise Template Projects template, which isn't programming language-specific, and this is why you see both C# and VB .NET project types.

You've just seen how simple it is to add a building block or project to an enterprise template project. However, sometimes you might need to add one or more additional items to a project. You do this in the same way that you add a new item to a standard VS .NET project. Exercise 8-4 demonstrates how to add a project item.

Exercise 8-4
Start example

  1. In your NewTemplateProject enterprise template project, right-click the BusinessFacade project in the Solution Explorer, and select Add ® New Item from the pop-up menu. You can also select the Project ® Add New Item menu command, or press Ctrl-Shift-A. This brings up the Add New Item dialog box.

  2. Expand the Local Project Items node, select the Code node, and select the Class template, as shown in Figure 8-6.

    Click To expand
    Figure 8-6: Add New Item dialog box

    Note

    There already is a class file, the Class1.vb file, in the BusinessFacade project. This Exercise merely demonstrates how to add a new item to a project in an enterprise template project.

  3. Type BusinessFacade.vb in the Name text box and click Open. The BusinessFacade.vb VB .NET class file is now added to the BusinessFacade project and shown in the Solution Explorer.

End example

As you can see, there's no difference between adding new items to a standard VS .NET project and adding them to a project in an enterprise template project.

Removing a Reference to a Policy File

When you create a new project based on one of the prebuilt enterprise template project templates, the enterprise template project file automatically references the prebuilt DAP.tdl policy file. In many cases, the prebuilt policy file won't be appropriate; it might be overkill or perhaps not restrictive enough. If you want to use your own policy reference file instead, remove the prebuilt policy file reference. After you've created your own policy file, you can reference that file instead. Exercise 8-5 shows you how to remove a reference to a prebuilt policy file. We will discuss policy files in Chapter 9.

Exercise 8-5
Start example

  1. Close the NewTemplateProject enterprise template project.

  2. In Notepad, open the BusinessFacade.vbproj file, which is located in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Projects\NewTemplateProject\ BusinessFacade folder.

  3. Delete the UserProperties element, which looks like this:

    <UserProperties
   TDLELEMENTTYPE = "BusinessFacade"
   TDLFILE = "DAP.tdl"
/>

  4. Save and close the file. This will delete the reference to the policy file (DAP.tdl in this case).

End example

Adding Wizards to an Enterprise Template Project

Adding a wizard to an enterprise template project is a little more difficult than just adding a building block or project. However, it can be your best choice, depending on what it is you want the developers to do. The wizards are dynamic, which means that they can create the project based on a developer's feedback.

You can add a wizard only manually, by editing the enterprise template project in an XML editor or a text editor. You can also create the entire enterprise template project from scratch, if you so desire, but it's generally easier to have VS .NET create the initial application structure, and then edit the resulting .etp file manually.

In Listing 8-3, you can see how the NewTemplateProject.etp file (created in the previous Exercises) looks after creating the initial application structure using VS .NET.

Listing 8-3. The Initial NewTemplateProject.etp File
Start example
<?xml version="1.0"?>
<EFPROJECT>
    <GENERAL>
        <BANNER>Microsoft Visual Studio Application Template File</BANNER>
        <VERSION>1.00</VERSION>
        <Views>
            <ProjectExplorer>
                <File>BusinessFacade\BusinessFacade.vbproj</File>
            </ProjectExplorer>
        </Views>
        <References>
            <Reference>
                <FILE>BusinessFacade\BusinessFacade.vbproj</FILE>
                <GUIDPROJECTID>
                   {20915FBE-2F4F-4B4D-956E-DECFA684AC82}
                </GUIDPROJECTID>
            </Reference>
        </References>
    </GENERAL>
    <GLOBALS>
        <GLOBALENTRY>
            <NAME>TDLFILE</NAME>
            <VALUE>DAP.TDL</VALUE>
        </GLOBALENTRY>
    </GLOBALS>
</EFPROJECT>
End example

Exercise 8-6 shows you how to add a wizard reference to your enterprise project template.

Exercise 8-6
Start example

  1. Open the NewTemplateProject.etp enterprise template project file in Notepad. (Make sure you close it, if it's still open in the VS .NET IDE.) It's located in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Projects\NewTemplateProject folder. The file should look like Listing 8-3.

  2. Delete the GUIDPROJECTID element.

  3. Add a SUBPROJECTWIZARDS element within the GENERAL element.

  4. Add a WIZARD element within the SUBPROJECTWIZARDS element.

  5. Add a FILE element within the WIZARD element. Set the value of this element to ..\Visual Basic Building Blocks\NewWebService.vsz.

  6. 6. Add a REQUIRESURL element within the WIZARD element. Set the value of this element to 1. You need to add this element and value because you want the developer to assign a URL to the Web service you add using the wizard. Your enterprise template project file should now look like Listing 8-4.

End example
Listing 8-4. The NewTemplateProject.etp File with Wizard Reference
Start example
<?xml version="1.0"?>
<EFPROJECT>
    <GENERAL>
      <BANNER>Microsoft Visual Studio Application Template File</BANNER>
      <VERSION>1.00</VERSION>
          <SUBPROJECTWIZARDS>
              <WIZARD>
                 <FILE> ..\Visual Basic Building Blocks\NewWebService.vsz</FILE>
                 <REQUIRESURL>1</REQUIRESURL>
              </WIZARD>
          </SUBPROJECTWIZARDS>
      <Views>
          <ProjectExplorer>
              <File>BusinessFacade\BusinessFacade.vbproj</File>
          </ProjectExplorer>
      </Views>
        <References>
            <Reference>
                <FILE>BusinessFacade\BusinessFacade.vbproj</FILE>
            </Reference>
        </References>
    </GENERAL>
</EFPROJECT>
End example

In Listing 8-4, you can see how the NewTemplateProject.etp file looks after adding a wizard reference. The FILE element value has been set to a nonexistent wizard, but you'll create this wizard in the next Exercise.

Well, you're not actually going to create a wizard from scratch, but you'll see what a wizard is made of and how you can customize the prebuilt wizards. The prebuilt wizards are located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\EFWizards folder. You should also place your custom wizards in this folder.

For the purpose of finishing the enterprise template project, you will add an XML Web service to the NewTemplateProject.etp file. You'll be using VB .NET for this XML Web service, but feel free to substitute with C#, if that suits you better. Then you will copy the actual wizard, which is nothing more than a script and one or more template files. Finally, you need to create the NewWebService.vsz file, which is the file (.vsz) that VS .NET uses for launching the wizard. You'll perform these steps in Exercise 8-7.

Exercise 8-7
Start example

  1. In the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Projects\Visual Basic Building Blocks folder, you can see a number of VB .NET project files (.vbproj). Find and copy the WebService.vbproj file to a new file named NewWebService.vbproj (in the same folder).

  2. Open the NewWebService.vbproj in Notepad and delete the UserProperties element at the end of the file. Then save and close the file. This will delete the reference to a prebuilt policy file. The NewWebService.vbproj file should now look like Listing 8-5.

    Listing 8-5. The NewWebService.vbproj File without the Policy File Reference

    Start example

    <VisualStudioProject>
   <VisualBasic
      OwnerKey = "{FE3BBBB6-72D5-11d2-9ACE-00C04F79A2A4}"
      ProjectType = "Web"
   >
      <Build>
          <Settings
              OutputType = "Library"
              StartupObject = ""
          >
             <Config
                Name = "Debug"
                EnableASPXDebugging = "true"
                DebugSymbols = "true"
                DefineDebug = "true"
                DefineTrace = "true"
                IncrementalBuild = "true"
                OutputPath = "bin"
             />
             <Config
                Name = "Release"
                EnableASPXDebugging = "true"
                DebugSymbols = "false"
                DefineDebug = "false"
                DefineTrace = "true"
                IncrementalBuild = "false"
                Optimize = "true"
                OutputPath = "bin"
             />
          </Settings>
          <References>
             <Reference Name = "System" />
             <Reference Name = "System.Data" />
             <Reference Name = "System.Web" />
             <Reference Name = "System.Web.Services" />
             <Reference Name = "System.XML" />
          </References>
          <Imports>
             <Import Namespace = "Microsoft.VisualBasic" />
             <Import Namespace = "System" />
             <Import Namespace = "System.Collections" />
             <Import Namespace = "System.Data" />
             <Import Namespace = "System.Diagnostics" />
             <Import Namespace = "System.Web" />
             <Import Namespace = "System.Web.Services" />
          </Imports>
      </Build>
      <Files>
         <Include>
         </Include>
      </Files>
   </VisualBasic>
</VisualStudioProject>
    End example

  3. Copy the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\EFWizards\vbwebservice folder, including the content, to a new folder named NewWebService in the \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\EFWizards folder. The \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\EFWizards\NewWebService folder now holds two subfolders:

    • scripts: This folder contains the custom script that creates the building block or project. The script can be either VBScript or JScript. All the prebuilt wizard scripts are JScript.

    • templates: This folder holds a number of project-specific template files, like a Web.config file for Web projects. All files in this folder will be added to the project.

    Note

    There are actually no files in these scripts and templates folders mentioned, because the files are located in a subfolder named langid, meaning the real name depends on the language used on your machine. Most machines will have folders named 1033, but you might have a different number as the name of your langid folders.

  4. Open Notepad and enter the following text:

    VSWIZARD 7.1
Wizard=VsWizard.VsWizardEngine
Param="WIZARD_UI = FALSE"
Param="WIZARD_NAME = NewWebService"
Param="PROJECT_TYPE = ETPROJ"
Param="SCRIPT_COMMON_RELATIVE_PATH = VBPROJ"
Param="EFT_PROTOTYPE = NewWebService.vbproj"

  5. Save the file as \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Projects\Visual Basic Building Blocks\ NewWebService.vsz. Remember to change the Save As type to All Files, or the saved file will get a .txt extension.

End example

This is all you have to do to add a wizard to your enterprise template project.(Consult the documentation for more information about how to create the actual wizard.)

Cleaning Up Your Enterprise Template Project

After you've created an enterprise template project, or edited an existing one, you can delete some of the files created by the VS .NET IDE. The files you can delete have the .suo, .eto, or .sln extension.

The .suo file is automatically created by the VS .NET IDE when you close your solution. It contains user customizations, such as which file was displayed in the text editor when you closed the solution, where you've placed breakpoints for the debugger, and so on. This is the solution user options file, which means it's user- and solution-specific. You can always delete this file from your solutions, which might be a good idea, especially if you change to a lower screen resolution, because this file remembers how and where you windows and panes are arranged.

The .eto files are policy cache files used by the VS .NET IDE for template projects and building blocks, to keep track of how the Solution Explorer is arranged for the template projects and building blocks. The purpose of an .eto file is a little like that of the .suo file, but .eto files are template project-specific, whereas the .suo file is solution-specific.

The .sln file is the VS .NET solution file, which holds information about all the files in a solution. Since you're creating an enterprise template project, and not a solution, you can delete this file.

All of the files with these extensions in the enterprise template project folder and subfolders can be deleted. You don't have to delete them, but since they're of no use to the users of your enterprise template project, you might as well get rid of them.

Besides these files, there are also two folders that you can delete from enterprise template project subfolders: bin and obj. These folders hold the executables and DLL files. They're automatically created when you open a VS .NET project or solution.

After creating your enterprise template project and perhaps deleting unnecessary files, you're also required to manually remove the GUIDPROJECTID elements from all of the .etp files in your enterprise template project. Open the .etp file(s) in Notepad, or any other text editor, delete the line with the GUIDPROJECTID element, and save the file. That's all you need to do.

Adding an Enterprise Template Project to the New Project Dialog Box

Once you've created a new enterprise template project, you will want to add it to the New Project dialog box, so that the users can create new solutions based on your new enterprise template project. To accomplish this, you need to create a text file with the .vsdir extension. This file is used by VS .NET to identify which projects to show in the New Project and Add Item dialog boxes.

Each line of text in the .vsdir file indicates a VS .NET project file (.etp, .csproj,.vbproj, or .vsz) that must be shown in the New Project dialog box. A line of text consists of elements, separated by the vertical bar (|), and it can look like this (taken from the ProxyProjects.vsdir file):

..\Projects\distributed application\Distributed Application.etp|
{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5011|10|
#5012|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|124|0|Project

The elements in a .vsdir text file line are described in Table 8-3.

Table 8-3. The .vsdir File Elements
Element Order | Description | Required? | Element Name
1 | The path and file name of the enterprise template project, wizard, or standard VS .NET project. | Yes | RelPathName
2 | Unique identifier (GUID) for a program that contains localized resources. | For wizards only | {clsidPackage}
3 | The name displayed in the New Project or Add Item dialog box, below the icon. In Figure 8-1 (earlier in this chapter), the name is Visual Basic Distributed Application. | No, but the value of the RelPathName element will be used if not specified. | LocalizedName
4 | Sort order in the New Project dialog box. This is an ascending order; a value of 0 will place the icon for your enterprise template project as the very first icon in the New Project dialog box, in the Enterprise Template Projects category. | Yes | SortPriority
5 | Description in the New Project or Add Item dialog box, shown below the Project Types and Templates panes. In Figure 8-1, the description is "A project for larger distributed applications with policy using Visual Basic." | Yes (you can type in a single space, if you prefer not to add a description) | Description
6 | Unique identifier (GUID) or the full path of a DLL or EXE that contains the icon specified with the IconResourceId value. This element overrides the value of the {clsidPackage} element, and it should be used for wizards only. | For wizards only | DLLPath
7 | The number of the icon used for your template in the New Project dialog box. See Table 8-4 for the valid numbers. | No, but the default Windows icon will be used if you don't specify one. | IconResourceId
8 | An integer value, which is a bitwise flag, that controls the name and the location of the new solution created rom your enterprise template project. See Table 8-5 for valid numbers. | Yes | Flags
9 | Default name for new projects cre ated with this template. By default, a number is added to this name, with the first project having a 1 added, the next project a 2, and so on. | No, but the value of the Project element is used, if not specified. | SuggestedBaseName

The numbers used to represent the icon displayed in the New Project dialog box (the IconResourceId element, at position 7 in the .vsdir file entry) are shown in Table 8-4. It's up to you find a suitable icon for your enterprise template project, but we suggest you follow the ones used for the prebuilt ones, which are described in the "Prebuilt Enterprise Template Projects" section earlier in the chapter.

Table 8-4: Icons for Enterprise Template Projects in the New Project Dialog Box
Number | Description | Icon
114 | Enterprise Template Project icon (the icon for creating your enterprise template project) |
120 | Icon for Template Description Language (TDL) files |
121 | C# Simple Distributed Application icon |
122 | Visual Basic Simple Distributed Application icon |
123 | Icon for the Simple Distributed Application, although this project type doesn't really exist. |
124 | Distributed Application icon |
125 | C# Distributed Application icon |
126 | Visual Basic Distributed Application icon |
127 | C# Business Facade Building Block icon |
128 | C# Business Rules Building Block icon |
129 | C# Data Access Building Block icon |
130 | C# System Building Block icon |
131 | C# WebUI Building Block icon |
132 | C# WinUI Building Block icon |
133 | Visual Basic Business Facade Building Block icon |
134 | Visual Basic Business Rules Building Block icon |
135 | Visual Basic Data Access Building Block icon |
136 | Visual Basic System Building Block icon |
137 | Visual Basic WebUI Building Block icon |
138 | Visual Basic WinUI Building Block icon |
140 | Icon for .eto files (you shouldn't use it for your enterprise template project) |
4500 | Visual Basic ASP.NET Web Service Building Block icon (you need to set the value of the DLLPath element to {164B10B9-B200-11D0-8C61-00A0C91E29D5} for this icon to be displayed) |
4547 | C# ASP.NET Web Service Building Block icon (you need to set the value of the DLLPath element to {FAE04EC1-301F-11d3-BF4B-00C04F79EFBC} for this icon to be displayed) |

Table 8-5 shows the values you can use to set the name and the location of the new solution created from your enterprise template project (the Flags element, at position 8 in the .vsdir file entry). There are a number of options for you to try out, but 0 (zero), which is the default value, lets the user of your template changeboth the name and location of the new solution. The other thing you can modify by changing this value is if you want to override the default name specified with the SuggestedBaseName field name, or if the SuggestedBaseName field name should be added to the previously used path.

Caution

We have a feeling Microsoft doesn't want us to play with this setting, which we find rather chaotic. Do try it out, if you feel adventurous, but keep in mind that changing this number for just one enterprise template project seems to have an impact on all enterprise template projects shown in the New Project dialog box, in some cases. Some values are valid for wizards only and others for projects. Do be careful with specifying numbers that aren't listed in Table 8-5, or that are not a value made up by adding one or more of the values in the table.

In Exercise 8-8, you'll add the new enterprise template project you created in earlier Exercises to the New Project dialog box.

Table 8-5: Values for the Name and Location of the Solution Created
Value | Description
0 | Default value, which lets you change both the name and location
1 | Uses a user interface and save functionality that's not local, which means that the Name text box is disabled, because the value of the LocalizedName element will be used, and a URL or URN is expected in the Location text box. You can see this if you select a custom enterprise template project in the New Project dialog box and look at the Location text box, where a forward slash (/) and the LocalizedName value is appended to the RelPathName value. You can use this for Web projects and Web services.
2 | Creates a blank or empty solution, and not a project.
4 | Disables the Browse button associated with the Location text box.
8 | Doesn't append the default extension to items added to a project or wizard. This value is ignored for some projects.
32 | Disables the Location text box.
4096 | Prevents the value of SuggestedBaseName element from being used to initialize the Name text box.
8192 | Disables the Name text box.
Exercise 8-8
Start example

  1. Open your desired text file editor (we use Notepad for this Exercise).

  2. Type in the following text, all on the same line:

    ..\Projects\NewTemplateProject\NewTemplateProject.etp|{AE77B8D0-6BDC-11d2-
B354-0000F81F0C06}|New Template Project|0|New Template Project
|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|125|0|NewTemplateProject

  3. Save the file under this name and in this folder: \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\ProxyProjects \NewTemplateProjectProxy.vsdir.

    Note

    The enterprise template project must be saved to the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks \Projects folder. You can't reference it anywhere else on your disk.
End example

To see your new enterprise template in the New Project dialog box, first close the VS .NET IDE, and then reopen it. (You can still edit the .vsdir file while VS .NET is open, because it seems to cache these files upon opening.) Then select File ®New ® Project or press Ctrl-Shift-N. In the New Project dialog box, select the Enterprise Template Projects category. Your new enterprise template project should now appear as the first project in this category, as shown in Figure 8-7.

Click To expand
Figure 8-7: New Template Project shown in the New Project dialog box

In Figure 8-7, you can see the icon and description referenced in the enterprise template project you created in this chapter in the New Project dialog box.

[2]There are plenty of tools on the market that can perform XML data validation against a schema, but it won't be integrated into Notepad, meaning you'll need to write your XML and then validate it in two separate steps.


Summary

In this chapter, you saw how you can create and use enterprise templates for your solutions. You learned the following specifics:

  • Enterprise template project files are XML-based text files.

  • Many elements can make up an enterprise template project file. Some are required, and others are optional. You also saw how the various elements are related.

  • You can create new enterprise template projects only by using VSEA.

  • You can manually add an enterprise template project to the New Project dialog box.

The next chapter covers how you can use policy files in your solutions that are based on an enterprise template project. You can restrict and/or enforce certain policies, such as which controls can be added to a form and what VS .NET IDE functionality can be accessed.


Chapter 9: Using Policy Files

Overview

In this chapter, you'll be introduced to policy files. Policy files are used in conjunction with enterprise template projects, as described in Chapter 8. Enterprise template projects are application prototypes for various project types. Policy files allow you to constrain and guide the developers working on your enterprise solution. You can use policy files with both enterprise editions of VS .NET: VSED and VSEA. However, you can create and edit policy files only with VSEA.

This chapter will cover a fair bit more than just the basics of using policy files. If you think the first few pages are a bit dry, please bear with us. We need to cover some basic information before we can move on to the more exciting stuff.

First, we'll cover some policy file concepts, including context and scope. Then we'll provide an overview of the policy file format and schema. After we've gotten through the introductory material, we'll explain how to create and edit policy files, and you'll see how powerful they can be.

Another feature of policy files is the possibility of associating specific help topics with each of the items in an enterprise solution, making sure that the most appropriate help topics are displayed in the Dynamic Help window. This is covered in Chapter 10.


Policy File Concepts

Enterprise solutions usually consist of many smaller projects, so it can be difficult to control all aspects of the solution. Even if an organization has written standards for which components or project types to use, there is no guarantee that the developers will actually adhere to those standards. This is where policy files come into the picture. They can restrict and guide the developers on the individual projects in your enterprise solution, by establishing which components, project types, and solution items can and must be used.

The policy file is said to describe the structure and elements of an enterprise solution. It also governs which technologies you can use in the solution or add to the solution, in terms of solution items (such as projects) and components.

Policy files can be used not only to restrict certain solution items, but also for specifically permitting other items. This is what makes a policy file ideal for large enterprise solutions: the author of a policy file can specify in as much detail as needed what the solution can, must, or must not include.

All of the enterprise template project prototypes that come with VSEA and VSED, described in Chapter 8, use the prebuilt DAP.tdl policy file, the standard one for distributed applications. Another prebuilt policy file is named VSIDE.tdl. These files have most of the items in the VS .NET IDE defined, ready for you to copy them into your own policy files. They're usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder.

Tip

The DAP.tdl and VSIDE.tdl files are prebuilt policy files you can use as a starting point for creating your own policy files. DAP.tdl contains elements that are appropriate for an enterprise solution, whereas VSIDE.tdl contains element definitions of the IDE features in VS .NET. In general, you can use a copy of the DAP.tdl as the initial policy file for your enterprise solutions, and then copy IDE element definitions, such as menu items, from the VSIDE.tdl file as needed.

Policy File Context

Policy files apply policies for the developers to a given context. As shown in Figure 9-1, this context can be any of the following three:

Click To expand
Figure 9-1: The three policy file contexts

  • The entire enterprise template project (this will make up your solution)

  • A single enterprise template project item, such as a project

  • A single component, such as a Label control or a COM component

When you set up your policy, you must decide which context the policy should govern.

Policy File Items

In relation to policy files, an item is anything you can apply a restriction or guideline to, such as menus, menu items, toolbox items, projects, project items, and references.

A policy file handles two different kinds of items: identified and unidentified items. Identified items are items that are explicitly part of the policy file through an ELEMENT node, which describes a single item in an enterprise template project. (The ELEMENT and other nodes in a policy file are discussed in the upcoming section on policy file format and schema.) As you can probably guess, unidentified itemsare those items that have not been specified as ELEMENT nodes.

But why would you need to work with unidentified items? The reason is that you won't know exactly what developers will do. For example, you don't want to explicitly create all possible project items in a project as ELEMENT nodes if you're leaving it up to the developers to decide which items to add. In fact, it would be impossible to know all possible items; literally thousands of different components can be added to a project.

Policy File Scope

The Template Description Language (TDL) language, which is used for policy files, doesn't provide full inheritance. However, when you refer to a policy file from an enterprise template project file, your subprojects and project items within the enterprise template project file automatically inherit the policy file settings from the parent project. This also means that you cannot have one policy file for a parent item, like the enterprise template project file, and another one for a subproject. For this reason, you cannot change the policy file for a child item, as illustrated in Figure 9-2.

Click To expand
Figure 9-2: Policy file scope

In Figure 9-2, you can see that the Policy File property is disabled in the Properties window. If you manually changed this value to a different policy file than the one for the parent item, and tried to open the project in the VS .NET IDE, you would get an error message, and the subproject would not be opened.


Policy File Format and Schema

A policy file is really nothing more than an ASCII text file expressed using TDL, an implementation of XML. Listing 9-1 shows an abbreviated version of a policy file.

Listing 9-1. Policy File Structure
Start example
<?xml version="1.0" ?>
<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS></DEFAULTSETTINGS>
   <ELEMENTS>
      <ELEMENT>
         <ID></ID>
         <CONTEXT></CONTEXT>
         <IDENTIFIERS></IDENTIFIERS>
         <ELEMENTSET></ELEMENTSET>
         <CONSTRAINTS></CONSTRAINTS>
         <PROTOTYPES></PROTOTYPES>
         <FEATURELINKS></FEATURELINKS>
      </ELEMENT>
   </ELEMENTS>
   <CATEGORIES></CATEGORIES>
   <FEATURES></FEATURES>
</TDL>
End example

Note that the policy file shown in Listing 9-1 doesn't contain any constraints; it has only the root and first-level nodes.

Note

The schema file used for policy files is the TDLSchema.xsd file, usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Schemas folder. Although you can manually edit this file to extend the TDL schema, it is not recommended, because you risk destroying the policy file's functionality.

Because TDL is XML-based, you use nodes or elements to describe your policy. You'll find details about how the nodes and elements work in the "Creating and Editing Policy Files" section later in this chapter, and we've included a list of all the nodes in the TDL schema in the "TDL Nodes" section at the end of this chapter. A diagram that shows all the nodes in the TDL hierarchy is available as a downloadable PDF file from the Downloads section of the Apress Web site (http://www.apress.com). Here, we will take a broad look at the root and first-level nodes in a policy file, and then at the important ELEMENTS node.

Root and First-Level Nodes

As you can see in Listing 9-1, the following are the root and first-level nodes in a policy file:

<TDL>
   <DEFAULTSETTINGS></DEFAULTSETTINGS>
   <ELEMENTS></ELEMENTS>
   <CATEGORIES></CATEGORIES>
   <FEATURES></FEATURES>
</TDL>

The following sections describe these nodes, taking them in the order in which they generally appear in a policy file.

Note

You can create a policy file using a standard text editor or an XML editor like the one in the VS .NET IDE, and add the nodes referenced in the sections as we go along. However, the next few sections are intended as introductory material. You'll get to create a policy file in the "Creating and Editing Policy Files" section later in this chapter.

TDL Root Node

The TDL root node is the only node with an attribute, which is the xmlns attribute. This attribute specifies the namespace for the policy file. In the prebuilt DAP.tdl policy file, the attribute is set to http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema. You should use this value in all of your policy files. This way, you can use an XML editor for minimal validation, as well as tag or node completion (automatically inserting the closing tag after you've typed in the opening tag).

The TDL start tag node should generally always look like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">

The TDL end tag should always look like this:

</TDL>

DEFAULTSETTINGS Node

The DEFAULTSETTINGS node is the only first-level node that is required. It is used forglobally specifying the default behaviors of the items in the policy file. Setting the default behaviors in the DEFAULTSETTINGS node is an excellent way of avoiding repeated information in your policy file. This means that you should specify the default behavior that will fit most items in your policy file, and then override the default setting for these nodes where appropriate.

The DEFAULTSETTINGS node and its child nodes look like this:

<DEFAULTSETTINGS>
   <DEFAULTACTION></DEFAULTACTION>
   <ORDER></ORDER>
   <POLICYMODE></POLICYMODE>
   <CONSTRAINTS></CONSTRAINTS>
</DEFAULTSETTINGS>

Only the CONSTRAINTS node is optional. The child nodes work as follows:

  • DEFAULTACTION: This node specifies if an item is included or excluded by default.

  • ORDER: This node specifies in which order include and exclude actions are taken. It has meaning only if an item is specified more than once. This happens when the policies are applied in an ELEMENTSET node, and you must specify INCLUDEEXCLUDE or EXCLUDEINCLUDE as the value for this node.

  • POLICYMODE: This node specifies how unidentified items (items that haven't been specified with an ELEMENT node) are handled. The POLICYMODE node works in conjunction with the DEFAULTACTION node for restricting elements, and you must specify PERMISSIVE or RESTRICTIVE as the value for this node. (See Table 9-1.)

  • CONSTRAINTS: This node serves as a container, and it can hold context-based constraints for menus, menu items, properties, and toolbox items.

The settings in the DEFAULTSETTINGS node can be overridden in an ELEMENTSETnode, which is described in the upcoming section about the ELEMENT node.

Note

The associated items referred to in Table 9-1 are items that are linked with a particular ELEMENT node, such as menus or menu items (MENULINK nodes).

Table 9-1. Default Item Policy Using the DEFAULTACTON and POLICYMODE Nodes
DEFAULTACTION Setting | POLICYMODE Setting | Default Policy Defined
INCLUDE | PERMISSIVE | Identified and unidentified items are included by default, unless explicitly excluded. Associated items of both included and excluded items are included, which is the real difference between this setting and the EXCLUDE/PERMISSIVE combination.
INCLUDE | RESTRICTIVE | Identified items that are explicitly added as INCLUDE nodes in the ELEMENTSET node, and any associated items, are included. All other items, both identified and unidentified, are excluded.
EXCLUDE | PERMISSIVE | Identified and unidentified items are included by default, unless explicitly added as EXCLUDE nodes in the ELEMENTSET node. Associated items of included items are also included, but associated items of excluded items are excluded, which is the real difference between this setting and the INCLUDE/PERMISSIVE combination.
EXCLUDE | RESTRICTIVE | Identified items that are explicitly added as INCLUDE nodes in the ELEMENTSET node are included. All other items, both identified and unidentified, are excluded. All associated items are excluded. This is also true for items associated with included items.

ELEMENTS Node

The ELEMENTS node is a container in which you place all the ELEMENT nodes (discussed in the "ELEMENT Node" section) in a single policy file. If an ELEMENT node that is referenced elsewhere in the policy file hasn't been defined in the ELEMENTS node, it will be handled as an unidentified item.

CATEGORIES Node

The CATEGORIES node is a container in which you place all the CATEGORY nodes in a single policy file. The CATEGORY node is used for grouping two or more ELEMENTnodes, or even other CATEGORY nodes. Therefore, when you refer to the same group of ELEMENT nodes more than once in your policy file, consider defining a CATEGORYnode in the CATEGORIES node, for easy reference elsewhere in your policy file.

FEATURES Node

The FEATURES node is a container for menu and toolbox items that you want to govern in your policy file. If you specifically want to enable or disable a menu or toolbox item, you must define it in the MENUS or TOOLBOXITEMS nodes, which are child nodes of the FEATURES node.

ELEMENT Node

The ELEMENT node isn't a first-level node in the TDL schema, but it's probably the most important one. The ELEMENT node is the fundamental building block of a policy file, because it specifies a particular enterprise template project item or element for which you define a policy.

The ELEMENT node describes a single item in an enterprise template project. Ifyou reference an element in your policy file that hasn't been specified with an ELEMENT node, it's called an unidentified element.

The ELEMENT node and its child nodes look like this:

<ELEMENT>
   <ID></ID>
   <CONTEXT></CONTEXT>
   <IDENTIFIERS></IDENTIFIERS>
   <ELEMENTSET></ELEMENTSET>
   <CONSTRAINTS></CONSTRAINTS>
   <PROTOTYPES></PROTOTYPES>
   <FEATURELINKS></FEATURELINKS>
</ELEMENT>

Only the ID node is required. The child nodes work as follows:

  • ID: This node is the unique identifier that is used to reference the node from elsewhere in the policy file.

  • CONTEXT: This node is used for displaying related help topics in the Dynamic Help window when the ELEMENT you're defining is selected within the VS .NET IDE. This subject is covered in detail in Chapter 10.

  • IDENTIFIERS: This node is a container node for zero or more IDENTIFIER nodes. This isn't the same as the ID node, which is used for referencing the ELEMENT elsewhere in the policy file. It's an identifier the VS .NET shell uses for identifying a more or less unique item, such as a project item. One of the child nodes of the IDENTIFIER node is the TYPE node, which determines the type of item, such as CODE or PROJECT.

  • ELEMENTSET: This node is used for referencing other ELEMENT or CATEGORY nodes that can be child items of the item being defined. The ELEMENTSET can also be used for defining constraints for the entire ELEMENT in which it is contained or a single member of the ELEMENTSET.

  • CONSTRAINTS: This node is used for specifying constraints for the item defined by the ELEMENT node. These constraints are specific to the element, meaning they apply when the element is selected within the VS .NET IDE. You can apply constraints to menus, menu items, properties, and toolbox items.

  • PROTOTYPES: This node is a container for zero or more PROTOTYPE nodes. Each PROTOTYPE node references the path and file name of an initial VS .NET project or prototype. Therefore, you use the PROTOTYPE node in cases where you have a prototype for the developers to build on.

  • FEATURELINKS: This node is a container for menu and toolbox item links. You add these child node links to the FEATURELINKS node in order to associate the linked items with the ELEMENT node in which FEATURELINKS is defined. This way, you enable or disable the items listed in the FEATURELINKS node, depending on whether the ELEMENT node is included or excluded. Basically, the FEATURELINKS node is there to save you the hassle of doing a lot of manual work.

In the next section, you'll see how the ELEMENT and other policy file nodes work together.


Creating and Editing Policy Files

This section will take you through creating a policy file from scratch. In general, we recommend that you start with a copy of the DAP.tdl file and edit it to suit your needs, but creating a policy file from scratch will give you a better understanding of how the policy file works. You'll see how to create the basic policy file skeleton and specify the default behaviors. Once you know how to build a policy file, you'll be able to edit existing policy files.

If a policy file is associated with an enterprise template project that has been used to create a new enterprise solution, and this solution is currently open, the policy file is said to be in use. However, you can make changes to such a policy file, and sometimes this comes in handy, depending on what kind of changes you want to make. When a solution associated with a policy file is opened in the VS .NET IDE, VS .NET loads the entire policy file into memory, effectively caching it for as long as the solution is open. This means that if you make changes to an associated policy file when the solution is open, you must close the solution and reopen it in the IDE for the changes to be applied.

Choosing an Editor

You can create and edit your policy files in any text-based editor, such as Notepad. However, because a policy file is expressed using the XML-based TDL, working in an XML editor offers advantages. Statement completion and other "smart" features will save you a fair bit of typing and reduce the possibility of errors. VS .NETcomes with a built-in XML editor (or designer, as Microsoft has chosen to call it), as shown in Figure 9-3.

Click To expand
Figure 9-3: VS .NET XML Designer with IntelliSense based on the TDL schema

Creating a Policy File Skeleton

When you're creating a policy file from scratch, you need to start by creating an empty text file with a .tdl extension (such as NewEnterprisePolicy.tdl) in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder.

If you want to use the VS .NET XML Designer without adding your policy fileto a project, you can begin by creating an empty text file with a .tdl extension and placing it in the mentioned Policy folder. After creating the empty policy file, you can double-click it to open it in the VS .NET XML Designer.

Your other option is to create the file in VS .NET. Open the New File dialog box (by pressing Ctrl-N or selecting File® New® File) and choose the XML file template, as shown in Figure 9-4.

Click To expand
Figure 9-4: Choosing to create an XML file in the New File dialog box

That creates a new XML file named XMLFile1, as shown in Figure 9-5, with the standard XML header. You should now delete the XML header/declaration and save the blank XMLFile1 file with a .tdl extension in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. (We know it's not good practice to create XML files without an XML declaration, but you'll be adding one soon.)

Click To expand
Figure 9-5: The XMLFile1 XML file shown in the XML Designer

The first node you need to add is the TDL node, because it is this root node that signals the type of file to VS .NET.

In Exercise 9-1, you'll start creating a policy file skeleton with the TDL node. You'll also associate the policy file with an enterprise template project, so that you will be able to check what happens in the VS .NET IDE when you use a solution based on an enterprise template project with a policy file.

Note

In the exercises in this chapter, you'll be using the NewTemplateProject.etp enterprise template project file created in the previous chapter. If you didn't follow the exercises in Chapter 8, you can find a copy of this file in the Chapter 08 folder of the accompanying sample code, available from the Downloads section of the Apress Web site (http://www.apress.com). You can copy the required files from the subfolders in Chapter 08\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks to the corresponding sub-folders in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks folder.
Exercise 9-1
Start example

  1. Create an empty text file named NewEnterprisePolicy.tdl, and place it in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Policy folder. You can use either the VS .NET XML Designer or the VS .NET New File dialog box to create this file, as described in the text preceding this Exercise.

  2. Add the TDL node to the NewEnterprisePolicy.tdl file, making it look like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
</TDL>

  3. To associate the newly created policy file, NewEnterprisePolicy.tdl, with the enterprise project file from Chapter 8, NewTemplateProject.etp, open the NewTemplateProject.etp file (located in \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\ NewTemplateProject) in Notepad and add the following text just before the closing EFPROJECT tag:

    <GLOBALS>
   <GLOBALENTRY>
      <NAME>TDLFILE</NAME>
      <VALUE>NewEnterprisePolicy.tdl</VALUE>
   </GLOBALENTRY>
</GLOBALS>

  4. Save the enterprise template project file, and then close Notepad.

End example

Another way to associate a policy file with an enterprise template project is to open the .etp file in the VS .NET IDE, select the enterprise project file in the Solution Explorer, and click the ellipsis button (…) in the Properties window, as shown in Figure 9-6.

Click To expand
Figure 9-6: Changing the policy file from the VS .NET IDE

If you try to create a new project from the enterprise template project file with the policy file in its current state, you will get an error, like the one shown in Figure 9-7, because you're missing some of the required elements or nodes. Don'tworry about it for now—we will add the necessary components in the coming sections.

Click To expand
Figure 9-7: Policy file loading error

Specifying Global Default Behaviors

As explained earlier in the chapter, the DEFAULTSETTINGS first-level node is used for globally specifying default behaviors for the items in an enterprise template project. Therefore, you add the first-level DEFAULTSETTINGS node as a child node to the TDL root node. After this, you need to consider how you want to handle identified items (those that have been specified as an ELEMENT node) and unidentified items, meaning including or excluding items by default, and if you want to constrain any menu items, toolbox items, or properties. You do this by using the child nodes of DEFAULTSETTINGS: DEFAULTACTION, POLICYMODE, ORDER, and CONSTRAINTS.

In Exercise 9-2, you will add the DEFAULTSETTINGS node to your policy file skeleton.

Exercise 9-2
Start example

  1. Open the NewEnterprisePolicy.tdl you created in Exercise 9-1.

  2. Add the DEFAULTSETTINGS node to the NewEnterprisePolicy.tdl file, making it look like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
 <DEFAULTSETTINGS>
 </DEFAULTSETTINGS>
</TDL>
End example

Specifying the Default ELEMENT Action and Policy Mode

The DEFAULTACTION node is used for globally specifying if an item is included or excluded by default. If you take the more permissive approach, you should set the value of this node to INCLUDE, which will include identified items and perhaps unidentified items, unless explicitly excluded. For a restrictive approach, set the value of this node to EXCLUDE, this will make sure that identified items will be excluded, unless explicitly included.

The DEFAULTACTION node works in conjunction with the POLICYMODE node (see Table 9-1 earlier in this chapter). The POLICYMODE node is used for globally specifying whether an unidentified item should be considered when including or excluding items. If you take the more permissive approach, you should set the value of this node to PERMISSIVE, which means unidentified items will be considered when including or excluding items. A restrictive approach will make sure that unidentified items always will be excluded. To achieve this, set the value of this node to RESTRICTIVE. Figure 9-8 illustrates how the default item policy works.

Click To expand
Figure 9-8: Default item policy

As you can see from Figure 9-8, there is at least one surprise: The INCLUDE/PERMISSIVE combination includes anything not explicitly excluded. You would think that associated items of excluded items would also be excluded, but not so. However, if you look at the four different combinations, you'll notice that you're able to cover virtually all possible situations in your policy file.

Here's a summary of how the DEFAULTACTION and POLICYMODE values work:

  • When POLICYMODE is set to PERMISSIVE and DEFAULTACTION is set to INCLUDE, everything is included unless specifically excluded, in which case, only the defined items are excluded, not any associated items.

  • When POLICYMODE is set to RESTRICTIVE and DEFAULTACTION is set to INCLUDE, everything is excluded unless specifically included, in which case any associated items are also included.

  • When POLICYMODE is set to RESTRICTIVE and DEFAULTACTION is set to EXCLUDE, everything is excluded, except for those items specifically included. No associated items are included.

In Exercise 9-3, you will add the DEFAULTACTION and POLICYMODE nodes to your policy file, within the parent DEFAULTSETTINGS node. In this example, you will take the restrictive approach.

Exercise 9-3
Start example

Add the DEFAULTACTION node and POLICYMODE node to the NewEnterprisePolicy.tdl file, so the NewEnterprisePolicy.tdl file now looks like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
   </DEFAULTSETTINGS>
</TDL>
End example

You still need to add more content to the policy file before you can create a new project from the enterprise template project file.

Note

When you set the POLICYMODE to RESTRICTIVE, it applies only to the Add Project Item dialog box and the Solution Explorer, meaning only elements that appear in these are restricted. This also means that code, code variables, and HTML, items aren't affected.
Start Sidebar
Unexpected Policy Behavior

Policy files are great, but they do need to operate on a set of rules that occasionally seem counterintuitive. Because of this, you may encounter some weird or unexpected behavior when you create more complex policy files. When we started working with policy files, and even more so when we started writing this book, we found that sometimes the policy files appeared to behave unexpectedly. Perhaps we explicitly excluded an item, and yet it was still accessible.

These surprises can be frustrating, and you can literally spend hours working them out. But the good thing is that we haven't yet come across any unexpected behavior that couldn't be explained once we investigated it in detail. In most cases, this was due to a default policy being overridden at some later stage further down the policy file.

Our advice is that you should always check for overriding policies when you come across unexpected policy behavior. We've made this mistake plenty of times, and we still do it. However, we now know where to look and it does save some time. Figure 9-8 might come in handy, if you're experiencing problems.

End Sidebar

Specifying Policy Order

When policies are applied in an ELEMENTSET node, and an element has been specified with both INCLUDE and EXCLUDE nodes, you need to have specified in which order the policies are applied. The ORDER node is used for this purpose, and you must specify INCLUDEEXCLUDE or EXCLUDEINCLUDE as the value. INCLUDEEXCLUDE means that all INCLUDE nodes in an ELEMENTSET are evaluated first, and then the EXCLUDEnodes are evaluated. So, if an item maps to both an INCLUDE and EXCLUDE node, it will be excluded when INCLUDEEXCLUDE is the value set for the ORDER node, and it will be included when EXCLUDEINCLUDE is used. This one is very tricky, but just keep in mind that it's the last evaluation that counts. See Table 9-1 earlier in this chapter for a schematic overview of the default item policy, or Figure 9-8 for a graphical representation of the default item policy.

In Exercise 9-4, you will add the ORDER node to your policy file, within the parent DEFAULTSETTINGS node, with a value of INCLUDEEXCLUDE. In most cases, this will be the preferred setting, always excluding ELEMENT nodes that have been specified in an EXCLUDE node, whether or not it also has been specified in an INCLUDE node. Since that is the last required node, after you add it, you will create a new project from the enterprise template project file.

Exercise 9-4
Start example

  1. Add the ORDER node to the NewEnterprisePolicy.tdl file so that it now looks like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
   </DEFAULTSETTINGS>
</TDL>

  2. To create a new project from the enterprise template project file, open the VS .NET IDE.

  3. Open the Add New Project dialog box (by selecting File ® New®Project), and select Enterprise Template Projects in the Templates pane.

  4. Keep the default name, NewTemplateProject1, and click OK to create the new project.

  5. Save the project/solution for later Exercises.

End example

If you followed the Exercise, your VS .NET IDE now looks like Figure 9-9.

Click To expand
Figure 9-9: NewTemplateProject1 project open in the VS .NET IDE

Specifying Global Constraints

Global constraints are constraints that apply to the entire enterprise template project that uses the policy file. Global constraints are specified using the optional CONSTRAINTS node within the DEFAULTSETTINGS node. The constraints you can specify are for menu and menu items (MENUCONSTRAINTS), properties (PROPERTYCONSTRAINTS), and toolbox items (TOOLBOXCONSTRAINTS).

Note

The global constraints discussed here aren't conditional, meaning they apply no matter what is currently selected in your enterprise template project.

We will cover using constraints in the "Configuring the VS .NET IDE Using Policies" section later in this chapter. However, in Exercise 9-5, you will set up the CONSTRAINTS node in your policy file, ready for later use. None of the child nodes of theCONSTRAINTS node are required, so you can simply add that node. This Exercise makes no difference to the VS .NET IDE when you open the NewTemplateProject1 created in the previous Exercise.

Note

Whether you should add these nodes to the policy file, if they aren't used, is a matter of preference. They certainly do no harm there, but bear in mind that the policy files do tend to be very large. However, it's good for a beginner reading your policy file to have them there, to indicate there aren't any global constraints.

Exercise 9-5
Start example

Add the CONSTRAINTS node to the NewEnterprisePolicy.tdl file within the parent DEFAULTSETTINGS node. Then add the MENUCONSTRAINTS, PROPERTYCONSTRAINTS, and TOOLBOXCONSTRAINTS child nodes to the CONSTRAINTS node. The NewEnterprisePolicy.tdl file now looks like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <CONSTRAINTS>
         <MENUCONSTRAINTS></MENUCONSTRAINTS>
         <PROPERTYCONSTRAINTS></PROPERTYCONSTRAINTS>
         <TOOLBOXCONSTRAINTS></TOOLBOXCONSTRAINTS>
      </CONSTRAINTS>
   </DEFAULTSETTINGS>
</TDL>
End example

Adding Items

As noted earlier in the chapter, items in a policy file are either identified or unidentified. Identified items are items that haven't been specified as an ELEMENTnode within the first-level ELEMENTS node.

All identified items must be added as ELEMENT child nodes to the ELEMENTSnode. The ELEMENT node is the most complex of all the nodes, but many of the child nodes are optional, and you rarely need to specify more than half of them.

The ID node is the only required child node of the ELEMENT node, and for a pretty obvious reason: it's used for identification and references elsewhere in the policy file. This means that the value of ID node must be unique within the policyfile, thus making the ELEMENT node unique. So, there must always be exactly one ID child node in an ELEMENT node. You can name your ELEMENT nodes virtually anything you want, by assigning the name to the ID child node. Well, there are a few exceptions to this rule. You cannot use these TDL keywords as the full ID (they can be part of the ID): INTERSECT, SUBTRACT, and UNION. Also not permitted are white space and parentheses as part of the ID.

Start Sidebar
TDL White Spaces

By our definition, white space is usually extra spaces, meaning you can have one space separating two words, but if there are two spaces, one of the spaces is counted as white space. However, the Microsoft definition for TDL white space seems to be a little different. You're not allowed any spaces within the ID, but you can have a space at the beginning or the end of the ID; they don't count. The same is true for INCLUDE and EXCLUDE nodes. So, these ID nodes are valid:

<ID>NewNode</ID>
<ID> NewNode</ID>
<ID>NewNode </ID>

However, the following ID name is invalid:

<ID>New Node</ID>
End Sidebar

Although you can use virtually any name as the ID for your ELEMENT nodes, it is highly recommended that you use the ones already created for you in the VSIDE.tdl and DAP.tdl files. This will save you a lot of time, and it will be easier for you and your developers to read and maintain the policy files.

You'll learn how the optional ELEMENTS child nodes work when we cover adding and configuring items in later sections of this chapter.

In Exercise 9-6, you will simply add the first-level ELEMENTS node to your policy file.

Exercise 9-6
Start example

Add the ELEMENTS node to the NewEnterprisePolicy.tdl file within the parent TDL

node. The file now looks like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <CONSTRAINTS>
         <MENUCONSTRAINTS></MENUCONSTRAINTS>
         <PROPERTYCONSTRAINTS></PROPERTYCONSTRAINTS>
         <TOOLBOXCONSTRAINTS></TOOLBOXCONSTRAINTS>
      </CONSTRAINTS>
   </DEFAULTSETTINGS>
   <ELEMENTS>
   </ELEMENTS>
</TDL>
End example

Defining Item ELEMENTSETs

Within an ELEMENT node, the ELEMENTSET child node is used for defining a subset of ELEMENT and/or CATEGORY nodes. Actually, you can also use the ELEMENTSET node for defining constraints for the entire ELEMENTSET or for a subset of the ELEMENTSET. This is in addition to or instead of explicitly defining a subset of ELEMENT and/or CATEGORY nodes.

An ELEMENTSET node has no required child nodes. It has the following optional nodes:

  • CONSTRAINTS: This node specifies constraints for all items in the ELEMENTSET, including both identified and unidentified items. These can be menu, property, and/or toolbox constraints.

  • DEFAULTACTION: This node has the same function as the node by the same name in the first-level DEFAULTSETTINGS node. However, here it applies only to the items in the ELEMENTSET, whereas the one in the DEFAULTSETTINGS node applies globally in the policy file. Be aware that if you specify this node in an ELEMENTSET node, it will override the value specified in the DEFAULTSETTINGS node.

  • EXCLUDE: This node is used for referencing ELEMENT nodes defined in the first-level ELEMENTS node or CATEGORY nodes defined in the first-level CATEGORIES node. Basically, if you want to explicitly exclude an item from the ELEMENTSET, you reference the item in an EXCLUDE node.

  • INCLUDE: This node is used for referencing ELEMENT nodes defined in the first- level ELEMENTS node or CATEGORY nodes defined in the first-level CATEGORIES node. Basically, if you want to explicitly include an item, you reference the item in an INCLUDE node.

  • MEMBERCONSTRAINTS: This node is used to specify constraints for one or more identified items in the ELEMENTSET. This can be menu, property, and/or toolbox constraints.

  • ORDER: This node has the same function as the node by the same name in the first-level DEFAULTSETTINGS node, but it applies only to the items in the ELEMENTSET, whereas the one in the DEFAULTSETTINGS node applies globally in the policy file. Be aware that if you specify this node in an ELEMENTSET node, it will override the value specified in the DEFAULTSETTINGS node.

When you use the EXCLUDE and INCLUDE nodes, you specify the value set for the ID node of an ELEMENT or CATEGORY node as their value. All items referenced in EXCLUDE and INCLUDE nodes are identified items, and all others are unidentified items. Depending on the default settings, items can be excluded or included by default, and this is the way to override that default.

To get an idea of how ELEMENTSET nodes work, let's assume that you want to disable the View ® Code menu item when any VB code files are selected in the Solution Explorer for the projWebService project. This is what you will do in Exercise 9-7.

Exercise 9-7
Start example

  1. First, you need a MENU node for the View ® Code menu item. Menus and menu items are defined in the MENUS node, a child node of the first-level FEATURES node. Listing 9-2 shows the definitions for the menuView.ViewCode menu item. Add Listing 9-2 to the NewEnterprise- Policy.tdl policy file and save it. You should add it after the </ELEMENTS> node, but before the </TDL> node.

    Listing 9-2. MENU Node Definition for the View ® Code Menu Item

    Start example

    <FEATURES>
   <MENUS>
      <MENU>
         <ID>menuView.ViewCode</ID>
         <CMDID>333</CMDID>
         <GUID>{5EFC7975-14BC-11CF-9B2B-00AA00573819}</GUID>
      </MENU>
   </MENUS>
</FEATURES>
    End example

  2. Now, you need an ELEMENT definition of VB code files. Listing 9-3 shows you how you can specify a group of project items (VB code files) as an ELEMENT node. The values for the View ® Code menu item have been copied from the VSIDE.tdl file. Add Listing 9-3 to the NewEnterprisePolicy.tdl policy file and save it. You should add it between the <ELEMENTS> and </ELEMENTS> nodes.

    Listing 9-3. ELEMENT Definition of VB Code Files

    Start example

    <ELEMENT>
   <ID>projItemVBCodeFile</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.vb</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
    End example

  3. With the menu and project item definition in place, it's time to create the Web service project ELEMENTS with a MEMBERCONSTRAINT, as in Listing 9-4. Add Listing 9-4 to the NewEnterprisePolicy.tdl policy file and save it. You should add it between the </ELEMENT> and </ELEMENTS> nodes.

    Note

    In Listing 9-4, we have defined the projWebService ELEMENT, which is a project ELEMENT node. This node is rather unique, because it very specifically identifies the VB .NET project by the name NewWebService.vbproj. In most cases, you won't be that specific, but we'll build on this later in the chapter, so just go with it for now.

    Listing 9-4. Project ELEMENT Definition with a MEMBERCONSTRAINT Node

    Start example

    <ELEMENT>
   <ID>projWebService</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>NewWebService.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <INCLUDE>projItemVBCodeFile</INCLUDE>
      <MEMBERCONSTRAINTS>
         <MEMBERCONSTRAINT>
            <ID>projItemVBCodeFile</ID>
            <MENUCONSTRAINTS>
               <MENUCONSTRAINT>
                  <ID>menuView.ViewCode</ID>
                  <ENABLED>0</ENABLED>
               </MENUCONSTRAINT>
            </MENUCONSTRAINTS>
         </MEMBERCONSTRAINT>
      </MEMBERCONSTRAINTS>
   </ELEMENTSET>
</ELEMENT>
    End example

End example

In the example is Exercise 9-7, the ELEMENTSET node specifically includes the VB code file project item, and then it sets up a MEMBERCONSTRAINT node that disables the View®Code menu item whenever a VB code file project item belonging to the projWebService project is selected in the Solution Explorer. That's right, no peeking at the code, as shown in Figure 9-10. Well, that's not entirely true, because you can right-click the VB code file project item in the Solution Explorer and select Open from the pop-up menu to get to the code.

Click To expand
Figure 9-10: View ® Code menu item disabled

However, even if the policy file doesn't block all ways to view the code, creating it does demonstrate the following:

  • You can assign a constraint to a specific member of an ELEMENTSET, rather than to just the entire ELEMENTSET.

  • You can control any aspect of the VS .NET IDE, including not allowing a developer to view the code or similar actions.

We're sure you get the idea of just how valuable this kind of functionality can be. Only your imagination will limit your control and guidance of the developers.

Creating Specific ELEMENT Identifiers

When you create an ELEMENT node, you must tell the VS .NET shell which item you want the ELEMENT to represent. In most cases, it will represent a specific type of item, such as a VB code file (project item) or an ASP.NET Web application (project). However, it is possible to have an ELEMENT node represent a unique item, such as a project referenced by the project file's physical name (NewWebService.vbproj, for instance).

As explained earlier in the chapter, an ELEMENT node must have an ID node. The value of the ID node is used for referencing the ELEMENT node elsewhere in the policy file, but that's all it does. The VS .NET shell also needs a way of telling which item the ELEMENT node represents, and this is where the IDENTIFIERS node comes in. This node holds a collection of custom information, expressed through IDENTIFIER nodes. The child nodes of the IDENTIFIER nodes provide the VS .NET shell with the information needed to identify an item. A bare-bones IDENTIFIERSnode with one IDENTIFIER child node looks like this:

<IDENTIFIERS>
   <IDENTIFIER>
      <TYPE></TYPE>
      <IDENTIFIERDATA>
      </IDENTIFIERDATA>
   </IDENTIFIER>
</IDENTIFIERS>

The IDENTIFIER node is optional, as is the IDENTIFIERS node within the ELEMENTnode. Therefore, you don't need to specify the IDENTIFIERS node if you don't want to specify at least one IDENTIFIER child node. You can specify as many IDENTIFIERnodes as you want within the IDENTIFIERS node. That's one way of creating an ELEMENT node that represents a unique item. You can also specify more than one IDENTIFERDATA node for an IDENTIFIER node.

The TYPE node is used for specifying the type of item represented by the ELEMENTnode. The TYPE node is required, and you must always specify exactly one TYPEnode in an IDENTIFIER node. The value for the TYPE node must be set to one of the following values:

  • CODE: This value specifies a code element. The code element can be one of the following: a named attribute, a named class, a named interface, or the kind or type of code element (Class, Namespace, Interface, Delegate, or Structure).

  • CODEVARIABLE: This value is used for specifying the type of a code variable or the base class name.

  • HTMLELEMENT: This value can be used for specifying a tag/name or an attribute value for an HTML element.

  • PROJECT: You can use this value for specifying a project, using a file extension, the type or kind of project, or a global or property value. You can be very specific about the project, meaning you can specify a specific project, not just a general type of project.

  • PROJECTITEM: This value is used for specifying a project item (what a surprise, eh?), and it's done using a file extension, the type or kind of project item, or a property value.

  • REFERENCE: This value is used for indicating a reference to a component.[1]The reference can be done using the file name and the major and minor version numbers of the component.

The following sections describe the various combinations of values for the NAME and VALUE nodes of the IDENTIFIERDATA node, when setting the value of the TYPE node of the parent IDENTIFIER node.

Caution

You can specify multiple IDENTIFIER nodes and IDENTIFERDATA nodes, and this can be very useful for creating more or less unique ELEMENT nodes. However, you must make sure you don't specify two conflicting combinations. If this happens, your ELEMENT node will never be identified by the VS .NET shell.
CODE/Attribute:<AttributeName>
TYPE node value | CODE
NAME node value | Attribute:<AttributeName>
VALUE node value | <AttributeValue>

You can use the CODE/Attribute:<AttributeName> IDENTIFIER node combination to identify a class by custom attribute. Here is an example:

<IDENTIFIER>
   <TYPE>CODE</TYPE>
   <IDENTIFIERDATA>
      <NAME>Attribute:MaxValue</NAME>
      <VALUE>"1"</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

For more information, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vstchusingcustomcodeattributesfortdlidentificationinenterprisetemplates.asp .

CODE/Kind
TYPE node value | CODE
NAME node value | Kind
VALUE node value | vsCMElementClass | vsCMElementDelegate | vsCMElementInterface | vsCMElementNamespace | vsCMElementStruct

Use the CODE/Kind IDENTIFIER node combination to specify a specific kind of code element, using one of the shown constants or the corresponding integer value. Here is an example:

<IDENTIFIER>
   <TYPE>CODE</TYPE>
   <IDENTIFIERDATA>
      <NAME>Kind</NAME>
      <VALUE>vsCMEelementClass</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
CODE/Implements
TYPE node value | CODE
NAME node value | Implements
VALUE node value | <InterfaceName>

Use the CODE/Implements IDENTIFIER node combination to specify a class that implements the interface specified with <InterfaceName>. Here is an example:

<IDENTIFIER>
   <TYPE>CODE</TYPE>
   <IDENTIFIERDATA>
      <NAME>Implements</NAME>
      <VALUE>IDisposable</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
CODE/Inherits
TYPE node value | CODE
NAME node value | Inherits
VALUE node value | <ClassName>

Use the CODE/Inherits IDENTIFIER node combination to specify a class that inherits from the base class specified with <ClassName>. You need to make sure you specifythe fully qualified name of the class, including the namespace, as shown in this example:

<IDENTIFIER>
   <TYPE>CODE</TYPE>
   <IDENTIFIERDATA>
      <NAME>Inherits</NAME>
      <VALUE>System.Windows.Forms.Form</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
CODEVARIABLE/TypeInherits
TYPE node value | CODEVARIABLE
NAME node value | TypeInherits
VALUE node value | <VariableType> | <BaseType>

The CODEVARIABLE/TypeInherits IDENTIFIER node combination is used to specify a code variable with <VariableType> or <BaseType>, meaning either the name of the variable type or the name of the base type. You need to make sure you specify the fully qualified name of the type, including the namespace, as shown in this example:

<IDENTIFIER>
   <TYPE>CODEVARIABLE</TYPE>
   <IDENTIFIERDATA>
      <NAME>TypeInherits</NAME>
      <VALUE>System.Web.UI.Control</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

While the CODEVARIABLE/TypeInherits covers the variable type, just like the CODEVARIABLE/TypeName IDENTIFIER node combination, it also covers the base class,if it's different from the variable type. This means that in the example shown here, any control derived from the System.Web.UI.Control can be identified with the ELEMENT node holding the IDENTIFIER node shown.

See the following section for information about the CODEVARIABLE TYPE scope.

CODEVARIABLE/TypeName
TYPE node value | CODEVARIABLE
NAME node value | TypeName
VALUE node value | <VariableType>

The CODEVARIABLE/TypeName IDENTIFIER node combination is used to specify a specific type of code variable with <VariableType>. You need to make sure you specify the fully qualified name of the type, including the namespace. See the description of the CODEVARIABLE/TypeInherits IDENTIFIER node combination for a comparison of the two CODEVARIABLE IDENTIFIER node combinations.

When you use CODEVARIABLE as the value of the TYPE node in an IDENTIFIERnode to identify an ELEMENT, you need to make sure you reference the ELEMENT node from the correct place. So, if you need to identify a specific class, such as the SqlDataAdapter class, you need to reference it from the right location. This means that if you reference it from a PROJECTITEM element, such as any kind of class file, the referenced IDENTIFIER node has class scope and not local procedure scope; if you exclude the referenced element, you can still use it in procedures, just not at the class level. Here is the CODEVARIABLE TYPE node definition:

<ELEMENT>
   <ID>codeSqlDataAdapter</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>CODEVARIABLE</TYPE>
         <IDENTIFIERDATA>
            <NAME>TypeName</NAME>
            <VALUE>System.Data.SqlClient.SqlDataAdapter</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>

The codeSqlDataAdapter ELEMENT identifies any code variable of type System.Data.SqlClient.SqlDataAdapter. The following ELEMENT is a PROJECTITEMdefinition, which explicitly excludes the codeSqlDataAdapter ELEMENT.

<ELEMENT>
   <ID>projWebService</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
          <TYPE>PROJECT</TYPE>
          <IDENTIFIERDATA>
             <NAME>Property:FileName</NAME>
             <VALUE>NewWebService.vbproj</VALUE>
          </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <EXCLUDE>codeSqlDataAdapter</EXCLUDE>
   </ELEMENTSET>
</ELEMENT>

So, now the codeSqlDataAdapter ELEMENT is excluded from the projWebServiceELEMENT, but what exactly does that mean in code? It means that any variables declared at the class level of type System.Data.SqlClient.SqlDataAdapter will be disallowed. However, if you declare a variable in a procedure within the class, you're allowed to do so. Listing 9-5 shows an example taken from a default Web service.

Listing 9-5. codeSqlDataAdapter ELEMENT Code Declaration Scope
Start example
 1 Imports System.Web.Services
 2
 3 <WebService(Namespace:="http://tempuri.org/NewWebService/Service1")> _
 4 Public Class Service1
 5    Inherits System.Web.Services.WebService
 6
 7    Private Service1Adapter As System.Data.SqlClient.SqlDataAdapter
 8
 9    <WebMethod()> Public Function HelloWorld() As String
10       Dim HelloWorldAdapter As System.Data.SqlClient.SqlDataAdapter
11
12       HelloWorld = "Hello World"
13    End Function
14 End Class
End example

In this example, we've omitted the auto-generated code to give you a better overview. The interesting point here is that the Service1Adapter variable declaration on line 7 is disallowed, while the HelloWorldAdapter variable declaration on line 10 is allowed.

Exercise 9-8 demonstrates the scope of the CODEVARIABLE TYPE node in an IDENTIFIER node.

Exercise 9-8
Start example

  1. Add the following to the NewEnterprisePolicy.tdl file, as the last ELEMENT node in the ELEMENTS node.

    <ELEMENT>
   <ID>codeSqlDataAdapter</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>CODEVARIABLE</TYPE>
         <IDENTIFIERDATA>
            <NAME>TypeName</NAME>
            <VALUE>System.Data.SqlClient.SqlDataAdapter</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>

  2. In your NewEnterprisePolicy.tdl file, insert the following line above the <INCLUDE>projItemVBCodeFile</INCLUDE> node in the ELEMENTSET node of the existing ELEMENT node with an ID of projWebService, shown in Listing 9-4 earlier in this chapter.

     <EXCLUDE>codeSqlDataAdapter</EXCLUDE>

  3. Save the policy file and create a new enterprise project based on the enterprise project file from Chapter 8, NewTemplateProject.etp.

  4. Copy Listing 9-5 to the Service1.asm.vb file of the NewWebService project of your new solution, replacing the existing code.

  5. Close and reopen VS .NET after making the changes, if it's open. In your Task List, you should now have a few policy reminders, and one of them is the reminder for line 6 of the code, as shown in Figure 9-11.

    Click To expand
    Figure 9-11: Policy reminder in the Task List

End example
HTMLELEMENT/Attribute:<AttributeName>
TYPE node value | HTMLELEMENT
NAME node value | Attribute:<AttributeName>
VALUE node value | <AttributeValue>

The HTMLELEMENT/Attribute:<AttributeName> IDENTIFIER node combination is used to specify an attribute of an HTML element with <AttributeName> and a value for it with the <AttributeValue>. This IDENTIFIER node combination is most often used in conjunction with the HTMLELEMENT/Tag node combination to specify an attribute and value for a specific HTML element/tag. This example shows how you can specify HTML elements with the align attribute set to left:

<IDENTIFIER>
   <TYPE>HTMLELEMENT</TYPE>
   <IDENTIFIERDATA>
      <NAME>Attribute:align</NAME>
      <VALUE>left</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
HTMLELEMENT/Tag
TYPE node value | HTMLELEMENT
NAME node value | Tag
VALUE node value | <TagValue>

The HTMLELEMENT/Tag IDENTIFIER node combination is used to specify an HTML element/tag, such as the TD tag, which is shown in this example:

<IDENTIFIER>
   <TYPE>HTMLELEMENT</TYPE>
   <IDENTIFIERDATA>
      <NAME>Tag</NAME>
      <VALUE>TD</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECT/FileExtension
TYPE node value | PROJECT
NAME node value | FileExtension
VALUE node value | <FileExtension>

Use the PROJECT/FileExtension IDENTIFIER node combination to specify a project using the project file extension, such as .csproj for C# specific projects, as in this example:

<IDENTIFIER>
   <TYPE>PROJECT</TYPE>
   <IDENTIFIERDATA>
      <NAME>FileExtension</NAME>
      <VALUE>.csproj</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

Don't forget to include the period as part of the extension. You can also use this IDENTIFIER node combination to specify an enterprise template project with .etp.

PROJECT/Global:<GlobalName>
TYPE node value | PROJECT
NAME node value | Global:<GlobalName>
VALUE node value | <GlobalValue>

Use the PROJECT/Global:<GlobalName> IDENTIFIER node combination to specify a project using a global value. Global values are global throughout an enterprise temple project file, and they must be specified using a GLOBALENTRY node in the GLOBALS node of the enterprise temple project file. See Chapter 8 for more information. Here is an example:

<IDENTIFIER>
   <TYPE>PROJECT</TYPE>
   <IDENTIFIERDATA>
      <NAME>Global:TDLELEMENTTYPE</NAME>
      <VALUE>WebServiceProjects</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECT/Kind
TYPE node value | PROJECT
NAME node value | Kind
VALUE node value | <GUID>

You can use the PROJECT/Kind IDENTIFIER node combination to specify an extensibility project using a GUID. This is for accessing the VS .NET Automation Object Model. Here is an example:

<IDENTIFIER>
   <TYPE>PROJECT</TYPE>
   <IDENTIFIERDATA>
      <NAME>Kind</NAME>
      <VALUE>{0291601F-21F2-47C7-9EEF-B829FFE7507B}</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECT/Property:<PropertyName>
TYPE node value | PROJECT
NAME node value | Property:<PropertyName>
VALUE node value | <PropertyValue>

Use the PROJECT/Property:<PropertyName> IDENTIFIER node combination to specify a project using a project property, such as FileName. This IDENTIFIER node combination is useful for singling out a specific project, such as is done in this example:

<IDENTIFIER>
   <TYPE>PROJECT</TYPE>
   <IDENTIFIERDATA>
      <NAME>Property:FileName</NAME>
      <VALUE>NewWebService.vbproj</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECTITEM/FileExtension
TYPE node value | PROJECTITEM
NAME node value | FileExtension
VALUE node value | <FileExtension>

Use the PROJECTITEM/FileExtension IDENTIFIER node combination to specify a project item using the project item file's extension, such as .aspx for a Web page project item. Don't forget to include the period as part of the extension. Here is an example:

<IDENTIFIER>
   <TYPE>PROJECTITEM</TYPE>
   <IDENTIFIERDATA>
      <NAME>FileExtension</NAME>
    <VALUE>.aspx</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECTITEM/Kind
TYPE node value | PROJECTITEM
NAME node value | Kind
VALUE node value | GUID

You can use the PROJECTITEM/Kind IDENTIFIER node combination to specify an extensibility project item using a GUID. This is for accessing the VS .NET Automation Object Model. Here is an example:

<IDENTIFIER>
   <TYPE>PROJECTITEM</TYPE>
   <IDENTIFIERDATA>
      <NAME>Kind</NAME>
      <VALUE>{C6149EDF-5063-4566-8296-5962098B009F}</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
PROJECTITEM/Property:<PropertyName>
TYPE node value | PROJECTITEM
NAME node value | Property:<PropertyName>
VALUE node value | <PropertyValue>

Use the PROJECTITEM/Property:<PropertyName> IDENTIFIER node combination to specify a project item using a project item property, such as FileName. This example shows how to identify a custom configuration file:

<IDENTIFIER>
   <TYPE>PROJECTITEM</TYPE>
   <IDENTIFIERDATA>
      <NAME>Property:FileName</NAME>
      <VALUE>MyApp.exe.config</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>
Reference/FileName
TYPE node value | REFERENCE
NAME node value | FileName
VALUE node value | <FileName>

You can use the Reference/FileName IDENTIFIER node combination to specify a component using the file name, including the extension. You need to use the fully qualified file name for the component, as shown in this example:

<IDENTIFIER>
   <TYPE>REFERENCE</TYPE>
   <IDENTIFIERDATA>
      <NAME>FileName</NAME>
      <VALUE>System.Data.dll</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

Often, you'll use this combination with one or both of the REFERENCE/MajorVersion and REFERENCE/MinorVersion combinations to explicitly state which component and version you're referencing.

When you identify COM or .NET components in your policy file using REFERENCEas the value for the TYPE node in an IDENTIFIER node, you need the fully qualified name of the component, but not the full path. So, you need to specify the fully qualified name of a .NET component, which means you need to include the namespace in which it's contained. One example is the Services component of the System.Web namespace, which must be specified as System.Web.Services.

A COM component is also specified using the fully qualified name, but it can be a little different than with .NET components. Here's the deal: The COM component must be registered[2] on your development machine.

If the COM component can be found in the \Program Files\Microsoft.NET\Primary Interop Assemblies folder, it has already been wrapped for easy access from a .NET application. The assemblies in this folder aren't the real COM components, but simply COM Interop assemblies—assemblies with a Runtime CallableWrapper (RCW) that takes care of the calls to and from the real COM component, which is usually located in the Windows\System32 folder.

If an Interop assembly is found in the \Program Files\Microsoft.NET\Primary Interop Assemblies folder, you need to specify only the file name and extension. However, if your COM component doesn't have an Interop assembly, you need to specify the name of the component prefixed with Interop., making a reference to Microsoft Office Runtime 1.0 Type Library look like this: Interop.MSORUNLib.dll. The file name for this COM component is MSORUN.DLL.

Okay, so far you know that when you have a COM component that doesn't have an Interop assembly, you prefix the file name with Interop. and add Lib to the end of file name, just before the extension (.DLL). But there's more to it. The Microsoft Office Runtime 1.0 Type Library is a special kind of COM component: a type library-only (there's only type information in the component, no executable code). The .NET Framework seems to differentiate type library-only components from "normal" COM components,[3] which is why the Lib is added to the end of the file name. We know, it's confusing, but see the following examples for clarification:

  • The classic ADO library, which has an Interop assembly, is referenced by its name and extension: adodb.dll.

  • The Microsoft Office Runtime 1.0 Type Library is referenced like this:Interop.MSORUNLib.dll.

  • A COM component that isn't a type library, like the Apple QuickTime Control, is referenced like this: Interop.QTActiveXPlugin.dll (the real file name of the component is QTActiveXPlugin.dll).

If you're in doubt about the name to specify for any kind of component, just add a reference to a project, and then select the component in the Solution Explorer. Then see the Name property in the Properties window, as shown in Figure 9-12. The value of this property, including the file extension (.dll), is the name you need to specify as the value for the VALUE node of the IDENTIFIERDATA node, when the value of the NAME node is set to FileName.

Click To expand
Figure 9-12: Component reference name shown in the Properties window
Reference/MajorVersion
TYPE node value | REFERENCE
NAME node value | MajorVersion
VALUE node value | <MajorVersion>

You can use the Reference/MajorVersion IDENTIFIER node combination to specify a component using the major version number of the component. Often, you'll use this combination with one or both of the REFERENCE/FileName and REFERENCE/MinorVersion combinations to explicitly state which component and which version you're referencing. Here is an example:

<IDENTIFIER>
   <TYPE>REFERENCE</TYPE>
   <IDENTIFIERDATA>
      <NAME>MajorVersion</NAME>
      <VALUE>1</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

A version number normally looks like this: 1.2.3 with 1 being the major version, 2 being the minor version, and 3 being the revision number. In the VALUEnode here, you need to specify an integer value, without a period to separate the major version from the minor version. If you do use a period, or if you specify any other characters than the numbers 0 through 9, your component won't be identified. It's not possible to specify the revision number that normally follows the minor version number.

Reference/MinorVersion
TYPE node value | REFERENCE
NAME node value | MinorVersion
VALUE node value | <MinorVersion>

You can use the Reference/MinorVersion IDENTIFIER node combination to specify a component using the minor version number of the component. Often, you'll use this combination with one or both of the REFERENCE/FileName and REFERENCE/MajorVersion combinations to explicitly state which component and which version you're referencing. As with the MajorVersion NAME node value, you need to specify an integer value and not include the period that normally separates the minor version from the major version. Here is an example:

<IDENTIFIER>
   <TYPE>REFERENCE</TYPE>
   <IDENTIFIERDATA>
      <NAME>MinorVersion</NAME>
      <VALUE>0</VALUE>
   </IDENTIFIERDATA>
</IDENTIFIER>

Defining ELEMENT Prototypes

The ELEMENT nodes you define in the ELEMENTS parent node either specify a prototypeor not. If your ELEMENT does specify a PROTOTYPES node, containing at least one valid PROTOTYPE node, the item represented by the ELEMENT node will be shown in the Add New Project or Add New Item dialog box. Which dialog box it's shown in depends on which type of ELEMENT it is.

Grouping Items

The CATEGORY node is for grouping your ELEMENT nodes in categories or groups of elements. The CATEGORY nodes are grouped in the CATEGORIES first-level container (surprise, eh?) node. One example of a group or category of nodes is shown in Listing 9-6.

Note

We guess Microsoft had to pick CATEGORY as the name of the grouping node, seeing as the ELEMENTS node was already taken as the container for ELEMENT nodes. Personally, we feel that GROUP would have been a better name, considering you might not be categorizing, but simply grouping your ELEMENT nodes. It's a matter of how you interpret the words we know, but it had to be said. That's the last you'll hear of that; promise, cross our hearts, hope to...
Listing 9-6. Category of ELEMENT Nodes
Start example
<CATEGORIES>
   <CATEGORY> <!-- Default XML Web service project items -->
      <ID>catXMLWebServiceProjectItems</ID>
      <CATEGORYMEMBER>projItemGlobalApplicationClass</CATEGORYMEMBER>
      <CATEGORYMEMBER>projItemDynamicDiscoFile</CATEGORYMEMBER>
      <CATEGORYMEMBER>projItemWebService</CATEGORYMEMBER>
      <CATEGORYMEMBER>projItemWebConfigFile</CATEGORYMEMBER>
      <CATEGORYMEMBER>projItemVBCodeFile</CATEGORYMEMBER>
      <CATEGORYMEMBER>projItemAssemblyResourceFile</CATEGORYMEMBER>
   </CATEGORY>
</CATEGORIES>
End example

A CATEGORY node must have a unique identifier, expressed using the ID node as shown in Listing 9-6. Then you simply add your ELEMENT nodes, or even other CATEGORY nodes, as CATEGORYMEMBER nodes to the CATEGORY node. Any value used for a CATEGORYMEMBER node must be defined as an ELEMENT or a CATEGORY node elsewhere in the policy file, or you'll get an error when a project associated with the policy file is opened.

Using ELEMENT Expressions

The TDL keywords INTERSECT, SUBTRACT, and UNION are used for including and excluding ELEMENT nodes. This also means that you cannot use these keywords as names or IDs for items or other elements in your policy file. The keywords are used with INCLUDE and EXCLUDE nodes as part of forming an element or category name. Each keyword has the following syntax:

<Name> TDL keyword <Name>

In the following example using INTERSECT, the INCLUDE node will include all features shared by the projItemVBCodeFile and projWebService elements:

<INCLUDE>projItemVBCodeFile INTERSECT projWebService</INCLUDE>

In the following example using SUBTRACT, the INCLUDE node will include all features in the projItemVBCodeFile element that are not in the projWebServiceelement:

<INCLUDE>projItemVBCodeFile SUBTRACT projWebService</INCLUDE>

And in this example using UNION, the INCLUDE node will include all features in the projItemVBCodeFile and the projWebService elements:

<INCLUDE>projItemVBCodeFile UNION projWebService</INCLUDE>

You can see how you can form element expressions for the INCLUDE and EXCLUDEnodes of an ELEMENTSET node, using the INTERSECT, SUBTRACT, and UNION keywords. Although the examples use names/IDs of ELEMENT nodes, you can also use the names of CATEGORY nodes.

Configuring the VS .NET IDE Using Policies

Because the VS .NET IDE can be customized with policies, you have a powerful tool for guiding and/or restricting the developers when they work on various parts of your enterprise solution. You can set up policies so that certain menus and menu items that are available in some projects are not available in others, based on what the developers are working on and what is currently selected. For example, you might want to disable the Add New Item dialog box only in a Web service project, because you don't want any other items added to your Web service, which must be as simple as possible.

The following items can be managed with policies:

  • Add New Item dialog box

  • Add New Project dialog box

  • Dynamic Help window

  • Menus

  • Properties window

  • Solution Explorer

  • Toolbox

The Solution Explorer isn't managed explicitly with policies. Rather, what you see of projects, project items, components, and so on is constrained by policiesapplied to the other items. The topics displayed in the Dynamic Help window can be customized using the CONTEXT node and its child nodes. Chapter 10 covers how to manage custom help. The following sections explain how to manage the other listed items.

Configuring the Add New Item and Add Project Dialog Boxes

You can control the items shown in the Add New Item dialog box (opened by choosing File ® Add ® New Item) and the Add New Project dialog box (opened by choosing File®New®Project), specifying which items are displayed and which items do not appear. This way, you can ensure that only displayed items can be added to a project or only displayed projects can be added to your enterprise template project.

There are two ways to approach this:

  • Display all valid items or projects by default: In your policy file, set the POLICYMODE node within the DEFAULTSETTINGS first-level node to PERMISSIVE.

  • Display no valid items or projects by default: In your policy file, set thePOLICYMODE node within the DEFAULTSETTINGS first-level node to RESTRICTIVE.

In order to control the individual items or projects that are shown in the Add New Item or Add New Project dialog box, you must add the items or projects as ELEMENT nodes to the ELEMENTS first-level node, and then explicitly INCLUDE or EXCLUDEthem from the individual projects (for items) or from the enterprise template project element (for projects).

Tip

If you don't want the developers to add any items to a project, simply disable the File ®Add ® New Item menu item. See the "Configuring the IDE Menus" section later in this chapter for more information.

When the Add New Item or Add New Project dialog box is opened in a solution with an associated policy file, the policy file validates the project items or projects that are normally valid[4] for the project to which you're trying to add the project item or for the enterprise template project to which you're trying to add the project. The validation routine first looks at the POLICYMODE setting. If it's set to RESTRICTIVE, all valid items or projects are excluded by default; if POLICYMODEis set to PERMISSIVE, all valid project items or projects are included by default.

This list of valid project items or projects is then validated against the INCLUDE(RESTRICTIVE) or EXCLUDE (PERMISSIVE) nodes within the ELEMENTSET node of the project's ELEMENT node. This means that project items or projects listed as EXCLUDEnodes with a PERMISSIVE POLICYMODE will be excluded, and project items listed as INCLUDE nodes with a RESTRICTIVE POLICYMODE, will be included. This also means that INCLUDE nodes are ignored with a PERMISSIVE POLICYMODE, and EXCLUDE nodes are ignored with a RESTRICTIVE POLICYMODE, because they're already included/excluded by default. (See Figure 9-8 earlier in this chapter for a graphical representation of the default item policy.)

Okay, so the validation routine looks at the list of valid project items or projects and compares it to the INCLUDE or EXCLUDE nodes, but that isn't all there's to it. The INCLUDE and EXCLUDE nodes refer to ELEMENT nodes, and these nodes must contain a PROTOTYPES node, with an appropriate PROTOTYPE node to be considered for display in the dialog box. An appropriate node in this case means that if your project is a VB .NET project, the prototype must be a VB .NET prototype. Listing 9-7 shows an example of specifying a project item PROTOTYPE.

Listing 9-7. Specifying a Project Item PROTOTYPE for an ELEMENT Node
Start example
<ELEMENT>
   <ID>projItemXMLSchema</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.XSD</VALUE>
         </IDENTIFIERDATA>
       </IDENTIFIER>
   </IDENTIFIERS>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjectItems\XSDSchema.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
End example

In Listing 9-7, you can see the projItemXMLSchema element defined. This has been copied straight from the VSIDE.tdl file. If you leave out the PROTOTYPESelement entirely from Listing 9-7, you can't use it in the Add New Item dialog box. Also, if you add a C# prototype to your policy file like this:

<PROTOTYPES>
   <PROTOTYPE>[VC#]\CSharpProjectItems\CSharpAddXMLSchema.vsz</PROTOTYPE>
</PROTOTYPES>

and this policy file is associated with a VB .NET specific enterprise template, you won't be able to use it in the Add New Item dialog box.

It's pretty simple really, because why would you want to display an item in the dialog box that VS .NET doesn't know how to add to a project?

In Exercise 9-9, you'll apply what you've learned so far in this chapter to determine how a policy file controls items in the Add New Item dialog box.

Exercise 9-9
Start example

  1. Copy the listing from Exercise 9-6 into a blank text file. Your policy file, which is associated with the NewTemplateProject.etp enterprise template created in Chapter 8, should look like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <CONSTRAINTS>
         <MENUCONSTRAINTS></MENUCONSTRAINTS>
         <PROPERTYCONSTRAINTS></PROPERTYCONSTRAINTS>
         <TOOLBOXCONSTRAINTS></TOOLBOXCONSTRAINTS>
      </CONSTRAINTS>
   </DEFAULTSETTINGS>
   <ELEMENTS>
   </ELEMENTS>
</TDL>

  2. Add Listing 9-8 to the existing ELEMENTS node.

    Listing 9-8. Project Item ELEMENT Nodes for Add New Item Dialog Box Configuration

    Start example

    <ELEMENT>
   <ID>projItemVBCodeFile</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.vb</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
<ELEMENT>
   <ID>projItemXMLSchema</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.XSD</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjectItems\XSDSchema.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
<ELEMENT>
   <ID>projItemXMLFile</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.xml</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjectItems\XMLFile.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
<ELEMENT>
   <ID>projItemXSLTFile</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.xslt</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjectItems\XSLTFile.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
    End example

  3. Add Listing 9-9 to the existing ELEMENTS node.

    Listing 9-9. Project ELEMENT Nodes for Add New Item Dialog Box Configuration

    Start example

    <ELEMENT>
   <ID>projBusinessFacade</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
            <VALUE>BusinessFacade</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>INCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <INCLUDE>projItemVBCodeFile</INCLUDE>
   </ELEMENTSET>
</ELEMENT>
<ELEMENT>
   <ID>projWebService</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>NewWebService.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>INCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <INCLUDE>projItemXMLSchema</INCLUDE>
      <INCLUDE>projItemXMLFile</INCLUDE>
      <INCLUDE>projItemXSLTFile</INCLUDE>
   </ELEMENTSET>
</ELEMENT>
    End example

  4. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

  5. Create a new project based on the NewTemplateProject.etp enterprise template created in Chapter 8, and name this project EnterpriseTemplateProject1.

  6. Your job is to find out which items are displayed in the Add New Item dialog box for the two project ELEMENT nodes you added in step 3, when the corresponding project is selected in the Solution Explorer. The question is a bit tricky, because it depends on the value of the POLICYMODE node in the DEFAULTSETTINGS node. Therefore, you need to figure out which items are displayed when the POLICYMODE node is set to RESTRICTIVE and which items appear when it is set to PERMISSIVE. You can find the answer to this question at the end of this chapter.

End example

To control the projects listed in the Add New Project dialog box, you must specify a project PROTOTYPE for an ELEMENT node, within a PROTOTYPES node. The PROTOTYPE node must be appropriate to be considered for display in the dialog box. In this case, an appropriate node means that if your enterprise template project is a VB .NET-only project, the prototype must be a VB .NET prototype, as shown in Listing 9-10.

Tip

If you don't want the developers to add any projects to an enterprise template project, simply disable the File ®New®Project menu item. See the "Configuring the IDE Menus" section later in this chapter for more information, but replace the menuFile.AddNewItem value of the MENULINK node with menuFile.AddNewProject.
Listing 9-10. Specifying a Project PROTOTYPE for an ELEMENT Node
Start example
<ELEMENT>
   <ID>projVBWindowsApp</ID>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjects\WindowsApplication.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
End example

In Listing 9-10, you can see the projVBWindowsApp element defined. This has been copied straight from the VSIDE.tdl file. As with the Add New Item dialog box, if you leave out the PROTOTYPES element entirely from Listing 9-10, or if you add a C# project prototype to your policy file that is associated with a VB .NET specific enterprise template, as in the following example, and you use this prototype, you can't use it in the Add New Project dialog box.

<PROTOTYPES>
   <PROTOTYPE>[VC#]\CSharpProjects\CSharpEXE.vsz</PROTOTYPE>
</PROTOTYPES>

Again, the reason for this is straightforward: Why would you want to display a project in the dialog box that VS .NET doesn't know how to add to the enterprise template project?

In Exercise 9-10, you'll see how you can control projects listed in the Add New Project dialog box.

Exercise 9-10
Start example

  1. Copy the listing from Exercise 9-6 into a blank text file. Your policy file, which is associated with the NewTemplateProject.etp enterprise template created in Chapter 8, should look like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <CONSTRAINTS>
         <MENUCONSTRAINTS></MENUCONSTRAINTS>
         <PROPERTYCONSTRAINTS></PROPERTYCONSTRAINTS>
         <TOOLBOXCONSTRAINTS></TOOLBOXCONSTRAINTS>
      </CONSTRAINTS>
   </DEFAULTSETTINGS>
   <ELEMENTS>
   </ELEMENTS>
</TDL>

  2. Add Listing 9-11 to the existing ELEMENTS node.

    Listing 9-11. Project ELEMENT Nodes for Add New Project Dialog Box Configuration

    Start example

    <ELEMENT>
   <ID>projVBWindowsApp</ID>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjects\WindowsApplication.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
<ELEMENT>
   <ID>projBusinessFacade</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
            <VALUE>BusinessFacade</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
<ELEMENT>
   <ID>projWebService</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>NewWebService.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
    End example

  3. Add Listing 9-12 to the existing ELEMENTS node.

    Listing 9-12. Enterprise Project ELEMENT Nodes for Add New Project Dialog Box Configuration

    Start example

    <ELEMENT>
   <ID>projEnterpriseTemplateProject1</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.etp</VALUE>
         </IDENTIFIERDATA>
     </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>INCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <INCLUDE>projBusinessFacade</INCLUDE>
      <INCLUDE>projWebService</INCLUDE>
      <INCLUDE>projVBWindowsApp</INCLUDE>
   </ELEMENTSET>
</ELEMENT>
<ELEMENT>
   <ID>projEnterpriseTemplateProject2</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.etp</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
    End example

  4. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

  5. Create a new project based on the NewTemplateProject.etp enterprise template created in Chapter 8, and name this project EnterpriseTemplateProject2. (EnterpriseTemplateProject1 has already been created earlier in this chapter.)

  6. Your job is to find out which projects are displayed in the Add New Project dialog box, for the two enterprise template project ELEMENT nodes you added in step 3, when they are selected in the Solution Explorer. The answer depends on the value of the POLICYMODE node in the DEFAULTSETTINGS node. So, you need to figure out which projects are displayed when the POLICYMODE node is set to RESTRICTIVE and when it is set to PERMISSIVE. The answer is given at the end of this chapter.

End example

Configuring the IDE Menus

To control which menus and menu items are shown, you must add the items to the FEATURES first-level node. Actually, you must first add the MENUS element as a child element of the FEATURES element, and then you can add your menus and menu items as MENU elements to the MENUS element.

Note

Although you don't need to define every menu or menu item in the VS .NET IDE as child elements in the FEATURES node, only menus or menu items that have been defined as MENU elements can be disabled or enabled from elsewhere in the policy file. If you try to reference a menu or menu item that hasn't been defined in the FEATURES node elsewhere in your policy file, an error message is displayed when you try to create a new project or project item that is based on an enterprise template project that references your policy file.

Say you want to be able to control if the File ® Add ® New Item menu item is shown. First, you need to add this menu item, as a MENU element, as shown in Listing 9-13.

Listing 9-13. Adding Menu Items to the FEATURES Node
Start example
<FEATURES>
   <MENUS>
      <MENU>
         <ID>menuFile.AddNewItem</ID>
         <CMDID>220</CMDID>
         <GUID>{5EFC7975-14BC-11CF-9B2B-00AA00573819}</GUID>
      </MENU>
   </MENUS>
</FEATURES>
End example

In Listing 9-13, we've defined the File ® Add ® New Item menu item, which is internally referred to as menuFile.AddNewItem. This means that this menu item can now be disabled and enabled elsewhere in the policy file. However, how do you know which properties (ID, CMDID, and GUID) a particular menu or menu item has? You cheat, and look it up in the VSIDE.tdl file, usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. This file holds the properties for all the standard menu items used within the VS .NET IDE.

Tip

Although menu items aren't located in one place in the VSIDE.tdl file, it's easy to find them. If you look them up by ID (which is the easiest way), you can search for menu + <menu name> + . + <menu item name>, which is menuFile.AddNewItem in the case of the File ® Add ®New Item menu item. You can nearly always guess the full name by looking at the names displayed for the menu and menu items. You always start with the word menu, followed by the menu name (no spaces) and a period, and then the menu item name.

You can copy the menu property values from the VSIDE.tdl file. All three child elements— CMDID, GUID, and ID—must be specified for a MENU element. The GUID element references a menu group and, in combination with the CMDID element,guarantees a unique menu item. This also means that no two MENU elements can have the same values for both the GUID and CMDID child elements. Although it seems that the GUID element is superfluous with regard to identification, it's necessary because it makes it accessible from VS .NET Automation Object Model.

Once your menus and menu items have been defined in the FEATURES node, you can disable and enable them from elsewhere in your project. All menus and menu items are enabled by default, depending on the current selection in the IDE, such as in a designer, an editor, or the Solution Explorer.

Note

You can't enable a menu or menu item that has been disabled by Visual Studio.

You can disable or enable a defined menu or menu item by using two techniques: constraints and feature links. These approaches are described in the following sections.

Configuring Menus Using Constraints

Constraints work by explicitly disabling or enabling a menu or menu item, as shown in Listing 9-14.

Listing 9-14. Using Constraints to Disable a Menu or Menu Item
Start example
<CONSTRAINTS>
   <MENUCONSTRAINTS>
      <MENUCONSTRAINT>
         <ID>menuFile.AddNewItem</ID>
         <ENABLED>0</ENABLED>
      </MENUCONSTRAINT>
   </MENUCONSTRAINTS>
</CONSTRAINTS>
End example

In Listing 9-14, you can see how the File ®Add ® New Item menu item is explicitly disabled by setting the value of the ENABLED element to 0; setting it to 1 will enable it. The CONSTRAINTS element can appear in three different parent nodes: DEFAULTSETTINGS, ELEMENT, and ELEMENTSET. If it appears in the DEFAULTSETTINGSnode, the menu or menu item is disabled by default, unless it's specifically enabled in a context-based scenario.

So, the lesson here is that if you want to explicitly disable a particular menu or menu item, you must first define it as a MENU node in the FEATURES node, and then add a MENUCONSTRAINTS node, which references the defined node, to the CONSTRAINTS child node in the DEFAULTSETTINGS node.

In Exercise 9-11, you will disable a menu item by using constraints in a policy file.

Exercise 9-11
Start example

  1. Copy the listing from Exercise 9-6 into a blank text file. Your policy file should look like this:

    <TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
   <DEFAULTSETTINGS>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <POLICYMODE>RESTRICTIVE</POLICYMODE>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <CONSTRAINTS>
         <MENUCONSTRAINTS></MENUCONSTRAINTS>
         <PROPERTYCONSTRAINTS></PROPERTYCONSTRAINTS>
         <TOOLBOXCONSTRAINTS></TOOLBOXCONSTRAINTS>
      </CONSTRAINTS>
   </DEFAULTSETTINGS>
   <ELEMENTS>
   </ELEMENTS>
</TDL>

  2. Add Listing 9-13 after the ELEMENTS node, but before the TDL node.

  3. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

  4. Add the MENUCONSTRAINT element and contained subelements from Listing 9-14 to the existing MENUCONSTRAINTS element of the NewEnterprisePolicy.tdl file.

This disables the File ® Add ® New Item menu item when an enterprise template project that is associated with the policy file containing the code in the listing is selected in the Solution Explorer, as shown in Figure 9-13.

Click To expand
Figure 9-13: File ® Add ® New Item menu item disabled by a constraint

End example
Configuring Menus Using Associations

Menu associations are MENULINKS nodes that are links or MENU nodes associated with ELEMENT nodes, as shown in Listing 9-15.

Listing 9-15. Using Associations to Disable a Menu or Menu Item
Start example
<ELEMENT>
   <ID>projWebService</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>NewWebService.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>INCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <EXCLUDE>projWebService</EXCLUDE>
   </ELEMENTSET>
   <FEATURELINKS>
      <MENULINKS>
         <MENULINK>menuFile.AddNewItem</MENULINK>
      </MENULINKS>
   </FEATURELINKS>
</ELEMENT>
End example

In Listing 9-15, we've defined the projWebService ELEMENT for the NewWebServiceproject, which is part of the NewTemplateProject enterprise template project created in Chapter 8. Using a MENULINK node for the File ® Add® New Item menu item, associated with the projWebService ELEMENT, the menu item will be disabled whenever the projWebService ELEMENT is excluded from an ELEMENTSET, implicitly or explicitly. The <EXCLUDE>projWebService</EXCLUDE> element in Listing 9-15 will disable the File ® Add ® New Item menu item when the NewWebService project is selected in the Solution Explorer.

In Exercise 9-12, you will disable a menu item by using associations.

Exercise 9-12
Start example

  1. Add the listing in Exercise 9-6 to a blank text file.

  2. Add Listing 9-13 after the ELEMENTS node, but before the TDL node.

  3. Add Listing 9-15 to the ELEMENTS node.

  4. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

  5. Open the NewTemplateProject1 solution you created in Exercise 9-4 earlier in this chapter.

  6. Select the NewWebService project in the Solution Explorer and see how the File ® Add ® New Item menu item is disabled. Select any other item in the Solution Explorer, and the menu item is enabled.

End example

Configuring the Properties

The properties of a project item, toolbox item, a component, and any other item with user-configurable properties are displayed in the Properties window, where you can edit them. However, sometimes it can be a good idea to control if and how the properties can be edited. This way, you can ensure that the developers don't accidentally set an incorrect value for a property. You might also want to use this approach when you need to set a property to a specific value, such as a connection string for your database, default menu and menu item captions, Windows form captions, labels, and so on.

Caution

Some properties are runtime environment-dependent, meaning that you're probably using development servers when developing. In most cases, this results in different paths, server names, database names, and so on. So, in many cases, you should allow the developers to modify a default database connection string (or similar property) that is different depending on the runtime environment. Optionally, you can choose to specify the properties for the development runtime environment, and then change these properties when you deploy your applications to a production environment.

The following nodes are used to control a property:

  • DEFAULT

  • MAXVALUE

  • MINVALUE

  • NAME

  • PROPERTYCONSTRAINT

  • PROPERTYCONSTRAINTS

  • READONLY

You need the PROPERTYCONSTRAINTS node with zero or more PROPERTYCONSTRAINTnodes. Well, there's no point in having an empty PROPERTYCONSTRAINTS node, so let's just say one or more PROPERTYCONSTRAINT nodes. Within each defined PROPERTYCONSTRAINT node, you must specify at least the NAME and READONLY nodes. The DEFAULT, MAXVALUE, and MINVALUE nodes are optional. However, depending on what kind of property restriction or guideline you're creating, you'll need to specify at least one of the optional nodes as well.

Note

The optional child nodes of the PROPERTYCONSTRAINT node can all be specified at the same time, but specifying one might mean another node is ignored. If you specify a value for the DEFAULT node, the other two optional nodes (MAXVALUE and MINVALUE) and the required READONLY node are ignored. If you set the value of the READONLY node to 1 (True), the MINVALUE and MAXVALUE nodes are ignored. The lesson here is that you might potentially confuse a developer or analyst trying to figure out the logic of your policy file, if you do specify all the optional nodes at the same time.

Listing 9-16 shows what you need in order to specify one property restriction or guideline.

Listing 9-16. Minimum Property Constraint Definition
Start example
<PROPERTYCONSTRAINTS>
   <PROPERTYCONSTRAINT>
      <NAME></NAME>
      <DEFAULT></DEFAULT>
   </PROPERTYCONSTRAINT>
</PROPERTYCONSTRAINTS>
End example

The NAME node is the exact programming name of the property, not the display name. So, if you're running a localized version of VS .NET, you might want to look it up in the code editor or in the Object Browser (displayed by pressing Ctrl-Alt-J), to make sure you type in the correct name.

Note

Design-time properties, such as those exposed by the many VS .NET designers, can't be controlled with a policy file. These properties can't be set from code, and as such there's no point in trying to restrict or guide your developers by setting the values of them. One such example is the Locked property of the Windows Forms designer, which prevents controls placed on a Windows form from being moved, if set to True.

Listing 9-17 shows how a Windows Forms Label element is defined.

Listing 9-17. Windows Forms Label Defined
Start example
<ELEMENT>
   <ID>codeWinFormsLabel</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>CODEVARIABLE</TYPE>
         <IDENTIFIERDATA>
            <NAME>TYPENAME</NAME>
            <VALUE>System.Windows.Forms.Label</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
End example

In Listing 9-17, you can see the codeWinFormsLabel UI control defined. This ELEMENT node must then be referenced implicitly[5] or explicitly, using an INCLUDE node in the ELEMENTSET node of a parent ELEMENT node, as is done in Listing 9-18.

Listing 9-18. Setting Property Constraints for an Included ELEMENT Node
Start example
<ELEMENT>
   <ID>projVBWindowsApp</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
      <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>WindowsApplication1.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <INCLUDE>codeWinFormsLabel</INCLUDE>
      <CONSTRAINTS>
         <PROPERTYCONSTRAINTS>
            <PROPERTYCONSTRAINT>
               <NAME>Location.X</NAME>
               <DEFAULT>0</DEFAULT>
               <READONLY>0</READONLY>
            </PROPERTYCONSTRAINT>
            <PROPERTYCONSTRAINT>
               <NAME>Location.Y</NAME>
               <DEFAULT>0</DEFAULT>
               <READONLY>0</READONLY>
            </PROPERTYCONSTRAINT>
         </PROPERTYCONSTRAINTS>
      </CONSTRAINTS>
   </ELEMENTSET>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjects\WindowsApplication.vsz</PROTOTYPE>
   </PROTOTYPES>
</ELEMENT>
End example

In Listing 9-18, we've included the codeWinFormsLabel element defined in Listing 9-17 as part of the ELEMENTSET for the parent projVBWindowsApp ELEMENTnode. You can also see that two PROPERTYCONSTRAINT nodes have been defined for the Location.X and Location.Y properties.[6]

Note

The projVBWindowsApp ELEMENT node has been defined using an IDENTIFIERDATA node that specifies that exact name of a project file, namely WindowsApplication1.vbproj. Obviously, this is just for test purposes; just assume that a new VB .NET Windows application project added to our solution will be named this way.

The default values for the two defined properties have been set to 0. Now, if you add a VB .NET Windows application named WindowsApplication1 to a solution based on the NewEnterpriseTemplate.etp enterprise template, any label control on a form in the project that doesn't have the default values for the X and Y properties will prompt a policy reminder in the Task List.

In Exercise 9-13, you will configure the Location property for Label controls.

Exercise 9-13
Start example

  1. Add the listing in Exercise 9-6 to a blank text file.

  2. Add Listing 9-17 to the ELEMENTS node.

  3. Add Listing 9-18 to the ELEMENTS node.

  4. Open the NewTemplateProject1 solution you created in Exercise 9-4 earlier in this chapter. (Close and reopen it, if it's already open.)

  5. Add a VB .NET Windows application named WindowsApplication1 to the NewTemplateProject1 project.

  6. Open Form1 in design view.

  7. Drag a Label control onto Form1.

  8. Change the X and Y properties of the Location property to 62 and 66.

  9. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. Now, the Task List has two policy reminders about the X and Y properties, as shown in Figure 9-14. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

    Click To expand
    Figure 9-14: Policy reminders in the Task List noting wrong property values

End example

Configuring the Toolbox

To control which toolbox items are shown, you must add the items to the FEATURESfirst-level node. First, you must add the TOOLBOXITEMS element as a child element of the FEATURES element, and then you can add your toolbox items as TOOLBOXITEMelements to the TOOLBOXITEMS node.

Note

Although you don't have to define every toolbox item in the VS .NET IDE as child elements in the FEATURES node, only toolbox items that have been defined as TOOLBOXITEM elements can be disabled or enabled from elsewhere in the policy file. If you try to reference a toolbox item that hasn't been defined in the FEATURES node elsewhere in your policy file, an error message is displayed when you try to create a new project or project item that is based on an enterprise template project that references your policy file.

Suppose that you want to be able to control if the Windows Forms Label toolbox item is shown. First, you need to add this toolbox item as a TOOLBOXITEMnode, as shown in Listing 9-19.

Listing 9-19. Adding Toolbox Items to the FEATURES Node
Start example
<FEATURES>
   <TOOLBOXITEMS>
      <TOOLBOXITEM>
         <ID>tboxWinFormsLabel</ID>
         <DESCRIPTOR>System.Windows.Forms.Label</DESCRIPTOR>
      </TOOLBOXITEM>
   </TOOLBOXITEMS>
</FEATURES>
End example

In Listing 9-19, we've defined the Label toolbox item, using the name tboxWinFormsLabel for internal reference. This means that this toolbox item can now be disabled and enabled elsewhere in the policy file. You can use any name as the ID for a toolbox item, but all the intrinsic toolbox items have already been defined in the VSIDE.tdl file, so it's easier just to copy it across from there.

All toolbox items are enabled by default, depending on the current selection in the IDE, such as in a designer, an editor, or the Solution Explorer.

Note

You can't enable a toolbox item that has been disabled by Visual Studio.

As with menu items, you can disable or enable a defined toolbox item by using either constraints or feature links, as described in the following sections.

Configuring the Toolbox Using Constraints

Toolbox constraints work by explicitly disabling or enabling a toolbox item, as shown in Listing 9-20.

Listing 9-20. Using Constraints to Disable a Toolbox Item
Start example
<CONSTRAINTS>
   <TOOLBOXCONSTRAINTS>
      <TOOLBOXCONSTRAINT>
         <ID>tboxWinFormsLabel</ID>
         <ENABLED>0</ENABLED>
      </TOOLBOXCONSTRAINT>
   </TOOLBOXCONSTRAINTS>
</CONSTRAINTS>
End example

In Listing 9-20, you can see how the Windows Forms Label toolbox item is explicitly disabled by setting the value of the ENABLED element to 0; setting it to 1 will enable it. The CONSTRAINTS element can appear in the DEFAULTSETTINGS, ELEMENT, and ELEMENTSET parent nodes. If it appears in the DEFAULTSETTINGS node, the toolbox item is disabled by default, unless it's specifically enabled in a context-based scenario. This means that if you want to explicitly disable a particular toolbox item, you must first define it as a TOOLBOXITEM node in the FEATURES node, and then add a TOOLBOXCONSTRAINTS node that references the defined node to the CONSTRAINTSchild node of the DEFAULTSETTINGS node.

In Exercise 9-14, you will configure a toolbox item using constraints.

Exercise 9-14
Start example

  1. Add the listing in Exercise 9-6 to a blank text file.

  2. Add Listing 9-19 after the ELEMENTS node, but before the TDL node.

  3. Save the file as NewEnterprisePolicy.tdl in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. You might want to back up the existing NewEnterprisePolicy.tdl file, if you've been following the previous Exercises.

  4. Add the TOOLBOXCONSTRAINT element and contained subelements from Listing 9-20 to the existing TOOLBOXCONSTRAINTS element of this NewEnterprisePolicy.tdl file.

This disables the Windows Forms Label toolbox item when an enterprise template project that is associated with the policy file containing the code in the listing is selected in the Solution Explorer, as shown in Figure 9-15.

Click To expand
Figure 9-15: The Windows Forms Label toolbox item disabled by a constraint

End example
Configuring the Toolbox Using Associations

Toolbox associations are TOOLBOXLINKS nodes that are links or TOOLBOXITEM nodes associated with ELEMENT nodes, as shown in Listing 9-21.

Listing 9-21. Using Associations to Disable a Toolbox Item
Start example
<ELEMENT>
   <ID>projVBWindowsApp</ID>
   <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECT</TYPE>
         <IDENTIFIERDATA>
            <NAME>Property:FileName</NAME>
            <VALUE>WindowsApplication1.vbproj</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
   <ELEMENTSET>
      <DEFAULTACTION>INCLUDE</DEFAULTACTION>
      <ORDER>INCLUDEEXCLUDE</ORDER>
      <EXCLUDE>projVBWindowsApp</EXCLUDE>
   </ELEMENTSET>
   <PROTOTYPES>
      <PROTOTYPE>[VB]\VBProjects\WindowsApplication.vsz</PROTOTYPE>
   </PROTOTYPES>
   <FEATURELINKS>
      <TOOLBOXLINKS>
         <TOOLBOXLINK>tboxWinFormsLabel</TOOLBOXLINK>
      </TOOLBOXLINKS>
   </FEATURELINKS>
</ELEMENT>
End example

In Listing 9-21, we've defined the projVBWindowsApp ELEMENT for the WindowsApplication1 project. Using a TOOLBOXLINK node for the Windows Forms Label toolbox item, associated with the projVBWindowsApp ELEMENT node, the toolbox item will be disabled whenever the projVBWindowsApp ELEMENT is excluded from an ELEMENTSET, implicitly or explicitly.

The <EXCLUDE>projVBWindowsApp</EXCLUDE> element in Listing 9-21 will disable the Windows Forms Label toolbox item when the projVBWindowsApp project is selected in the Solution Explorer. Well, if the project is selected, the Windows Form tab won't be displayed in the toolbox, so what we mean is that if an appropriate child project item of the projVBWindowsApp project is selected, then the Windows Forms Label toolbox item will be disabled. An appropriate project item in this case is a Windows Form.

[1]A component, in this case, can be a COM(+) component or a .NET assembly.

[2]This usually means registered in the Registry. This can be done manually using the regsvr32.exe utility, which is normally found in the Windows\System32 folder.

[3]In a "normal" COM component, the type information is embedded in the resource section of the DLL or EXE file. This is the case with COM components created in Visual Basic 6 and earlier.

[4]A valid project item is an item that can be used within the project. This means that a Windows Form project item isn't valid in an ASP.NET Web application. A valid project is a project that can be used within the enterprise template project. This means that a C# project item isn't valid in a VB .NET enterprise template project.

[5] Implicitly in this case means that the ELEMENT node has been defined and the DEFAULTACTION child node of the ELEMENTSET node has been set to INCLUDE.

[6]The Location property is a very common property of just about all Windows Form controls with a UI, and it is used to control the position of the upper-left corner of the control. The Location property is an example of a property with two or more properties, called nested properties. You can specify a nested property using a period as the delimiter, as in Location.X.


Policy Validation

The policy files wouldn't be any good if no validation of the associated solution and projects were to take place. The policy file validation doesn't work by enforcingthe constraints set up in the policy file; instead, it works by adding a policy reminder to the Task List, as shown in Figure 9-11 earlier in this chapter. This policy reminder holds a description of the problem and the location of the offending item, as well as the location of the policy definition that triggers the policy reminder.

So, what good does the policy validation do, if it doesn't enforce the policy? Well, personally we think that it's good that the policy isn't enforced, because especially on new projects, you'll be making changes to the policy as you go along. If you needed to change the policy file every time you found a problem, such as a specific component being disallowed, you would have developers waiting for the change. Instead, it's better to let the developers break the policy temporarily, until the policy has been fixed. It's a matter of preference, really.

There's one good thing about the policy reminders for code reviewers: They can simply open the solution and see exactly which policies have been broken. Now, this won't suffice for some code reviews, but for a quick review of how the developers are getting on, it will save a lot of time.

Tip

The policy validation is a check of how the solution and projects conform to the associated policy file.

Policy reminders or validation errors can be fixed in two ways: You kill the messenger or do as he says! (Well, figuratively speaking.) This means that either you drop the policy that triggers the validation error or you correct the problem in the solution.


TDL Nodes

This section provides a reference to all of the TDL nodes that you can use in your policy files. Table 9-2 lists all the nodes, if they're required, and what other nodes they work with. The Max. Occurrences column refers to the maximum number of nodes within the parent node, not in the entire policy file. A hyphen (-) means there are no restrictions on the number of nodes. The descriptions are by no means exhaustive, but Table 9-2 serves as a quick reference for most of the information you need to use the TDL nodes.

Table 9-2: TDL Nodes
Node Name | Description | Required in Parent Node | Parent Node(s) | Child Node(s) | Max. Occurrences
CATEGORIES | Holds all the categories in the policy file, if any; basically, merely a container. | No | TDL | CATEGORY | 1
CATEGORY | Can be used as an alias for ELEMENT and other CATEGORY nodes. By using this node as an alias for a group of ELEMENT and CATEGORY nodes, you reduce the amount of text in your policy files, because you need to reference only the CATEGORY node, instead of all the elements it contains. | No | CATEGORIES | CATEGORYMEMBER,ID | -
CATEGORYMEMBER | Hold the ID of a CATEGORY or ELEMENT | No | CATEGORY | - | -
CMDID | Indicates a menu item's position in a menu hierarchy. The value must be an integer or a defined integer constant, and it must be unique. | Yes | MENU | - | 1
CONSTRAINTS | A container for context-based restrictions in the IDE, such as menu items, the toolbox, or the Properties window. | No | DEFAULTSETTINGS ELEMENT , ELEMENTSET | MENUCONSTRAINTS , PROPERTYCONSTRAINTS , TOOLBOXCONSTRAINTS | 1
CONTEXT | Used in connection with context- based information displayed in the Dynamic Help window | No | ELEMENT | CTXTATTRIBUTE CTXTKEYWORD | 1
CTXATTRIBUTE | Hold a NAME and VALUE pair, which is used for restricting or constrain-ing the help topics found with the keyword(s) expressed using CTXATTRIBUTE node(s). | No | CONTEXT | NAME VALUE | -
CTXTKEYWORD | The search term/keyword assigned to the parent ELEMENT node. The CONTEXT , and the keyword is used when the parent ELEMENT is active in the Solution Explorer, for searching the help files for topics to display in the Dynamic Help window. This node is used in conjunction with the CTXTATTRIBUTE node. Only one keyword is allowed in each CTXTKEYWORD node, so declare as many CTXTKEYWORD nodes as you have keywords for the parent ELEMENT | Yes | CONTEXT | - | -
DEFAULT | Sets a default value for a property. When you use this node, the READONLY MINVALUE , and MAXVALUE nodes are ignored. | No | PROPERTYCONSTRAINT | - | 1
DEFAULTACTION | Specifies how unknown items are dealt with in an ELEMENT or ELEMENTSET node. It governs if unknown items are included orxcluded by default. This node interacts with the POLICYMODE node | Yes(in DEFAULTSETTINGS node), and No (in the ELEMENTSET node) | DEFAULTSETTINGS,ELEMENTSET | - | 1
DEFAULTSETTINGS | Specifies the default values and behaviors for each of the ELEMENT and ELEMENTSET nodes, as well as the default constraints for the policy file. | Yes | CONSTRAINTS ,DEFAULTACTION ORDER POLICYMODE | TDL | 1
DESCRIPTOR | Contains a unique value used for identifying a control that is displayed in the toolbox. You can find a list of valid DESCRIPTOR values in the VSIDE.tdl file (usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\ Policy folder). | Yes | TOOLBOXITEM | - | 1
ELEMENT | Represents an element in an enterprise template project; the fundamental building block of a policy file. | No | ELEMENTS | CONSTRAINTS CONTEXT , ELEMENTSET , FEATURELINKS ID , IDENTIFIERS , PROTOTYPES | -
ELEMENTS | Container for all of the ELEMENT nodes in a single policy file. | No | TDL | ELEMENT | 1
ELEMENTSET | Specifies a subset ELEMENT or CATEGORY node and/or constraints in the form of a CONSTRAINTS node and/or a MEMBERCONSTRAINTS node | No | ELEMENT | CONSTRAINTS DEFAULTACTION , EXCLUDE , INCLUDE , MEMBERCONSTRAINTS ,.ORDER | 1
ENABLED | Enables or disables a menu or toolbox item. You must specify a 0 (false) or 1 (true) as the value for this node. pression as the value for this node. | Yes | MENUCONSTRAINT , TOOLBOXCONSTRAINT | - | 1
EXCLUDE | Excludes CATEGORY and ELEMENT nodes from the parent node. You must use the ID of a CATEGORY or ELEMENT node, or an ELEMENT expression as the value for this node. | No | ELEMENTSET | - | -
FEATURELINKS | Associates the ID nodes of the child nodes with the parent ELEMENT. | No | ELEMENT | MENULINKS TOOLBOXLINKS | 1
FEATURES | Container for the menus and toolbox items that can be governed by the policy file in which the node resides. | No | TDL | MENUS , TOOLBOXITEMS | 1
GUID | GUID for a group of menu items. This node works in conjunction with the ID and CMDID nodes. | Yes | MENU | - | 1
ID | Holds a unique identifier that can be used to reference the parent node in which it resides. Although you can use your own names as the ID for a node, white space and parentheses aren't allowed. The IDs for standard items in the IDE can be found in the VSIDE.tdl file (in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\ Policy folder). | Yes | CATEGORY , ELEMENT ,MENU , MENUCONSTRAINT , MEMBERCONSTRAINT | - | 1
IDENTIFIER | Can be used to provide your own ID information about an ELEMENT node for a component. | No | IDENTIFIERS | IDENTIFIER ,TYPE | -
IDENTIFIERDATA | Specifies a name/value pair that VS .NET uses for processing of elements or a co mponent of an element. | No | IDENTIFIER | NAME , VALUE | -
IDENTIFIERS | Container node for the IDENTIFIER node(s) of an ELEMENT node. | No | ELEMENT | IDENTIFIERDATA | 1
INCLUDE | Explicitly includes CATEGORY and ELEMENT nodes in the parent node. You must use the ID of a CATEGORY or ELEMENT node, or an ELEMENT | No | ELEMENTSET | - | -
MAXVALUE | Specifies the maximum value for a property. If you have specified a value for the DEFAULT and/or READONLY node, this node is ignored. | No | PROPERTYCONSTRAINT | - | 1
MEMBERCONSTRAINT | Can be used to restrict VS .NET IDE features for specific members of an ELEMENTSET nodes. | No | MEMBERCONSTRAINTS | ID , MENUCONSTRAINTS , TOOLBOXCONSTRAINTS | -
MEMBERCONSTRAINTS | Container for MEMBERCONSTRAINT nodes. | No | ELEMENTSET | MEMBERCONSTRAINT | 1
MENU | Creates a reference to a menu item in the VS .NET IDE. | No | MENUS | ID , CMDID , GUID | -
MENUCONSTRAINT | Indicates if a specific menu item is enabled or disabled. | No | MENUCONSTRAINTS | ENABLED , ID | -
MENUCONSTRAINTS | Container for MENUCONSTRAINT nodes. | No | CONSTRAINTS , MEMBERCONSTRAINTS | MENUCONSTRAINT | 1
MENULINK | Contains the ID of a menu item that is to be disabled automatically when the parent MENULINKS node's parent, FEATURELINKS , is contained in an ELEMENT , which is excluded from an ELEMENTSET | No | MENULINKS | ID | -
MENULINKS | Container for MENULINK node. | No | FEATURELINKS | MENULINK | 1
MENUS | Container for MENU nodes. | No | FEATURES | MENU | 1
MINVALUE | Specifies the minimum value for a property. If you have specified a va lue for the DEFAULT and/or READONLY node, this node is ignored. | No | PROPERTYCONSTRAINT | - | 1
NAME | Unique identifier, used for referencing the node in which it is contained. | Yes | CTXTATTRIBUTE , IDENTIFIERDATA ,.PROPERTYCONSTRAINT | - | 1
ORDER | Specifies the order in which INCLUDE and EXCLUDE actions are evaluated. You can set this node only to INCLUDEEXCLUDE or EXCLUDEINCLUDE | Yes(DEFAULTSETTINGS), No (ELEMENTSET) | DEFAULTSETTINGS , ELEMENTSET | - | 1
POLICYMODE | Specifies how unidentified items are handled. You must specify either PERMISSIVE or RESTRICTIVE, POLICYMODE works in conjunction with the DEFAULTACTION node, and you use it to specify if all project items are displayed in the Add New Item dialog box by default (PERMISSIVE), or not shown by default (RESTRICTIVE). | Yes | DEFAULTSETTINGS , ELEMENTSET | - | 1
PROPERTYCONSTRAINT | Contains child nodes that deter mine the limits for a property, when displayed in the Properties window. | No | PROPERTYCONSTRAINTS | DEFAULT , MINVALUE , MAXVALUE , NAME , READONLY | -
PROPERTYCONSTRAINTS | Container for PROPERTYCONSTRAINT nodes | No | CONSTRAINTS , MEMBERCONSTRAINT | PROPERTYCONSTRAINT | 1
PROTOTYPE | Specifies the loca tion, including the file name, for a prototype or model. Depending on what type of prototype is referenced, you must prefix the location and file name with [ VB], [ VC#], [ VC], or [EF], for VB .NET, C#, C++, or Enterprise Frameworks. The path is relative to the VS .NET folder structure, which is typically \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks. | No | PROTOTYPES | - | -
PROTOTYPES | Container for PROTOTYPE nodes. | No | ELEMENT | PROTOTYPE | 1
READONLY | Specifies if the property can be edited. A value of 1 makes the property read-only; a value of 0 makes the property editable. 0 and 1 are the only allowed values for this node. If you have specified a value for the DEFAULT node, this node is ignored. | Yes | PROPERTYCONSTRAINT | - | 1
TDL | Root node of a policy file, which means that all other nodes must be contained within the start and end TDL tags. | Yes | - | CATEGORIES , DEFAULTSETTINGS , ELEMENTS , FEATURES | 1
TOOLBOXCONSTRAINT | Enables or disables a specified toolbox item when a specific selection is made in a designer, an editor, or in the Solution Explorer. | No | TOOLBOXCONSTRAINTS | ENABLED , ID | -
TOOLBOXCONSTRAINTS | Container for TOOLBOXCONSTRAINT nodes. | No | CONSTRAINTS , MEMBERCONSTRAINT | TOOLBOXCONSTRAINT | 1
TOOLBOXITEM | Creates a reference to an item displayed in the toolbox. | No | TOOLBOXITEMS | DESCRIPTOR ,.ID | -
TOOLBOXITEMS | Container for TOOLBOXITEM nodes. | No | FEATURES | TOOLBOXITEM | 1
TOOLBOXLINK | Contains the ID of a toolbox item that is to be disabled automatically when the parent TOOLOXLINKS node's parent, FEATURELINKS , is contained in an ELEMENT , which is excluded from an ELEMENTSET. | No | TOOLBOXLINKS | - | -
TOOLBOXLINKS | Container for TOOLBOXLINK nodes. | No | FEATURELINKS | TOOLBOXLINK | 1
TYPE | Specifies the type of the item allowed in the parent IDENTIFIER. The only valid values for this node are CODE , CODEVARIABLE , HTMLELEMENT , PROJECT , PROJECTITEM , and REFERENCE. | No | IDENTIFIER | - | 1
VALUE | Specifies the value for a name/value pair used in the parent node. | Yes | CTXTATTRIBUTE , IDENTIFIERDATA | - | 1


Summary

In this chapter, you were introduced to one of the enterprise features of VS .NET:policy files. You saw how you can create and edit these policy files and how they can be used with enterprise template project files.

Although the concept of policy files is easy to understand, they are not the easiest things to work with. However, once you become familiar with the way these policy files work, you have an incredibly powerful tool at your disposal that will save you many hours of manual work when it comes to setting up restrictions and guidelines for your developers and making sure they're followed. If you really want to get a deeper understanding of policy files than what you've gotten from this chapter, we suggest you examine the DAP.tdl and VSIDE.tdl files. They contain much valuable information that you can absorb, now that you have the basic understanding of policy files.

The next chapter shows you how you can create custom help topics, have them compiled, and make them part of the help for your enterprise template project files.


Exercise Answers

In this section, you'll find answers to the questions asked in some of the Exercises in this chapter.

Exercise 9-9 Answers
Start example

In the "Configuring the Add New Item and Add New Projects Dialog Boxes" section, Exercise 9-9 asked you to figure out the contents of the Add New Item dialog box. Here are the answers:

  • POLICYMODE is set to PERMISSIVE and the projBusinessFacade project is selected in the Solution Explorer. All valid project items are displayed (see Figure 9-16).

    Click To expand
    Figure 9-16: Add New Item dialog box with all valid project items for the projBusinessFacade project displayed

  • POLICYMODE is set to PERMISSIVE and the projWebService project is selected in the Solution Explorer. All valid project items are displayed (see Figure 9-17).

    Click To expand
    Figure 9-17: Add New Item dialog box with all valid project items for the projWebService project displayed

  • POLICYMODE is set to RESTRICTIVE and the projBusinessFacade project is selected in the Solution Explorer. All valid project items are displayed (see Figure 9-16).

  • POLICYMODE is set to RESTRICTIVE and the projWebService project is selected in the Solution Explorer. The XML File, XML Schema, and XSLT File items are displayed (see Figure 9-18).

    Click To expand
    Figure 9-18: Add New Item dialog box with INCLUDE project items only displayed

Did you get it right? If not, go back and review the Exercise, because the answer isin there, and the hint is the default settings.

End example
Exercise 9-10 Answers
Start example

In the "Configuring the Add New Item and Add New Project Dialog Boxes" section, Exercise 9-10 asked you to figure out the contents of the Add New Project dialog box. Here are the answers:

  • POLICYMODE is set to PERMISSIVE and the projEnterpriseTemplateProject1 enterprise template project is selected in the Solution Explorer. All valid projects are displayed (see Figure 9-19).

    Click To expand
    Figure 9-19: Add New Project dialog box with all valid projects displayed

  • POLICYMODE is set to PERMISSIVE and the projEnterpriseTemplateProject2 enterprise template project is selected in the Solution Explorer. All valid projects are displayed (same as Figure 9-19).

  • POLICYMODE is set to RESTRICTIVE and the projEnterpriseTemplateProject1 enterprise template project is selected in the Solution Explorer. The Visual Basic Projects - Windows Application project is displayed (see Figure 9-20).

    Click To expand
    Figure 9-20: Add New Project dialog box with VB .NET Windows Application displayed

  • POLICYMODE is set to RESTRICTIVE and the projEnterpriseTemplateProject2 enterprise template project is selected in Solution Explorer. No items are displayed.

End example

If you didn't get the correct answers, go back and review the Exercise, because the answer is in there, and the hint is the default settings.


Chapter 10: Using Custom Help Topics

Overview

In this chapter, you'll be introduced to custom help topics and how they're used in policy files associated with enterprise template projects. Policy files are covered in Chapter 9, and enterprise template projects are covered in Chapter 8.

Custom help topics are used to provide help to the developers working on a project based on an enterprise template project. This means that you can guide the developers by means of your own help topics associated with various solution, IDE, and toolbox elements.

As in the previous chapters, we'll cover the basics before moving on to the more interesting material. First, we'll take a look at the Dynamic Help window itself, and then we'll explore the makeup of help context files. Finally, we'll explain how to create custom help topics. The example here uses some simple HTML topics, but you'll know how to use custom help topics after reading this chapter.


The Dynamic Help Window

The help you can provide with custom help topics is context-specific and displayed in the Dynamic Help window in the VS .NET IDE. The fact that the custom help topics are context-specific, just like any other VS .NET help topic, means that the content in the Dynamic Help window changes according to your current selection in the VS .NET IDE. This selection might be in a code editor, an item in the Solution Explorer, a control on a Windows or Web form, or indeed the form itself.

Note

Although the content of the Dynamic Help window changes according to your current selection in the VS .NET IDE, custom help topics can be associated only with items in the Solution Explorer, and not, for example, with code variables in the Visio Code Editor. This is different from the help topic links provided by Microsoft.

The Dynamic Help window, which is shown in the lower-right corner of Figure 10-1, is HTML-based. It's very helpful, because you always have a list of help topics to choose from when you select something within the VS .NET IDE. (If the Dynamic Help window isn't displayed in your VS .NET IDE, you can open it by pressing Ctrl-F1 or by choosing Help ®Dynamic Help.)

Click To expand
Figure 10-1: Dynamic Help window

The Dynamic Help window is split into categories as shown in Figure 10-2, where you can see three of the five predefined VS .NET categories. The predefined categories are as follows:

Click To expand
Figure 10-2: Dynamic Help window categories

  • Help: This is most obvious category and the default one. It should contain links to topics in the MSDN help documentation.

  • Samples: This category should contain links to help topics that contain examples of how to use Microsoft .NET.

  • Getting Started: This category should contain links to help topics that help you get started with using VS .NET quickly.

  • Actions: This category should contain links to macros and wizards, and any other tool that is launched by clicking the link.

  • Miscellaneous: This category should contain links to any help topic that can't really be put into any of the other categories; in other words, it's a catchall category.

Selecting External or Internal Help

When you click any of the links displayed in the Dynamic Help window, the help topic is displayed externally in the Microsoft Document Explorer (the help text viewer that comes with VS .NET). In Figure 10-3, you can see the Solution Explorer help topic displayed in the Microsoft Document Explorer. This means the help topics are displayed externally, outside the VS .NET IDE in another application.

Click To expand
Figure 10-3: Help topics in the Microsoft Document Explorer
Note

When you make a selection within the VS .NET IDE, it's tracked by the IDE, and the information collected is then used to filter the help collection, so that only help topics relevant to the current selection are displayed in the Dynamic Help window. The filtering used in the Dynamic Help window is the same kind of filtering you can apply to the help collection displayed in the Microsoft Document Explorer when you open it manually. However, the two filters don't interfere with each other. This means that filtering applied in the Dynamic Help window doesn't filter the help collection in the Microsoft Document Explorer when opened manually and vice versa.

If you prefer, you can choose to view help topics internally instead. In Figure 10-4, you can see the same help topic shown in Figure 10-3 displayed internally in the VS .NET IDE as an HTML page. If you look closer, you'll see that a new toolbar is also being displayed as the bottommost toolbar. In fact, this is the same toolbar as the one from the Microsoft Document Explorer application, and it offers the same functionality.

Click To expand
Figure 10-4: Displaying Help topics internally

Whether you want to use internal or external help is a matter of preference.[1]You can choose one or the other in the Options dialog box, as shown in Figure 10-5. To get to these settings, select Tools ® Options, choose the Environment category in the list box on the right, and then choose the Help category. Simply select your preferred way of displaying the help topics (Internal help or External help), and then click OK to change to that method. You will need to close and reopen the VS .NET IDE for this change to take effect.

Click To expand
Figure 10-5: Help settings in the VS .NET IDE Options dialog box

Choosing a Help Collection

The content of the Dynamic Help window is usually based on the information in the MSDN Library installed on your machine.[2] It can also be based on the VS .NET Combined Collection, which includes the MSDN Library. In fact, you can base the content of the Dynamic Help window on any help collection you might happen to have installed on your system. For example, the Visual Studio Integration Partner (VSIP) Collection is installed when you install the VSIP developer edition (see http://www.vsipdev.com for more information about VSIP).

The help on which your Dynamic Help window is based is another choice in the Help category of the Options dialog box (Figure 10-5). Just choose a collection from the Preferred collection drop-down box.

[1]We prefer the external help, but you should really try out both options before committing yourself to either.

[2]The MSDN Library is automatically installed if you choose to install the help files when running the VS .NET Setup program.


Help Context File Format

Listing 10-1 shows a custom help context file, created as an XML file. This is the type of file you need to set up in order to create custom help topics. In fact, this is the file we'll create in the "Creating Custom Help Topics" section later in this chapter.

Listing 10-1. NewEnterpriseHelp.xml Context File
Start example
 1 <?xml version='1.0' encoding="utf-8" ?>
 2 <DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"
 3    xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
 4    xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd">
 5    <LinkGroup ID="NewEnterpriseHelp"
 6       Title="New Enterprise Custom Help Topics" Priority="1">
 7       <Glyph Expanded="3" Collapsed="4"/>
 8    </LinkGroup>
 9    <Context>
10       <Keywords>
11          <KItem Name="NewHelpTopicKeyword" />
12       </Keywords>
13       <Attributes>
14          <AItem Name="Product" Value="VB" />
15          <AItem Name="NewHelpTopicKeywordAttribute" Value="1" />
16       </Attributes>
17       <Links>
18          <LItem
19             URL="file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"
20             LinkGroup="NewEnterpriseHelp">
21                  New Enterprise Development Help
22          </LItem>
23       </Links>
24    </Context>
25 </DynamicHelp>
End example

In Listing 10-1, you can see the DynamicHelp root node and the first-level LinkGroup and Context child nodes. The DynamicHelp node is required in any help context file. The DynamicHelp root node has only the optional xmlns (XML namespace) attribute, and since it gives you IntelliSense in the VS .NET XML editor, there's really no point in changing it.[3] The optional, first-level LinkGroup and Contextnodes are described in the following sections.

LinkGroup Node

The LinkGroup node is required when you want to create your own custom help category. The following sections describe the attributes and the Glyph child node of the LinkGroup node.

<LinkGroup ID="NewEnterpriseHelp"
    Title="New Enterprise Custom Help Topics" Priority="1">
     <Glyph Expanded="3" Collapsed="4"/>
</LinkGroup>

LinkGroup Attributes

The LinkGroup node has the attributes ID, Priority, and Title. Only the ID attribute is required.

ID Attribute

ID is a required attribute that identifies the LinkGroup, and it's the value of this attribute that is used for specifying which group a link item should be listed under in the Dynamic Help window. The link item (LItem) node is described in the section about the Context node.

Priority Attribute

The Priority attribute of the LinkGroup node contains a value that defines the display priority of the group in the Dynamic Help window, such as Priority="1500". The value is relative to other groups, and the group with highest priority will be displayed at the top of the Dynamic Help window. Well, this is only partly true, because the predefined groups actually have a priority different from the one specified in the context.xml file.

If you want to place your link group at the very top of the Dynamic Help window, no matter which of the predefined groups are shown, you should specify

The predefined groups have the following internal priority values:

  • Actions = 2000

  • Help = 1800

  • Samples = 1700

  • Getting Started = 1600

  • Miscellaneous = 1500

    Note

    These internal priorities are defined in the Registry at this node: HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1\ Dynamic Help\LinkGroups. You can change these priorities through the Dynamic Help page of the Options dialog box, as explained in the "Setting Up the Dynamic Help Window" section later in this chapter.

If you specify the same priority as a predefined group, your new group loses—it's placed below the predefined group.

If you don't set the Priority attribute, it's automatically set to 1. The maximum value for the Priority attribute is 899795648511 (wherever this number comes from), and if you specify a higher value than this, it will automatically cause the value to be set to 1.

Title Attribute

The Title attribute of the LinkGroup node is used to specify the name or title that is displayed in the Dynamic Help window:

Title="New Enterprise Custom Help Topics"

If you set the value of this attribute to an empty string (" "), no group title is displayed, but the custom help topics belonging to this group will be displayed as a separate group. However, if you leave out the Title attribute entirely, the custom help topics belonging to this group will be displayed as part of the group with the next higher priority.

Glyph Node

The Glyph node is a child node of the LinkGroup node. This node is used for specifying an icon, which is displayed on the left side of the link group name (specified withthe Title attribute of the LinkGroup node). You can use animated icons, by specifying values for the Expanded and Collapsed attributes, or a static icon, by specifying a value for the Static attribute.

<Glyph Expanded="3" Collapsed="4"/>
<Glyph Static="1"/>

Animated icon doesn't mean that the icon displayed when the group is expanded or collapsed is animated; it means that you have two different icons—one for each state: expanded or collapsed.[4]

The attributes of the Glyph node specify the icon for the link group/category using a value set to an integer value in the range 1 through 14. This value refers to some predefined images that are stored in the library file vsbrowse.dll, which is located in the \Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE folder. Here's a list of integer values mapped to icons:

As you can see from the list, the icon for the value 13 is missing, and the icons certainly aren't placed as logically as they could have been. It would have made sense to place the pairs of icons adjacent to each other. This is also the way the MSDN Help documentation states it is, which leads us to believe that this is indeed a bug. For this reason, we include the "correct" list, just in case Microsoft's "intention" is fixed in a later release and/or hotfix.

The three attributes of the Glyph node work as follows:

  • The Static attribute specifies an icon for the link group/category. This attribute is overridden if you specify the Expanded and Collapsed attributes.

  • The Collapsed attribute specifies the icon for the link group/category when the links or help topics belonging to the category are collapsed.

  • The Expanded attribute specifies the icon for the link group/category when the links or help topics belonging to the category are expanded. If you leave out this attribute and specify the Collapsed attribute, the Title attribute of this LinkGroup node won't be shown in the Dynamic Help window, whether or not the Static attribute is specified.

Context Node

The Context node is where you set up keywords and links. It has the Keywords, Links, and Attribute child nodes.

<Context>
   <Keywords>
     <KItem Name="NewHelpTopicKeyword" />
  </Keywords>
  <Attributes>
    <AItem Name="Product" Value="VB" />
      <AItem Name="NewHelpTopicKeywordAttribute" Value="1" />
  </Attributes>
    <Links>
      <LItem
          URL="file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"
          LinkGroup="NewEnterpriseHelp">
               New Enterprise Development Help
      </LItem>
   </Links>
</Context>

Keywords and KItem Nodes

The Keywords child node of the Context node is a container for zero or more KItemnodes. Neither type of node is required.

The KItem child node and its Name attribute specify a link to one or more CTXTKEYWORD nodes in a policy file. You use the CTXTKEYWORD node for setting up a keyword for the context of the ELEMENT node in which it's contained. The keyword specified is used for searching for help topics to be displayed in the Dynamic Help window. You'll learn more about CTXKEYWORD and other policy file settings for dynamic help in the "Adding Help Topic References to the Policy File" section later in this chapter.

<KItem Name="NewHelpTopicKeyword" />

Even if the Name attribute is optional, you wouldn't want to leave it out. If you did, you wouldn't link to the policy file, and your custom help topic would not be displayed in the Dynamic Help window.

Links and LItem Nodes

  • The Links node of the Context node is a container for zero or more LItem nodes. These nodes are also optional.

  • The LItem node specifies a link to a custom help topic document:

    <LItem
   URL="file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"
   LinkGroup="NewEnterpriseHelp">
        New Enterprise Development Help
</LItem>

The URL attribute of the LItem node specifies the document that should be shown when the associated item is selected in the VS .NET IDE. Although the name of this attribute is URL, you can use a URL, a UNC, or a simple file name to specify the document. Make sure you prefix the attribute value with http:// for a URL, file:// for a file, and ftp:// to specify the FTP protocol, to avoid errors. Although a simple file name, such as C:\NewEnterpriseHelp.htm, will work, any other direct (without a prefix) name might not work.

If the value of the URL attribute is duplicated in another LItem node, whether or not it's in a different context file, only the first occurrence read by the VS .NET IDE will be shown in the Dynamic Help window. Because the browser component (Microsoft Internet Explorer) associated with the VS .NET IDE is used for opening the help file/document, you can use any document that the browser component recognizes. Therefore, which documents can be opened depends on your setup. If your developers all have the same setup on their machines, you can use any document type that is recognized. However, using HTML documents is a good choice, because they're human-readable and easy to author.

The LinkGroup attribute specifies under which group in the Dynamic Help window the custom help topic should be listed. If you don't specify this attribute, it will automatically be listed under the Miscellaneous group.

The value of the LItem node, New Enterprise Development Help in the example shown in this section, specifies the name of the custom help topic—the name displayed as a link to the custom help file in the Dynamic Help window. Although the URL attribute and this attribute are optional, you wouldn't want to leave them out, because the custom help topic won't be displayed in the Dynamic Help window if these attributes are missing.

Another attribute of the LItem node is Priority, which is used for ranking the custom help topic link within the group it's contained. If it's placed in a custom help topic group, setting the value of this attribute to a positive integer is all you need to do. However, if you want to place it in one of the predefined groups, you need to add the following AItem node to the Attributes node container (described next):

<AItem Name="locale" Value="kbEnglish"/>

You can also specify a ToolTip attribute of the LItem node, to specify a tool tip for when the mouse is placed over the custom help topic link in the Dynamic Help window.

ToolTip="This is my custom help topic…"

Attributes and AItem Nodes

The optional Attributes node of the Context node is a container for zero or more AItem nodes. The AItem node is used for specifying attributes for your help topics.

<Attributes>
   <AItem Name="Product" Value="VB" />
</Attributes>

When your help topic is displayed for a large number of UI items in the VS .NET IDE, it can often be a good idea to assign attributes to the help topics. This way, you can filter out help topics that, on the one hand, are relevant to the active context, but on the other hand, aren't as specific as you want them to be. For most smaller help systems, this is overkill, but it's a good tool when you don't want too many help topics displayed, because it allows you to show only the most relevant ones. This node can be used in conjunction with the CTXTATTRIBUTE node in a policy file, which is used to filter the help topics that have been returned by the CTXTKEYWORD node(s).

The AItem node has Name and Value attributes. The Name attribute specifies the name of an attribute that can be referenced in the policy file using the CTXTATTRIBUTEnode (Name="Product" in the example). This attribute is optional, but if you leave it out, you won't be able to filter your custom help topics displayed in Dynamic Help window. The Value attribute specifies a value for the AItem attribute node (Value="VB" in the example).

You'll learn more about how the AItem node works with the CTXTATTRIBUTE and CTXTKEYWORD nodes in a policy file in the next section, which describes how to create custom help topics.

[3]Having said that it provides you with IntelliSense, which is what it should do, we also have to say that it currently doesn't work on our setup, but perhaps you have a different experience.a priority higher than 2000, which is the internal priority of the Actions group.

[4]For this release of VS .NET, Microsoft seems to have taken out functionality. You were able to create your own icons in VS .NET 2002, but this is no longer possible.


Creating Custom Help Topics

You can create the help topics you want to associate with elements defined in your policy file in a number of ways. In fact, you can use any kind of document or link for this purpose. One implication of this is that you don't need to compile your help topics before you can use them in the Dynamic Help window.

Tip

Although you don't have to compile your help topics for them to show up in the Dynamic Help window, you still might want to do so. By compiling, say, HTML files to .chm files, you can add indexing and search functionality to your help topics. You can find more information about using the Microsoft HTML Help 1.4 SDK at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp.asp

For demonstrating how to associate custom help topics with your policy file, we've created a simple HTML file, NewEnterpriseHelp.htm, as shown in Listing 10-2. You can find this file in the Chapter 10 folder of the sample code (available from the Downloads section of the Apress Web site, www.apress.com).

Listing 10-2. NewEnterpriseHelp.htm Custom Help File
Start example
 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 2 <html>
 3    <head>
 4       <title>New Enterprise Help Topics</title>
 5       <meta name="GENERATOR" content="Microsoft Visual Studio.NET 7.1">
 6       <meta name="vs_targetSchema"
 7          content="http://schemas.microsoft.com/intellisense/ie5">
 8    </head>
 9    <body>
10       <table id="MainTable" width="100%" border="0">
11          <tr align="center" height="40px" valign="top">
12             <td>
13                <font face="Verdana" size="3" color="#0000ff">
14                   Custom Help Topic 1</font>
15             </td>
16          </tr>
17          <tr align="center" height="40px" valign="middle">
18             <td>This is custom help topic 1, which is associated
19                with...</td>
20          </tr>
21          <tr align="center">
22             <td>
23                <a href="mailto:carstent@dotnetservices.biz">
24                   Send message to help author</a>
25             </td>
26          </tr>
27       </table>
28    </body>
29 </html>
End example
Note

In the accompanying source code, you can find a copy of the HTML in Listing 10-2 as a Microsoft Word document, NewEnterpriseHelp.doc, which can be used as a help document. The "Setting Up Help Context Links" section later in this chapter explains where you need to specify which help document to show.

In Listing 10-2, you can see a very simple HTML page, which has been formatted for display purposes. It's not exactly a great-looking page, and certainly not a very helpful one, but it does show you how easy it can be to create your custom help topics. We'll use this HTML file in the Exercises in this chapter. Figure 10-6 shows how the HTML page looks when displayed in Internet Explorer.

Click To expand
Figure 10-6: NewEnterpriseHelp.htm custom help file displayed in Internet Explorer

Once you have created your help topics, you need to create a link to the policy file; or rather, you need to set up an XML file, also known as the context file, which takes care of the linking between the policy file and the help file. You do this by specifying an existing VS .NET category or by defining a new category andby setting up help context keywords.

Tip

You can edit the context file and the help document after you've created an enterprise solution and have the changes reflected in the solution. You just need to close and reopen the solution, if it's open in the VS .NET IDE when you edit the files. Actually, this is also true for policy files, which are discussed in Chapter 9.

Defining Custom Help Topic Categories

In general, it's easier for the developers to find the custom help topics when they're placed in a category of their own, rather than in one of the Dynamic Helpwindow's predefined categories. To create your own custom help category, you use the LinkGroup node in your custom help context file.

As you can see from the three categories in the Dynamic Help window shown earlier in Figure 10-2, the categories aren't sorted alphabetically. So what determines how they're sorted? You can prioritize the various categories (including the predefined categories), by using the Priority attribute of the LinkGroup node, as shown in Listing 10-3.

Listing 10-3. Basic Custom Help Context File
Start example
 1 <DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"
 2    xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
 3    xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd">
 4    <LinkGroup ID="NewEnterpriseHelp"
 5       Title="New Enterprise Custom Help Topics" Priority="1">
 6       <Glyph Expanded="3" Collapsed="4"/>
 7    </LinkGroup>
 8 </DynamicHelp>
End example

On line 5 of Listing 10-3, the priority is set with an integer value. As explained in the "Priority Attribute" section earlier in the chapter, the category with the highest value will be shown at the top of the Dynamic Help window. If you want to use one of the predefined categories instead of a custom category, you just need to set the value of the LinkGroup attribute of an LItem node to the name of a predefined category.

Start Sidebar
About the Predefined Help Categories

You can see the predefined help categories and their priorities in the context.xml file located in the \Program Files\Microsoft Visual Studio .NET\Common7\IDE\ HTML\XMLLinks\1033 folder.[5] Please note that it seems as if this file wasn't edited before shipping, as the xmlns attribute refers to http://microsoft.com/vstudio/tbd/vsdh.xsd. We assume that tbd means "to be decided," and that this is an oversight from the VS .NET development team. Go ahead and fix this is if you like, so it looks like Listing 10-3 (replace /vstudio/tbd with /vsdata/vsdh.xsd).

Although you can edit the priority of the predefined categories in the context.xml file, this will have no effect on how the predefined categories are sorted. The only things we've found you can actually change in this file are the Title, Expanded, Collapsed, and Static attributes of the Glyph node. It doesn't help commenting out one or more of the LinkGroup nodes either, because they're still shown.

If you want to change the way the predefined categories are sorted and pick which ones are displayed, you can do this through the Dynamic Help page of the Options dialog box, as explained in the "Setting Up the Dynamic Help Window" section later in this chapter.

End Sidebar

In Exercise 10-1, you'll begin creating a custom context file, with a custom help topic category.

Note

Custom help topics are referenced from individual ELEMENT nodes in policy files, so we've decided to build on the NewEnterprisePolicy.tdl policy file introduced in Chapter 9. You can copy it across from the Chapter 09\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder to the corresponding folder on your system. Make sure you copy the version of the NewEnterprisePolicy.tdl file created in Exercise 9-14, and rename it to NewEnterprisePolicy.tdl in the mentioned folder.
Exercise 10-1
Start example

  1. Open the VS .NET IDE. You don't need a solution open, and it's probably easier to close any open solution, before continuing.

  2. Select File ® New® File, or press Ctrl-N.

  3. In the New File dialog box, select the XML File template in the General category.

  4. Click the Open button. This creates a new XML file with the name XMLFile1, and with no content but the XML header.

  5. To the default XML declaration in the XML file,[6] you need to add the text shown in Listing 10-3. Feel free to remove the carriage return characters inserted on Lines 1 and 2 to make the text easier to read.

  6. Save the XML file as NewEnterpriseHelp.xml in the \Program Files\ Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\ 1033 folder.

End example

Setting Up Help Context Links

Now that you've set up your custom help categories (or perhaps you've decided to use one of the predefined ones), you need to add one or more keywords that will correspond to the ones we'll define later in the policy file. Therefore, the keywords link the policy file to the context file.

Context file keywords are defined as KItem (keyword item) nodes within the Keywords node of the first-level Context node, like this:

<Context>
   <Keywords>
   </Keywords>
</Context>

Basically, the Context node is a child node of the DynamicHelp root node. Both the Context and Keywords nodes are optional, but your context file is of little value to you if you decide not to include these nodes.

The Keywords node is a container for zero or more KItem nodes, which look like this:

<KItem Name="" ID="" />

The ID attribute is a unique identifier, but it's rarely used, and we won't be using itin this chapter. The Name attribute is used for linking to one or more CTXTKEYWORDnodes in the policy file. This means that you must spell the value of the Nameattribute of the KItem node and the value of the CTXTKEYWORD node exactly the same. These values are not case-sensitive, and you can use two or more words to makeup a keyword, but we've chosen to follow general code variable naming conventions.

After you have the keywords defined, which helps you link to the policy file, you still need to link to the help file you created earlier. For this, you use context links, which are created using the LItem (link item) child nodes of the Links node. The Links node is created within the first-level Context node.

In Exercise 10-2, you'll add the Keywords and Links nodes to your help contextfile. Note that although we've chosen to use an HTML file for our custom help topic, you can use any other document type that can be read on the target system. The help document is always loaded in the Microsoft Document Explorer, which uses OLE to load the document. This also means that an OLE object that can read your help document must be installed on your target system. For this reason alone, we strongly suggest that you use HTML help files. However, if you have Microsoft Word installed on your system, feel free to replace the NewEnterpriseHelp.htm part of the URL attribute of the LItem node (in step 3 of the Exercise and as shown in Listing 10-4) with NewEnterpriseHelp.doc. We have already created this Microsoft Word document for you, and it is located in the Chapter 10 folder with the accompanying source code (available from the Downloads section of the Apress Web site, at www.apress.com).

Exercise 10-2
Start example

  1. Add the following <Context> element to Listing 10-3, just before the final <DynamicHelp> end tag.

    <Context>
     <Keywords>
        <KItem Name="NewHelpTopicKeyword" />
     </Keywords>
<Context>

  2. Create a Links section without any defined links, following the Keywords section:

    <Links>
</Links>

  3. Add the following LItem element to the Links element:

    <LItem
   URL="file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"
   LinkGroup="NewEnterpriseHelp">
      New Enterprise Development Help
</LItem>

The entire context file should now look like Listing 10-4.

End example
Listing 10-4. NewEnterpriseHelp.xml Context File with a Context Node
Start example
 1 <?xml version='1.0' encoding="utf-8" ?>
 2 <DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"
 3    xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
 4    xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd">
 5    <LinkGroup ID="NewEnterpriseHelp"
 6       Title="New Enterprise Custom Help Topics" Priority="1">
 7        <Glyph Expanded="3" Collapsed="4"/>
 8    </LinkGroup>
 9    <Context>
10       <Keywords>
11          <KItem Name="NewHelpTopicKeyword" />
12       </Keywords>
13       <Links>
14          <LItem
15             URL=
16             "file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"[7]
17             LinkGroup="NewEnterpriseHelp" >
18                  New Enterprise Development Help
19          </LItem>
20       </Links>
21    </Context>
22 </DynamicHelp>
End example

In Listing 10-4, you can see a single LItem node, with the URL and LinkGroupattributes and a node value defined.It would be nice to see an example of what we've been doing so far, but we haven't linked our context file with a policy file yet. We'll do that right after the following discussion of help topic filtering.

Setting Up for Filtering Help Topics

You may want to be able to filter help topics, so that certain ones appear and certain ones do not appear in different situations. For example, you might have a custom help topic for a project item that is written specifically for VB .NET developers, so it would not be relevant for C# developers. Using the AItem child nodes of the Attributes node in the help context file, in conjunction with the CTXTATTRIBUTEchild node of the CONTEXT node in a policy file, you can filter out help topics.

In Exercise 10-3, you'll add an Attributes node with AItem child nodes to your help context file. The AItem nodes are also a valuable tool for filtering out topics that might be relevant, but for this example, you will filter out the least relevant help topics. Using the Value attribute of the AItem node, you can choose to exclude all items with any other value than, say 1, or you can choose to include all items with a value of 1. This will be clearer when you see the associated settings in the policy file, in the "Filtering the Custom Help Topic Links" section later in this chapter.

Exercise 10-3
Start example

  1. Add an Attributes node and two AItem child nodes to Listing 10-4:

    <Attributes>
   <AItem Name="Product" Value="VB" />
   <AItem Name="NewHelpTopicKeywordAttribute" Value="1" />
</Attributes>

  2. The entire context file should now look like Listing 10-5. Save your context file to the \Program Files\Microsoft Visual Studio .NET\Common7\ IDE\HTML\XMLLinks\1033 folder.

    Caution

    If you don't save your context file to \Program Files\ Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\ 1033, or at least copy it there after you have saved it to a different location, you will not be able to link it with your policy file. Note that the 1033 is the language and code page code ID (LCID) for the English language, but you might have a different ID on your system, depending on the language you use with VS .NET.
End example
Listing 10-5. NewEnterpriseHelp.xml Context File with an AItem Attribute Node
Start example
 1 <?xml version='1.0' encoding="utf-8" ?>
 2 <DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"
 3    xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
 4    xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd">
 5    <LinkGroup ID="NewEnterpriseHelp"
 6       Title="New Enterprise Custom Help Topics" Priority="1">
 7       <Glyph Expanded="3" Collapsed="4"/>
 8    </LinkGroup>
 9    <Context>
10       <Keywords>
11          <KItem Name="NewHelpTopicKeyword" />
12       </Keywords>
13       <Attributes>
14          <AItem Name="Product" Value="VB" />
15          <AItem Name="NewHelpTopicKeywordAttribute" Value="1" />
16       </Attributes>
17       <Links>
18          <LItem
19             URL="file://C:/EDWVSNETUMLMSF/Chapter 10/NewEnterpriseHelp.htm"
20             LinkGroup="NewEnterpriseHelp">
21                  New Enterprise Development Help
22          </LItem>
23       </Links>
24    </Context>
25 </DynamicHelp>
End example

In Listing 10-5, you can see two AItem nodes with the Name and Value attributes defined. The AItem nodes are valuable, because the author of the policy file that uses the context file containing Listing 10-5 can choose to reference the AItemnodes or leave out the reference. So, if you, as an author of the context file, want to give the author of the policy file the possibility of filtering a specific help topic, you add an AItem node to the Context node. It's entirely up to the policy file author whether he or she wants to use it. See the "Filtering the Custom Help Topic Links" section later in this chapter for information about how a policy file author can filter which custom help topics are displayed.

Note

Even if there are no NAME and VALUE child nodes in the CONTEXT node in your policy file that match the Name and Value attributes of the AItem node in the context file, the custom help topic link is still displayed in the Dynamic Help window.

Adding Help Topic References to the Policy File

If you got this far, you're nearly there, meaning what's left is a piece of cake. All you need to do now is to edit your policy file to specify a CONTEXT node that links to one or more Context nodes in your context file. You must add the CONTEXT node to your policy file for all the ELEMENT nodes for which you want your help topic links displayed. It should be added after the ID node. Here is a basic CONTEXT node in a policy file:

<CONTEXT>
   <CTXTKEYWORD>NewHelpTopicKeyword</CTXTKEYWORD>
</CONTEXT>

In Exercise 10-4, you'll edit the policy file you created in Chapter 9, adding the CONTEXT node. Make sure you edit the policy file located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. If you didn't follow the instructions in Chapters 8 and 9, you can copy the files from the source code folders of these chapters across to the corresponding folders.

Exercise 10-4
Start example

  1. Add the CONTEXT node to the NewEnterprisePolicy.tdl file created in Chapter 9, in the ELEMENTS node. Your ELEMENT node should look like Listing 10-6.

    Listing 10-6. projItemVBCodeFile ELEMENT Node for Policy File

    Start example

    <ELEMENT>
   <ID>projItemVBCodeFile</ID>
   <CONTEXT>
      <CTXTKEYWORD>NewHelpTopicKeyword</CTXTKEYWORD>
   </CONTEXT>
         <IDENTIFIERS>
      <IDENTIFIER>
         <TYPE>PROJECTITEM</TYPE>
         <IDENTIFIERDATA>
            <NAME>FileExtension</NAME>
            <VALUE>.vb</VALUE>
         </IDENTIFIERDATA>
      </IDENTIFIER>
   </IDENTIFIERS>
</ELEMENT>
    End example

  2. Save and close the policy file.

End example

If you create a new project based on the NewTemplateProject enterprise template project created in Chapter 8, which is associated with the NewEnterprisePolicy.tdl policy file created in Chapter 9, and you have followed the Exercises in this chapter, the Dynamic Help window will look like Figure 10-7 when you select a VB .NET code-behind file.

Click To expand
Figure 10-7: Custom help topic shown in the Dynamic Help window
Note

Make sure you associate the NewEnterprisePolicy.tdl policy file with the NewTemplateProject enterprise template project before you create a new solution based on it. Otherwise, you won't see the custom help topic in the Dynamic Help window as it is shown in Figure 10-7.

As you can see in Figure 10-7, the New Enterprise Custom Help Topics group is listed at the bottom of the Dynamic Help window when a VB .NET code-behind file is selected in the Solution Explorer. The link for the New Enterprise Development Help topic is displayed in the New Enterprise Custom Help Topics group.

When you click the New Enterprise Development Help topic link in the Dynamic Help window, the custom help topic you created in the Exercises in this chapter is displayed, as shown in Figure 10-8.

Click To expand
Figure 10-8: Custom help topic shown in the Microsoft Document Explorer

If you select any other type of file in the Solution Explorer, such as the Global.asax file, the link for the New Enterprise Development Help topic is no longer displayed in the Dynamic Help window. The custom New Enterprise Custom Help Topics group is also no longer displayed in the Dynamic Help window. This is because the only help topic associated with the custom group isn't displayed.

So far, you've seen the very basic CONTEXT node, which is used for linking ELEMENT nodes of your policy file with your custom help topics, but there's more to it than that. Table 10-1 shows the various child nodes and possible values for the CONTEXT node in a policy file. The Max. Occurrences column refers to the maximum number of nodes within the parent node, not the entire policy file. A hyphen (-) means there are no restrictions on the number of nodes.

Table 10-1: CONTEXT Child Node Settingx in a Policy File
Name | Description | Required | Occurrences | Example
CTXTKEYWORD | Used to set up a keyword for the context of the ELEMENT node in which it's contained. The keyword is used for searching for help topics to be displayed in the Dynamic Help window. The search is for help topics related to the ELEMENT when it's in the active context (currently selected) in the VS .NET IDE. The value must be unique within the CONTEXT node for an ELEMENT node, but not for the entire policy file. | Yes | - | <CTXTKEYWORD> NewHelpTopicKeyword </CTXTKEYWORD>
CTXTATTRIBUTE | Used to filter the help topics returned by the CTXTKEYWORD node(s), allowing you to constrain the help topics displayed in the Dynamic Help window. This node is used in combination with the AItem node in the context file, and it's particularly helpful when you want to differentiate between two ELEMENT nodes that have the same value for a CTXTKEYWORD node. |  | No | -
NAME | The name of the context attribute. It should match the name of the Name attribute of the AItem node in the context file. | Yes | 1 | <NAME> NewHelpTopicKeywordAttribute </NAME>
VALUE | The value of the context at tribute. You can use this node to exclude all items with any other value than say 1, or you can choose to include all items with a value of 1. It's obviously a matter of how you phrase it and how the author of the context file has set up the AItem nodes, but you do have two ways of looking at it. | Yes | 1 | <VALUE>1</VALUE>

Filtering the Custom Help Topic Links

The optional CTXTATTRIBUTE node, which is a child node of the CONTEXT node, is used to set up a filter that is used for filtering the custom help topics returned by the CTXTKEYWORD node(s). The following is the optional CTXTATTRIBUTE node with its required child nodes:

<CTXTATTRIBUTE>
   <NAME>...</NAME>
   <VALUE>...</VALUE>
</CTXTATTRIBUTE>

The NAME and VALUE child nodes, which are required, are used to specify what to filter and on what basis. Listing 10-7 shows an example of a CONTEXT node.

Listing 10-7. CONTEXT Node in a Policy File
Start example
 1 <CONTEXT>
 2    <CTXTKEYWORD>NewHelpTopicKeyword</CTXTKEYWORD>
 3    <CTXTATTRIBUTE>
 4       <NAME>NewHelpTopicKeywordAttribute</NAME>
 5       <VALUE>1</VALUE>
 6    </CTXTATTRIBUTE>
 7 </CONTEXT>
End example

Recall that the CTXTATTRIBUTE node is used to in combination with the AItemnode of the associated content file, as described earlier in the chapter.

In Exercise 10-5, you'll build on the example from the previous Exercises by adding policy file content that corresponds to one of the AItem nodes in Listing 10-5. Note that you could add the code in Listing 10-7 to just about any ELEMENTnode in your policy file, but for demonstration purposes, you'll create a new ELEMENT node for the projItemWebForm. After you've set up a link between the context file and that ELEMENT of your policy file, you will check that it actually works.

Exercise 10-5
Start example

  1. Add Listing 10-8 to your NewEnterprisePolicy.tdl policy file, directly after the ELEMENTS container node, making it the first ELEMENT node in the policy file.

    Listing 10-8. projItemWebForm ELEMENT Node with a CONTEXT Child Node

    Start example

     1 <ELEMENT>
 2   <ID>projItemWebForm</ID>
 3   <CONTEXT>
 4      <CTXTKEYWORD>NewHelpTopicKeyword</CTXTKEYWORD>
 5       <CTXTATTRIBUTE>
 6          <NAME>NewHelpTopicKeywordAttribute</NAME>
 7          <VALUE>1</VALUE>
 8       </CTXTATTRIBUTE>
 9    </CONTEXT>
10    <IDENTIFIERS>
11       <IDENTIFIER>
12          <TYPE>PROJECTITEM</TYPE>
13          <IDENTIFIERDATA>
14          <NAME>FileExtension</NAME>
15          <VALUE>.aspx</VALUE>
16          </IDENTIFIERDATA>
17       </IDENTIFIER>
18    </IDENTIFIERS>
19 </ELEMENT>
    End example

  2. Change the value of the POLICYMODE element of the DEFAULTSETTINGS element from RESTRICTIVE to PERMISSIVE¸ and the value of the DEFAULTACTION element from EXCLUDE to INCLUDE. (You need to do this in order to allow the action in step 4; see Chapter 9 for more information about the POLICYMODE element.)

  3. Save and close the policy file.

  4. Add a VB .NET ASP.NET Web Application project to the NewTemplateProject1 that we're using for our Exercises in this chapter.

  5. Select the default WebForm1 Web form in the Solution Explorer. The Dynamic Help window will now display the custom help topic link, as shown in Figure 10-9.

    Click To expand
    Figure 10-9: Custom help topic link shown in the Dynamic Help window

End example

In Figure 10-9, you can see the custom help topic link displayed in the Dynamic Help window when the WebForm1 Web form is selected in the Solution Explorer. This works because the value of the CTXTKEYWORD node in an ELEMENT node in the policy file matches the value of the KItem node in the context file. Also, because the values of the NAME and VALUE child nodes in the policy file match the Name and Value attributes of an AItem node in the context file, the custom help topic link is displayed in the Dynamic Help window. Okay, but what does it really tell you?

If you look back at your context file, the Name and Value attributes of the AItem node in the context file were already in there, because you added them in Exercise 10-4. Nevertheless, even if you did not add corresponding NAME and VALUEchild nodes in the CONTEXT node in your policy file, the custom help topic link would still be displayed in the Dynamic Help window. This means that when you set up attributes in the context file, you don't need to use them in your policy file, and if you don't, only the value of CTXTKEYWORD node in the policy file needs to match the value of the KItem node in the context file for the custom help topic link to be displayed.

In Exercise 10-6, you'll see what happens when you change the setting for the VALUE node in your policy file.

Exercise 10-6
Start example

  1. Edit your policy file to change the value of the VALUE node in Line 7 of Listing 10-8 to 0, as shown here:

    <VALUE>0</VALUE>

  2. Save the policy file and open the NewEnterpriseProject1 solution in VS .NET (close and reopen it, if it's already open).

  3. Select the WebForm1 Web form in the Solution Explorer. Notice that the Dynamic Help window doesn't display the custom help topic link.

End example

Table 10-2 shows the connection between the Name and Value attributes of the AItem node in a context file and the NAME and VALUE child nodes of the CTXTATTRIBUTEnode. The behaviors listed in the table assume that an ELEMENT node in the policy file is already linked using the CTXTKEYWORD node to the context file through the KItem node, and the item associated with the ELEMENT node is selected in the Solution Explorer.

Table 10-2: CTXTATTRIBUTE Node and AItem Node Combinations
CTXATTRIBUTE Node Defined? | NAME Node Value | VALUE Node Value | AItem Node Defined? | Name Attribute Value | Value Attribute Value | Custom Help Topic Link Displayed?
No | N/A | N/A | No | N/A | N/A | Yes
No | N/A | N/A | Yes | Any value | Any value | Yes
Yes | Any value | Any value | No | N/A | N/A | No
Yes | Name1 | Any value | Yes | Name2 | Any value | No
Yes | Name1 | Value1 | Yes | Name1 | Value2 | No
Yes | Name1 | Value1 | Yes | Name1 | Value1 | Yes

The various combinations in Table 10-2 are fairly obvious, but what isn't so obvious is why you would want to use attributes in combination with the keywords. If the keywords are what effectively link the various Solution Explorer elements with custom help topics, then why do you need attributes? There are a number of cases where attributes are appropriate.

One example is when you have development language-specific custom help topics that are linked to development language-agnostic ELEMENT nodes, such as the projItemWebForm in Listing 10-8. Let's assume that your custom help topic is only relevant in connection with the projItemWebForm ELEMENT node when the project in which it's contained is VB .NET-specific. In Exercise 10-3 and Listing 10-5, an AItem node was added to the context file with the Name and Value attributes of "Product" and "VB", respectively. We added these attributes to make sure that the custom help topic link is displayed only when the linked ELEMENT node is itself a VB .NET project or project item, or is part of a VB .NET project.

So, if you add an AItem node with Name and Value attributes to your context file, does that mean that you need to add the corresponding CTXTATTRIBUTE node and child nodes to your policy file? No, because this attribute is actually automatically added by VS .NET. But how do you know which attributes are added automatically? There is no list for you to refer to, but there is something much more unique, which you can use to test your own policy file custom attributes as well: Dynamic Help window Debug mode. When you set the Dynamic Help window in debug mode, you can see the keywords and attributes emitted by the currently selected items in the VS .NET, including the projects and project items in the Solution Explorer. You'll learn more about debug mode in the next section.

Now, let's use the information about the automatically supplied attributes and see if it actually works. Exercise 10-7 demonstrates one way of using attributes with custom help topics.

Exercise 10-7
Start example

  1. Change the projItemWebForm ELEMENT node in your NewEnterprisePolicy.tdl policy file so that it looks like Listing 10-9. Basically, what you need to do is to remove the CTXTATTRIBUTE node, including the child nodes.

    Listing 10-9. projItemWebForm ELEMENT Node Without a CTXTATTRIBUTE Node

    Start example

     1 <ELEMENT>
 2    <ID>projItemWebForm</ID>
 3    <CONTEXT>
 4       <CTXTKEYWORD>NewHelpTopicKeyword</CTXTKEYWORD>
 5    </CONTEXT>
 6    <IDENTIFIERS>
 7       <IDENTIFIER>
 8          <TYPE>PROJECTITEM</TYPE>
 9          <IDENTIFIERDATA>
10            <NAME>FileExtension</NAME>
11            <VALUE>.aspx</VALUE>
12          </IDENTIFIERDATA>
13       </IDENTIFIER>
14    </IDENTIFIERS>
15 </ELEMENT>
    End example

  2. Open the NewTemplateProject1 (close and reopen it, if it's already open), and select the default WebForm1 web form in the Solution Explorer. The Dynamic Help window will then display the custom help topic link. Now, the observant reader will point out that the NewHelpTopicKeyword keyword is responsible for the custom help topic being displayed. This is true, but the Product attribute still has a role to play, as demonstrated in the next steps.

  3. Add a C# ASP.NET Web Application project to the NewTemplateProject1.

  4. Select the default WebForm1 web form in the Solution Explorer. The Dynamic Help window will not display the custom help topic link, because of the Product attribute with a value of VB. To display the custom help topic link for the C# Web application, you can change the value of the Product attribute to C#.

End example

Another reason for using attributes is if the CONTEXT node in the policy file has more than one CTXTKEYWORD node, linking it to more than one KItem node.

[5]This is the language and code page code ID (LCID) for the English language, but you might have a different ID on your system, depending on the language you use with VS .NET.

[6]Actually, you can leave out the XML header; it seems the VS .NET IDE can interpret the file without it.

[7]Don't forget to edit this to be the path where you have installed the file on your machine.


Displaying Dynamic Help Window Debugging Information

In order to see the keywords and attributes emitted by VS .NET, as well as the custom ones you supply in connection with your own custom help topics, you can enable the display of debugging information in the Dynamic Help window. To do this, you need to change a setting in the Registry.

Caution

It can be dangerous to change settings in the Registry, because you can leave your system in an unusable state, if you perform the wrong action(s). If you're unsure of how to work with the Registry Editor, we suggest that you don't make any changes to the Registry. However, that means you won't be able to display debugging information.

To enable the debugging display, open the Registry Editor (from the Command Prompt window, or by choosing Start ® Run from the desktop and executing the regedit command). In the Registry Editor, locate the following node:

HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1\Dynamic Help

Now, you need to add a new value to this node. It must be a string value with the name Display Debug Output in Retail and a value of YES. This Registry Editor node should look like the one shown in Figure 10-10.

Click To expand
Figure 10-10: Registry Editor with the Dynamic Help window debugging information set

Next, open VS .NET (close and reopen it, if it's already open) and check out the Dynamic Help window, which should look like the one in Figure 10-11.

Click To expand
Figure 10-11: Dynamic Help window displaying debugging information

In Figure 10-11, you can see various keywords and attributes emitted by the active VS .NET context. The debugging information is shown in two sections:

Keywords: Actually, the Keywords section consists of many Keywords sections, each with a priority ranking. The individual Keywords sections are ranked according to the priority in descending order, meaning the Keyword section with the highest rank is placed at the top of the keywords list.

Attributes: The Attributes section holds all the attributes emitted for the current context. As you can see in Figure 10-11, they're in alphabetical order, and any attribute might appear more than once, depending on the number of elements in the current context for which it has been registered. Many, if not most, of the attributes you see here are emitted by VS .NET, but you can also see the ones you "register" yourself when setting up your custom help topics. The values of the VALUE and NAME child nodes of the CTXTATTRIBUTE node are the values you'll find here—for example Product and VB, respectively.

To remove the debugging information from the Dynamic Help window, delete the HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\7.1\Dynamic Help\Display Debug Output in Retail value in the Registry, orchange its value from YESto NO. You need to close and reopen the VS .NET IDE before the change takes effect, if it's open when you edit the Registry.


Setting Up the Dynamic Help Window

You can arrange and sort the contents of the Dynamic Help window in different ways, and you can change the scope of the content, as described in this section. In most cases, you'll probably want to leave the default settings, with all the default categories shown and in the default order, and all of the help topic types displayed under each category.

You can make changes to the default appearance of the content of the Dynamic Help window by using the Options dialog box, as shown in Figure 10-12. To get to this page of the Options dialog box, choose Tools ® Options, choose the Environment category, and then choose the Dynamic Help category.

Click To expand
Figure 10-12: Setting Dynamic Help display options

As you learned earlier in this chapter, and as you can see listed in Figure 10-12, there are five predefined categories for the Dynamic Help window. The predefined help topic links are not only categorized this way, but they're also grouped in various topic types: Article, Procedure, Orientation, Reference, Sample, and Syntax.

Figure 10-13 shows an example with two custom categories—Training and New Enterprise Custom Help Topics—added to the predefined ones. The latter is obvious, because you added it yourself, by creating the NewEnterpriseHelp.xml file in the \Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\1033 folder. So, what about the Training category? If you installed the MSDN Help files on your system, you'll also have this category on your setup, because installing those Help files adds the msdntrn.xml file to the mentioned folder.

Click To expand
Figure 10-13: Custom categories in the Dynamic Help page of the Options dialog box

All categories shown in the Dynamic Help page of the Options dialog box can be found in the files in \Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE\HTML\XMLLinks\1033 folder. If a category is listed in a file in this folder, it will always be shown in the Options dialog box, even if the enterprise template, policy file, and context file aren't loaded. This is different from the Dynamic Help window, where a category is shown only if it contains help topic links for the current context.

You can use the settings in the Help Context page of the Options dialog box to control the Dynamic Help window display as follows:

  • To turn off the display of categories or topic types, deselect the category or type in the Categories or Topic types list.

  • To change the order in which the categories are listed, select a category and click either the Move Up or Move Down button to move the category in the desired direction.

  • To choose which links to show in the window, select one of the Show links for radio buttons: Selection only, to show only the help topics relevant to the currently selected UI element (such as a Web form); Active UI elements, which is the default setting, to display help topics relevant to all open UI elements; or Show all links, to display all links relevant to the current state of the VS .NET IDE.

    Note

    In most cases, you should keep the Show links for default setting, Active UI elements, because it will generally make sure that all of the relevant help topics are displayed.

  • To specify the maximum number of help topic links to display, select the Limit number of links per category check box and type in the desired maximum number. You can enter only integer values, and the maximum number of help topic links per category allowed is 1000. A value of 0 here will disable link categories in the Dynamic Help window.


Summary

This chapter introduced you to custom help topics, which are used in conjunction with enterprise template projects and policy files to create custom help text that is automatically displayed in the Dynamic Help window when an item in a solution based on an enterprise template is selected in the VS .NET IDE. A custom help topic is created in a document, such as an HTML document, and linked to a policy file using a context file.

  • We covered the following topics:

  • How the Dynamic Help window works

  • How to create help topics

  • Working with context files, including help categories, and context keywords

  • How to add help topic references to items in a policy file

  • How to display Dynamic Help window debugging information

  • How to change the Dynamic Help window display

The following chapter will teach you about source code control and versioning, and how you avoid overwriting changes made by other developers.


Chapter 11: Visual SourceSafe

Overview

VS .NET can be used with any source control application that is Microsoft Source Code Control Interface (MSSCCI)-compliant. In this chapter, you'll learn about using the source code locking and versioning facilities provided by Microsoft's Visual SourceSafe (VSS) 6.0d, which is the source control application that comes with VSED and VSEA. VSS 6.0d integrates into the VS .NET IDE.

This chapter provides an overview of source control in general and VSS 6.0d specifically. You can read the chapter from start to finish to get up and running with VSS, and also use it as a quick reference guide when you need information about how to perform a certain VSS operation. Before going into the specifics for VSS, let's take a quick look at the benefits of source control in general.


Why Use Source Control?

The first question you hear in just about any organization, when source control in any shape or form is being discussed, is "What's the reason for using source control?" Well, there certainly are some good reasons for using source control, especially when developing in teams, but also when working on single-developer projects:

  • Versioning: Every time you save a source control item to the VSS project database, a new version is stored. This makes it possible to go back to a previous version of an item, in case something unexpected happens.

    Note

    When referring to source control items in this chapter, we mean any file or document under source control.

  • Locking: When you check out an item from the VSS project database, it's locked by you, meaning it's protected from any changes made by other developers. This makes it possible for teams to work on the same project, without running the risk of overwriting changes made by other developers.

  • Project-oriented control: VSS is project-oriented, which means that VSS is used to control items through the project. In many ways, a project in VSS can be compared to a folder/directory in a file system. However, the versioning, locking, history, and merge facilities of VSS set it apart.

    Note

    The project-oriented approach of VSS is in contrast to most modern file systems, such as NTFS, which can be used to control individual files. Although file systems like NTFS have many utilities for recovery and backup, these utilities always work at the individual file level.

  • Project item sharing: You can share items located in one project with other projects, without having multiple copies of the same item. This works much like a component that holds general procedures for use in many different projects.

  • Merging two versions of a project item: If you have two different versions of the same project item, you can have the source control application merge the two items, forming a single item.

  • Security and audit trail: Because of the way changes are recorded with user information, each version of a project item in a database can be tracked back to the user who checked in the project item.

  • Storage: The items in the VSS database, and most other source control databases, are placed in a central and, usually, remote location. When you check in your edited items, they're placed in the VSS database. This makes it easy to back up the database in one step, instead of needing to back up all the files that make up a project on various machines.

  • IDE integration: Source control applications like VSS provide great ease of use. Instead of having to use a separate application for managing the source control, you can use the tools integrated into the IDE. And if you choose to in the IDE integration setup, you can have most of the daily routines performed for you automatically.

VSS can not only be used with your code files, but it can also be used with other types of files, including Word documents, Visio files (UML, database schema, and so on), and even text and binary files. So, even if this chapter is all about using VSS with your source code, you can apply these concepts to any files that are part of your project. By default, VSS handles project items automatically, and they're handled as either text files or binary files.

Note

There is a potential problem with text files in Unicode format. Microsoft warns about potential corruption problems if you add files in Unicode format as text files. The workaround is to add them as binary files. See the READMESS.HTM file for more information. This file is located in the VSS installation folder on your system, and in the VSS root folder of your installation media.


The VSS Architecture

Now that we've established some of the reasons for using source control, let's look at how VSS is put together.

VSS is based on the client/server architecture: one server with one or more projects, and one or more clients connecting to one or more projects on the server. However, the server-side application is not a service that services the clients, for example, by responding to requests for updates. With VSS, the client does all the communication initiation, pulls updates from the server, and pushes updates to the server. (If you have ever worked with Microsoft Mail Server, the predecessor to Microsoft Exchange Server, you know what we mean.) In very simple terms, the VSS server is nothing but a shared folder on the server's file system.

Figure 11-1 shows a common VSS network setup with four clients and three VSS database servers. As you can see, the machines have different Windows operating systems. The clients connect to one or more database servers.

Click To expand
Figure 11-1: A common VSS network setup

Servers/VSS Database Servers

The central database, which contains the master copy of the items in each of the projects, is placed on a server. This server doesn't need to be a "real" server like Windows 2000 Server or Windows Server 2003; it can be any machine with a Windows operating system installed that can host VSS. However, in multideveloper environments, it is important that the server be available at all times, so that the developers have ready access to their projects. A VSS database server can hold any number of projects.

Note

A server can also function as a workstation. Although it's not ideal, it's often how it's done in smaller development teams, especially when only a single developer works on a project.

Workstations/VSS Clients

A VSS workstation is any machine with a Windows operating system installed that can host the VSS client application. A VSS client can connect to any number of VSS databases, or VSS servers. This means that developers can be part of any number of projects from a single machine, although the projects may be in different VSS databases and even on different machines.

Note

Although VSS can be installed and run on a Windows 98 client, you can't use VS .NET on these systems.

A VSS client holds only a copy of the original project items in a local working directory. This way, you can work without being connected to the server. This can be advantageous when you're not actually connected to the network on which your VSS server is located. The working directory can be any folder on your machine. It's set up when you connect to a project on a VSS database server, but it can be changed at anytime.

Database Organization

The database on the server isn't a database in the way most people think of a database; it's not a Microsoft SQL Server database, nor is it a Microsoft Access database file (*.mdb). The VSS database is merely a file system folder on the server's file system. VSS was installed into this folder, but the main VSS folder holds only two files that are used to keep track of projects and users in the database. This main VSS folder, which should be network shared for easy access from the client, also holds a data folder, which is where the files of the various projects are stored in a proprietary format.

Note

An issue to consider seriously is how and with what frequency the VSS database is backed up. See the "Archiving/Restoring Databases and Projects" section later in this chapter for more information.

Database Folders and Files

Most of the files located in the data folder and its subfolders aren't human-readable, and none of them should ever be edited manually. You should work with these files only through the VSS client and administration applications. However, if you're like us, you want to know what makes up an application in the form of files, especially configuration files. Table 11-1 contains a list of the important folders and files in the VSS database.

Note

The log files within the a through z subfolders in the data folder hold information that VSS uses for versioning purposes, such as differences between all saved versions. The first project file is named aaaaaaaa.a or aaaaaaaa.b in the a folder. The extension toggles between .a and .b, meaning that if no project file exists, the extension is .a, and if a project file exists with an .a extension, the new extension is .b. If a project file exists with a .b extension, the new extension is .a. You should never have both versions of the project file at the same time. When a new file is written, the log file is updated with version information, and the old file is deleted. See Knowledge Base Article 157714 at http:// support.microsoft.com/default.aspx?scid=kb;en-us;157714 for more information.

Table 11-1. VSS Database Folders and Files
Folder/File Name | Location | Type | Description
a – z | data folder | Folder | Folders that contain the actual project data and log files. Files are placed in these 26 folders evenly, starting with the a folder, then the bfolder and so on. The log files have no extension. In the a folder, the first log file is named aaaaaaaa; in the bfolder, it is baaaaaaa. Subsequent files in the a folder are named abaaaaaa and acaaaaaa.
aaaaaaaa.cnt | data folder | File | Holds the actual name of the file that was last added to the database. This doesn't mean the last project file, but the last database file. Therefore, if the content of this file is JAAAAAAA, then the last file added to the database is the file jaaaaaaa.a or jaaaaaaa.b in the j subfolder of the data folder.
backup | data folder | Folder | Used by the Analyze utility for placing the original version of any file that has been repaired.
crcs.dat | data folder | File | Holds Cyclic Redundancy Code (CRC) algorithm information that is used to improve performance when checking out and getting files from the database.
data | Folder | Main VSS folder | The actual VSS database folder
ddcerr.log | data folder | File | An error log file for the DDCONV utility application (ddconv.exe) file located in the win32 folder. This utility is used to upgrade databases to version 6.0 format from earlier versions.
labels | data folder | Folder | Holds label cache information, which is used for label promotion. (See your documentation for more information.)
locks | data folder | Folder | Holds any locks in use if VSS locking is enabled.
loggedin | data folder | Folder | Contains logon files for the logged in users <username>.log) and the administrative lock file (admin.lck), if the database is locked.
names.dat | data folder | File | Used to track long file name information; that is, project items with names that are longer than 34 characters.
netsetup.x86 | Main VSS folder | Folder | Holds files for connecting from a client and setting up a VSS client on that client. This folder is installed only if you choose to install a shared database server when installing VSS, or if you choose to install the network client setup when customizing the installation. (Consult your VSS documentation for more information about installing VSS.)
NETSETUP.EXE | Main VSS folder | File | The actual setup executable to run from a client, on which you want to install the client version of VSS. This file is installed only if you choose to install a shared database server when installing VSS, or if you choose to install the network client setup when customizing the installation.
NETSETUP.LST | Main VSS folder | File | The configuration file used by the NETSETUP.EXE executable. This file is installed only if you choose to install a shared database server when installing VSS, or if you choose to install the network client setup when customizing the installation.
READMESS.HTM | File | Main VSS folder | The readme file with late-breaking changes and other information that isn't included in the documentation.
rights.dat | data folder | File | Holds security information about users and projects, such as which user can access which project(s); in other words, user /project relationships. If this file is corrupted in any way, you can fix it using the Analyze utility. (See the "Validating Database Integrity" section later in this chapter for more information.)
setup | Folder | Main VSS folder | Holds the files necessary to rerun setup without the original setup media.
srcsafe.ini | File | Main VSS folder | Holds the global database settings, as well as settings for all users of the database.
ss.ini | File | User subfolder in the users folder | Holds custom user-specific information, such as window height, toolbar placement, file execution applications, etc.
ssadmin.ini | File | User subfolder in the users folder | Like the ss.ini file, but used only in connection with the Visual SourceSafe Administrator application. Only the Admin user has this file stored in the User subfolder.
status.dat | data folder | File | A cache file for the VSS Explorer client application that stores the checkout status for the project items. Caching this information speeds up client retrieval of project items. If this file is corrupted in any way, you can fix it using the Analyze utility. (See the "Validating Database Integrity" section later in this chapter for more information.)
temp | Folder | Main VSS folder | Used by VSS client and server applications for holding temporary files, created when performing various tasks.
template | Folder | Main VSS folder | Holds templates for the configuration files, such as srcsafe.ini. You can modify these templates, and your changes will be reflected when creating new users.
um.dat | data folder | File | The user management file, which holds the user and password combinations for the database. If this file is corrupted in any way, you can fix it using the Analyze utility. (See the "Validating Database Integrity" section later in this chapter for more information.)
users | Folder | Main VSS folder | Holds a subfolder for each user registered in the database. Each of these subfolders holds an ss.ini and also an ssadmin.ini configuration file if the user is an Admin user.
users.txt | File | Main VSS folder | Holds a list of all users in the VSS database. (See the "Securing Default Users " section later in this chapter for more information.)
version.dat | data folder | File | Holds the database versions, such as 6.0. If this file is corrupted in any way, you can fix it using the Analyze utility. (See the "Validating Database Integrity" section later in this chapter for more information.)
VSSCLNT.SRG |  | Main VSS folder | Holds the Registry entries for a VSS client. The file can't be imported directly into the Registry, because of the various paths that haven't been fully specified.
win32 | Folder | Main VSS folder | Contains all the executable files, including command-line utilities.

Project Hierarchy

Every VSS database is a hierarchy of projects, starting with the root project at the top of the hierarchy. The root project, which is also commonly referred to as the root folder, is represented by adollar sign and a forward slash($/). All other projects in a database are subprojects of this root folder.

In Figure 11-2, you can see the root project of the VSS database named Microsoft Visual Studio, displayed in the Visual SourceSafe Explorer. You can open the Visual SourceSafe Explorer by selecting Start ®Microsoft Visual SourceSafe ®Microsoft Visual SourceSafe 6.0. The name of the currently open database appears in the title bar of the Visual SourceSafe Explorer application, after the two hyphens (--). This is also true for the Visual SourceSafe Administrator application, discussed in the "Visual SourceSafe Administration" section later in this chapter.

Click To expand
Figure 11-2: The root folder in Visual SourceSafe Explorer
Note

Any development project you have that uses VSS must be located in the same VSS database. It is not possible to have a development project that has project items in different VSS databases.


VSS Security

The built-in security in VSS is based on a simple user name/password combination. This doesn't prevent anyone from accessing the VSS database directly through the file system on which the database is located. In other words, there's no built-in security mechanism to prevent someone from accessing the database directly. Therefore, you should secure the folders that host the VSS database using the functionality provided by the file system. For this reason alone, it is advisable to use a modern file system such as NFTS, which provides proper user/role/group-based security functionality, such as authentication.

How you set up authentication depends on your specific operating system. However, there are two ways you can secure the files using authentication:

  • Remote-access security, to control which users can access the share set up on the VSS folder

  • Local-access security, to control which users can access the VSS folder locally

In practice, the local-access settings might be sufficient, meaning that users who don't have local access also won't be granted remote access, even if the share settings allow it. So, setting the local-access settings might be all you need to worry about.

Folder Sharing

If your development team requires access to a VSS database on a server, you need to share the VSS main folder. This folder contains the srcsafe.ini file, which holds information about the database.

Note

Have your system administrator set up a network share on the VSS main folder. You can choose to do this yourself, but it's our firm belief that developers shouldn't be managing permissions on a network, so unless you're a system administrator (or hold a similar position), don't do it.

Securing Default Users

When you install VSS or create a new VSS database, the Admin and Guest users are automatically created, but neither has a password by default. We strongly suggest that you assign a password to the Admin user and either delete the Guest user or assign it a password as well.

Note

There's no relationship between the users in VSS and Windows users. However, check out the "Establish a User Naming Convention" section at the end of this chapter for information about how you can bring the two sets of users closer.

Figure 11-3 shows the default users.txt file in Notepad. This file holds the two default users: Admin and Guest. As you can see, each user entry contains the name of the user and a path to the file containing the actual settings for the user. The content of this file is changed as you add and remove VSS users. (See the "User Administration" section later in this chapter for more information about managing VSS users.)

Click To expand
Figure 11-3: The default users.txt file


VSS Integration with the VS .NET IDE

VSS integrates into the VS .NET IDE in a number of ways. This section describes the interface additions and the source control options that you can access from the VS .NET IDE. You'll learn how to use these features in the "Using Visual SourceSafe"section later in this chapter.

Interface Additions

When VSS is installed, several items are added to the VS .NET IDE: a Source Control menu accessible from the File menu, a Pending Checkins window, and Source Control option in the Output window.

Source Control Menu

To see the VSS menu, choose File ® Source Control. Here is how the menu looks when a solution is open in the IDE:

Click To expand

When a solution isn't open, only the Open From Source Control and Microsoft Visual Source Safe options are available from the menu.

Pending Checkins Window

The Pending Checkins window is added to the windows at the bottom of the IDE, as shown in Figure 11-4. This window shows all of the items that are currently checked out in a project. To open the Pending Checkins window, select View ®Pending Checkins, or right-click any project item under source control in the Solution Explorer and select Show Pending Checkins from the pop-up menu. The Pending Checkins window will appear, even if no solution is open in the IDE or the open solution does not have any projects under source control.

Click To expand
Figure 11-4: Pending Checkins window
Tip

Use the Pending Checkins window to quickly see what has been checked out on your machine. If you have a project consisting of 20 or more files or so, viewing the Pending Checkins window is much quicker than going through the items in the Solution Explorer.

The Pending Checkins window gives you a quick overview of the items that are currently checked out. This isn't necessary with small projects containing only a handful of items, but the bigger the project, the easier it is to lose the overview of what is currently checked out. You can also check in items from this window.

Output Window's Source Control List

When is VSS installed, the IDE's Output window has a Source Control list item added to it. To open the Output window, select View ® Other Windows ® Output menu item or press Ctrl-Alt-O. In Figure 11-5, you can see the Output window with Source Control selected from the drop-down list at the top of the window.

Click To expand
Figure 11-5: Output window with Source Control selected

In the Source Control output, you can see all the VSS operations that have been performed since you opened the solution. The information in this window isn't all that informative; it merely gives the time when an operation started and ended, similar to this:

---- Operation started at time 07:19:05 ----
---- Operation completed successfully at time 07:19:05 ----

This output (and any other output in the Output window) is cleared when a solution is closed.

Start Sidebar
Using the Task List in Team Development

There is no direct VSS information in the Task List. It will show only indirect information, such as problems with missing files when moving a project to a different machine. This can happen if one or more files aren't part of the VSS project, and thus you'll get an error reference in the Task List.

A handy application of the Task List related to VSS is a kind of bulletin board. Developers can leave notes for other members of a team (or possibly themselves), concerning source control, such as comments about unfinished VSS tasks.

For example, when you have an item that's nearly finished, and you need someone else to finish it for you, you can leave the other developer a note on the Task List. When you get the item back, there should be a reminder about the VSS check-in task in the Task List.

End Sidebar

Source Control Options

You can control source control settings in the VS .NET IDE through the Options dialog box (displayed by selecting the Tools ®Options). In the Options list, there are two categories under Source Control: General and SCC Provider.

General Options

Figure 11-6 shows the General category options under Source Control. This category has several groups of options.

Click To expand
Figure 11-6: General options under Source Control in the Options dialog box
Roles

The drop-down list at the top of the dialog box lets you choose which role to use for the settings in the dialog box. The following roles are provided when VSS is installed (these roles are predefined and can't be changed):

  • Visual SourceSafe: This role sets the options according to the default VSS settings, or rather the most commonly used VSS settings.

  • Independent Developer: This role is for independent developers, meaning developers who don't work in a team. When you're not working in a team, you generally have different considerations when it comes to source control.

  • Custom: Custom isn't really a role as such. Custom is automatically selected when you check or uncheck options that have been specified with one of the other roles. When you select the Custom role, all options from the previous role are preserved.

    Note

    When you have made customizations to the source control settings, these customizations are lost when you select one of the predefined roles, except Custom. However, if you do so by mistake, you can always click the Cancel button in the Options dialog box to prevent the changes from being saved.
Action When Opening or Closing a Solution

The first two options in the dialog box deal with what happens when you open a solution and when you close a solution:

  • Get everything when a solution is opened: If this option is selected, all items under source control will be updated to their latest version, if necessary, when you open a solution.

  • Check in everything when closing a solution: When you select this option, all checked-out project items are automatically checked in when you close your solution. We don't recommend selecting this option, because it will more than likely cause an unfinished item to be checked in. An unfinished item is an item that can't be compiled, results in runtime errors, or other unwanted behavior.[1]

Menu Commands

The next two options in the dialog box are Display silent check out command in menus and Display silent check in command in menus. These control the display of the Check Out Now and Check In Now menu options. Choosing the corresponding "silent" command will have the Check Out Now or Check In Now menu item replace the Check Out or Check In option in the File menu, and also in the pop-up menus when you right-click a checked-in item in the Solution Explorer. In the File® Source Control menu, the Check Out Now or Check In Now menu item is added. Checking in and out, including "silently," is discussed in the "Using Visual SourceSafe" section later in this chapter.

Action When Performing Operations on Checked-in Items

The remaining options are settings for handling operations on checked-in items. The fifth option in the Options dialog box is labeled Keep items checked out when checking in. This is a very neat option, and we tend use it for our daily work. Because we check in items after every minor change, it saves time to keep it checked out after checking in. This way, the latest version of the item is saved to the VSS database, but the item is still checked out to the developer.

The next drop-down list has four options for what happens when checked-in items are edited:

  • Prompt for check out: We suggest that this setting, which is the default, should always be used, because it will prevent overwriting any changes, and you'll be prompted for checking the item out before continuing.

  • Prompt for exclusive checkouts: Although this setting is safer than the previous one, it will effectively prevent sharing of project items, because it will disallow multiple check-outs. This is a good thing, because multiple check-outs shouldn't be allowed or disallowed on a per-item basis. Rather, you should set this option for an entire project.

  • Check out automatically: Although this is a safe option, we don't recommend it, because if you don't notice that the item has been checked out, you might forget to check it in afterwards.

  • Do nothing: This is certainly a safe option, which disallows the editing of any checked-in item. However, we feel that in most, if not all, cases it's nicer to be prompted for a check-out if you try to edit a checked-in item.

The option following the options for when checked-in items are edited is labeled Allow checked-in items to be edited. This option is somewhat dangerous, because it can lead to changes being overwritten. We don't recommend it. However, choosing an option from the drop-down list below, which controls what happenswhen checked-in items are saved, can make it safer to allow the editing of checked-in items. The bottom drop-down list offers these settings:

  • Prompt for check out: If the version in the database hasn't changed, you're prompted to check out the edited item.

  • Check out automatically: If the version in the database hasn't changed, and you've enabled silent check-out, the item is automatically checked out. If silent check-out isn't enabled, you're prompted for a comment for the check-out.

  • Save as: This is by far the safest of the three possible settings. It prompts you for a path to where the item should be saved.

There's no guarantee that another user hasn't made changes to the item during the time you retrieved the latest version of the item and the time you try to save it. If so, VSS can't check out the item from the database, because it will overwrite the version you're currently editing. In this case, when you have either Prompt for check out or Check out automatically selected as the action when checked-in items are saved, you will see the Conflicting Modifications Detected dialog box, as shown in Figure 11-7. Here, you're prompted if you want to overwrite the existingversion of the item on your disk or save it under a different name. In either case, you'll need to manually merge the version on your disk with the version in the database, as described in the "Merging Item Versions" section later in this chapter.

Click To expand
Figure 11-7: This can happen when you allow editing of checked-in items.

SCC Provider Options

Figure 11-8 shows the SCC Provider category options under Source Control. These options are provider-specific.

Click To expand
Figure 11-8: SCC Provider options under Source Control in the Options dialog box

As in the General category options, the drop-down list at the top of the dialog box lets you choose which role to use for the settings in the dialog box: Visual SourceSafe, Independent Developer, or Custom. If you have any other MSSCCI-compliant source control providers installed on your setup, you'll have other items in this list.

The Login ID (SourceSafe) text box is provider-specific. The content of this text box should be the user ID that you want to use to connect to the source control database. You have the option of changing the user ID when you specify the password, before logging on to the database.

The Perform background status updates option lets you choose whether you want status updates to be performed in the background. When you're working on a high-bandwidth network with your source control database available at all times, you should select this option. However, if you're on a dial-up network, or your source control database isn't always available, you shouldn't select this option. Instead, you should update the status manually by selecting File ®Source Control® Refresh Status.

The real provider-specific options are available when you select the Advanced button. If you're working with VSS, you first need to log in to your VSS database,[2] as shown in Figure 11-9.

Click To expand
Figure 11-9: Visual SourceSafe Login dialog box

After you've clicked the Advanced button to set vendor-specific options, and logged in to the VSS database if necessary, the SourceSafe Options dialog box appears, as shown in Figure 11-10.

Click To expand
Figure 11-10: The General tab of the SourceSafe Options dialog box, showing vendor-specific options
Note

If you have a different source control provider, such as SourceOffSite, the Options dialog box will look different.

The General and Local Files tabs of the SourceSafe Options dialog box are the same as the ones in the Visual SourceSafe Explorer application. Here, we'll look at the Integration tab, shown in Figure 11-11, which contains options that affect some of VSS menu items in the VS .NET IDE.

Click To expand
Figure 11-11: Integration tab of the SourceSafe Options dialog box

The Connection Information section of the Integration tab shows the project root and the name, path, and data specifier (which is the data folder) of the database in which the project is stored.

The Display dialog box section of the Integration tab has two options:

  • History: Select this option to display the History Options dialog box, prompting for history details, when you select File ® Source Control ®History.

  • Diff: Select this option to display the Difference Options dialog box, prompting for difference details, when you select File ® Source Control®Compare Versions.

The Choose SourceSafe Database section of the Integration tab lets you select between two options: you can have a dialog box displayed when you add a new project to source control, prompting for which database to use, or you can use the default database.

[1]On the other hand, a finished item is one that has been completed with regard to the changes that were scheduled for a given period.

[2]This only happens the first time you click the Advanced button in each session (each time you open the VS .NET IDE).


Getting Started

This section is intended for first-time VSS users and administrators. We will give you an overview of how to get started with VSS, including how to set up the server and clients. Here, we will outline which actions to perform and in which order. The actual instructions for performing the tasks are given in other sections of this chapter.

If you haven't installed and set up VSS yet, we suggest you install the product after reading the accompanying documentation. After you've finished installing the software, make sure you make the default database[3] available to all the users you want to access the projects you plan to keep in the database. This means setting up folder sharing of the database folder (see the "Folder Sharing" section earlier in this chapter) and creating one or more user accounts for those people who need to access the database (see the "User Administration" section later in this chapter).

Accessing VSS Projects

If you haven't created a VSS project yet, you first need to add whatever solution you're working on to the VSS database (see the "Adding a Development Solution/Project to Source Control" section later in this chapter). If you plan to use individual project and user rights, you need to enable them (see the "Enabling Individual User/Project Rights" section later in this chapter).

Once a project exists in a VSS database, all you need to do is to tell each team member to retrieve the project from the VSS database. Make sure you tell the developers where to find the database (the machine and share name on the network: \\MachineName\ShareName).

You can find information about connecting to a VSS database in the "Connect to a VSS Database" section later in this chapter, and information about retrieving a project from a VSS database in the "Creating a New Development Project from Source Control" section later in this chapter.

Editing a Project Item

When you're ready to edit a project item, you need to do the following:

  • Check the project item out from the project (see the "Checking Out Items" section later in this chapter).

  • Make your changes to the project item.

  • Test and validate the changes made to the project item, making sure it's functional.

  • Check in the project item (see the "Checking In Items" section later in this chapter).

If you're getting started with VSS, you'll need to perform some tasks in the Visual SourceSafe Administrator application, as described in the next section.

[3]If you plan to use a different database, make sure you have access to it, or create a new one if that is necessary. See your documentation for information about how to create a new database.


Visual SourceSafe Administration

Administering Visual SourceSafe is a straightforward task, but there are a few caveats, as you will learn in this section. For most administrative tasks, you use the Visual SourceSafe Administrator application. First, we'll look at starting up that application, and then we'll cover the two main categories of administrative tasks: user administration and database administration.

Visual SourceSafe Administrator Application Startup

The Visual SourceSafe Administrator application is shown in Figure 11-12. To start this application, select Start ® Programs ® Microsoft Visual SourceSafe®Visual SourceSafe 6.0 Admin (or use the Start ® Run command to run ssadmin.exe).

Click To expand
Figure 11-12: Visual SourceSafe Administrator application

When you open the Visual SourceSafe Administrator application, the Visual SourceSafe Login dialog box appears. This is the same dialog box as shown earlier in Figure 11-9, with one difference: The Username text box is disabled and is filled in with the administrator's user name, Admin. This is the only user who can log in and open the Visual SourceSafe Administrator application. Enter the password and click OK to continue.

You can also run the Visual SourceSafe Administrator application by executing the \Program Files\Microsoft Visual Studio\VSS\win32\SSADMIN.EXE (using the correct path on your system, which depends on where you installed VSS) command from the VS .NET 2003 Command Prompt window. To open this window, select Start® Programs ® Microsoft Visual Studio .NET 2003 ® Visual Studio .NET Tools® Visual Studio .NET 2003 Command Prompt. Be aware that none of the VSS installation folders are added to the path that is searched when you open the VS .NET 2003 Command Prompt window, so you need to either execute the full path or add the folder to the search list manually, which you can do in two ways.

One way to add the folder to the search list is to add the Win32 VSS folder to the \Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\ vsvars32.bat command/batch file. This file is parsed by Cmd.exe[4] when you open the VS .NET 2003 Command Prompt window. The Win32 VSS folder should be added to the following @set PATH line, which might look similar to this:

@set PATH=%DevEnvDir%;%MSVCDir%\BIN;%VCINSTALLDIR%\Common7\Tools;%VCINSTALLDIR%
\Common7\Tools\bin\prerelease;%VCINSTALLDIR%\Common7\Tools\bin;%FrameworkSDKDir%
\bin;%FrameworkDir%\%FrameworkVersion%;%PATH%;

You should add your folders before the %PATH%; at the end of the line, which is where the general Path environment variable is added. Make sure you separate various folders with a semicolon (;) as shown in the example.

Another way to add the folder to the search list is to add the Win32 VSS folder to the general Path environment variables through the System applet in the Control Panel. Open that applet, choose the Advanced tab, and then click the Environment Variables button to open the Environment Variables dialog box. Figure 11-13 shows the Environment Variables dialog box with the Path variable selected. Simply click the Edit button to edit the Path variable. Be aware that this will add the folder(s) to any Command Prompt window that is opened, not just the VS .NET 2003 Command Prompt.

Click To expand
Figure 11-13: Environment Variables dialog box

Along with the Visual SourceSafe Administrator application, you can run some of the other VSS utilities from the command line. If you really like using the command line instead of the Windows UI for your administration, we suggest that you add the following VSS folder using either of the methods just described:

\Program Files\Microsoft Visual Studio\VSS\win32

Remember that the path might be different on your system, depending on where VSS is installed.

Note

Most of the changes you make using the Visual SourceSafe Administrator application don't go into effect until you close the application.

User Administration

When you first install VSS, two default users are created: Admin and Guest. These users, as well as the other users you will set up, are database-specific.

You administer users through the Visual SourceSafe Administrator application (see Figure 11-12). All user actions in the Visual SourceSafe Administrator appli cation are performed on the open database. Before performing any administrative tasks, make sure you open the correct database by selecting the Users ® Open SourceSafe Database or by pressing Ctrl-O.

Adding Users

User administration in VSS is integrated and based on a rather simple user ID and password combination. Therefore, you need to make sure that any users, except the two default ones, are created in each database to which you need to give them access. Because no central network-wide user authentication, such as Windows authentication, can be used with VSS user administration, you must add each user, except for the two default ones, to any database the user needs to access.

Note

If you need to add each user to several databases, why not have a user group for several users and at least save some of the manual work? You can do this, but we think this is a bad idea, because there's no way of auditing which user did what. Let's assume that a user has deleted one or more project items, checked in one or more unusable project items, and perhaps performed other actions that violate your VSS policies. You might want to use auditing to find out which user is responsible, but you can't, because when you find the user ID, you see only a common user group, used by more than one user. All user names are stored in the users.txt file.

To add a new user, select Users ® Add User or press Ctrl-A. This brings up the Add User dialog box, as shown in Figure 11-14. Simply give the new user a name and password in the corresponding text boxes. If you don't want the user to be able to make changes, you can select the Read only option. Notice the security warning in the dialog box with regard to read-only users; click the Help button for more information about this issue. If you try to add a user with an existing name, you'll get an error.

Click To expand
Figure 11-14: Add User dialog box in Visual SourceSafe Administrator

Removing Users

To remove a user from the open VSS database, first select that user in the main list of the Visual SourceSafe Administrator application, and then select Users ®Delete User or press Ctrl-D. This brings up a confirm user deletion dialog box, as shown in Figure 11-15. Notice the security warning with regard to user sharing permissions; select the Help button for more information.

Click To expand
Figure 11-15: Confirm User Deletion dialog box
Note

You can't delete the Admin user or change this user's settings.

Changing User Settings

If you want to change the user name or the read-only user setting, select Users ®Edit User or press Ctrl-E. This brings up the Edit User dialog box, as shown in Figure 11-16. If you change the name of a user, the corresponding file and folder in the database are renamed accordingly.

Click To expand
Figure 11-16: Edit User dialog box
Caution

If you change the name of a user who is logged in, an error will occur when the user logs out. This is because the log file in the loggedin folder still has the old name. Also, renaming a user with checked-out project items requires the Admin user to force the check- in, because the original user no longer exists, and he or she can no longer check in the project item. Therefore, if you really need to make changes to a user's name, make sure that user doesn't have any project items checked out and isn't logged in.

You can also change a user's password. Just select the user in the main list of the Visual SourceSafe Administrator application, and then select Users ®Change Password to open the Change Password dialog box.

Enabling Individual User/Project Rights

By default, all users in a database can read project items in any project in the database. If they're not marked as read-only, they can also make changes to the project items. This is hardly ever the right way of approaching user administration. However, there's a solution: enable user/project rights assignment, which is done from the Visual SourceSafe Administrator application.

Choose Tools ® Options to open the SourceSafe Options dialog box, and then select the Project Rights tab, as shown in Figure 11-17. On this tab, there's an Enable Rights and Assignments commands option, which you must select in order to assign individual project rights to the users of a VSS database.

Click To expand
Figure 11-17: Project Rights tab of the SourceSafe Options dialog box

Selecting the Enable Rights and Assignments commands option enables the assignment of the following project rights:

  • Read: Allows reading projects and project items.

  • Check Out/Check In: Allows checking in and out projects and project items.

  • Add/Rename/Delete: Allows adding, renaming, and deleting projects and project items.

  • Destroy: Allows destruction (permanent/unrecoverable deletion) of projects and project items.

    Note

    When you enable project rights assignment, the enabled rights are automatically enabled for all new projects as well as the root project. Subsequently, you can change the rights for the users in the individual projects. See your documentation for more information about assigning project/user rights.

Database Administration

You'll need to perform some administration and maintenance of your VSS data bases on the server, as well as on the clients. Some administrative tasks are performed using the Visual SourceSafe Administrator application, and others are done from the VS. NET IDE or the command line.

Locking the Database for Maintenance

When you perform some maintenance operations on your VSS database, such as changing the location for the temporary files, it's a good idea—and in some cases, a must—that you log out all users before you perform the operation. However, a user might log in during the operation, which is why you need to lock the database.

To lock the database, in the Visual SourceSafe Administrator application, select Tools® Lock SourceSafe. This brings up the Lock Visual SourceSafe Database dialog box, as shown in Figure 11-18.

Click To expand
Figure 11-18: Lock Visual SourceSafe Database dialog box

In the Lock Visual SourceSafe Database dialog box, you must select the Lock all users out of Visual SourceSafe option. This will prevent all users from logging on, but it will not lock out the users listed in the list box. You must manually notify these users and have them log out. When you want to unlock the database, return to this dialog box and deselect the Lock all users out of Visual SourceSafe option.

Caution

Remember that the users listed in the list box of the Lock Visual SourceSafe Database dialog box will not be locked out when you select the Lock all users out of Visual SourceSafe option. You must manually notify these users.

Now, the UI in the Visual SourceSafe Administrator application isn't all that intuitive, and you might have problems knowing when a database is locked. So, how do you tell? Take a look at Figure 11-19. In the bottom-right corner of the Visual SourceSafe Administrator window, there's a yellow key that indicates that the currently open database is locked.

Click To expand
Figure 11-19: Database locked in Visual SourceSafe Administrator

Validating Database Integrity

The VSS database isn't the best-designed database we've ever seen, and inconsis tencies do occur. We don't want to paint a grim picture, but you need to be aware of this fact.

Okay, so inconsistencies creep into the VSS database as a result of daily use, but how do you fix them? You fix them by periodically validating the database integrity. The tool for this purpose is the Analyze command-line utility.

The inconsistencies and unwanted side effects in a VSS database that the Analyze utility can fix are as follows:

  • Corrupted files

  • Removal of unused project items

  • Parent and child items mismatch

  • Wasted unused disk space

  • Shared and branched items mismatch

It's good practice to run Analyze on a frequent basis. This will help to prevent minor errors from becoming really problematic errors. In other words, you will be able to fix the minor errors before they escalate.

Before you run Analyze, make sure it will have good working conditions, so it will operate in a flawless and effective manner. First, make sure there is plenty of free disk space; Analyze will crash if it runs out of space during operation. Second, log out all users and lock the database while Analyze is running, as described in the previous section.

The Analyze utility is command-line-based and the actual file name is analyze.exe. This file is placed in the \Program Files\Microsoft Visual Studio\ VSS\win32 folder (the path might be different on your setup). You can run it from the VS .NET 2003 Command Prompt window (select Start ® Programs ®Microsoft Visual Studio .NET 2003 ® Visual Studio .NET Tools ®Visual Studio .NET 2003 Command Prompt). If you have added this path to the search list, as described in the "Visual SourceSafe Administrator Application Startup" section earlier in this chapter, you can run this utility from any folder. Although the Analyze utility is command-line-based, Microsoft has added a "sluggish" UI and made it accessible from the Start menu in two different ways:

  • Analyze and Fix VSS DB: You can use this menu item for analyzing and fixing the current VSS database.

  • Analyze VSS DB: You can use this menu item for a quick analysis of the current VSS database.

Although you have these options for running the Analyze utility, they don't give you the flexibility of running it from the command-line using the various switches.[5] To see Analyze's command-line switches, run Analyze /? from the command prompt. This brings up the help window shown in Figure 11-20.

Click To expand
Figure 11-20: Analyze help window listing the command-line switches

Archiving Databases and Projects

Archiving a VSS database or project serves some different purposes, such as the following:

  • Removing rarely used projects from a database to save space and to improve VSS performance

  • Copying or moving projects or project items between different databases

  • Backing up databases or projects for security reasons

To archive a database or project, select Archive ® Archive Projects in the Visual SourceSafe Administration application.

Click To expand

Caution

The archive and restore operations performed from within the Visual SourceSafe Administration application are always done on the currently open database. Make sure you open the correct database before attempting to archive or restore a database.

This brings up the Choose Project to Archive dialog box, as shown in Figure 11-21. Here, you can choose to archive the root project, which effectively means the entire database, or any project shown in the dialog box.

Click To expand
Figure 11-21: Choose Project to Archive dialog box
Tip

Select the root project ($/) if you want to archive the entire database currently open in the Visual SourceSafe Administration application.

The VSS database has a hierarchical nature, meaning that when you select a project to archive, you archive all items and all subprojects within the selected project. However, this doesn't mean that you must archive the parent project in order to archive two of more subprojects.

After you select a project and click OK in the Choose Project to Archive dialog box, the Archive Wizard starts. This wizard guides you through three steps: adding projects to archive, specifying the handling of the archived projects within the existing database, and specifying additional options.

Note

As of version 6.0, VSS now offers the features of the two archive and restore command-line utilities from within the Visual SourceSafe Administration application. Here, we explain how to use the Windows UI features of the Visual SourceSafe Administration application.
Adding Projects to Archive

The Archive Wizard, Step 1 of 3 page is shown in Figure 11-22. The Projects to archive list contains the project you just selected. Any subprojects aren't shown, but they will be archived as well.

Click To expand
Figure 11-22: Archive Wizard, Step 1 of 3

If you want to add a project, simply click the Add button. This will bring up the Choose Project to Archive dialog box again (see Figure 11-21). If you need to remove a project that has been added in error, select it in the Projects to archive list and click the Remove button. Note that you're not required to confirm the removal.

Handling the Archived Projects in the Existing Database

Next, you see the Step 2 of 3 page of the Archive Wizard, as shown in Figure 11-23. You have three options for how the archived projects will be dealt with in the existing database, after the projects have been archived.

Click To expand
Figure 11-23: Archive Wizard, Step 2 of 3

This is what the three options do:

  • Save data to file: This is the default option, and it simply archives the selected projects. The data in the database is left intact, which means this is the option to use when you want to back up your database or project. It can also be used to copy data to another database.

  • Save data to file, then delete data from database to save space: Besides backing up the selected project, this will also remove the selected project from the database. As suggested by the option's name, this will save disk space in your VSS database. You can use this option to move projects to another database or to remove projects that are used infrequently.

  • Delete data permanently: This isn't really an archive operation; it's all about permanently removing data—projects and project items—from the database. Use this option to recover disk space from projects and/or project items that are no longer used.

    Note

    You can't use the second or third option to delete the root project; this isn't allowed.

If you choose either of the first two options, you must also specify the path and file name of the archive to create. We recommend that you click the Browse button to bring up the Save As dialog box for specifying the path and file name. This way, you can be sure that the path is valid. Entering an invalid path will cause an error when you click the Finish button in Step 3 of the Archive Wizard. If you enter the path and name of an existing file, you'll be prompted to overwrite the existing file when you click the Finish button.

Specifying Additional Options

In Figure 11-24, you can see the final step of the Archive Wizard. In this step, you have two options for which versions of the items in the selected projects to archive and/or delete.

Click To expand
Figure 11-24: Archive Wizard, Step 3 of 3

The default option is to archive and/or delete all versions, which is indicated by selecting the Archive all of the data option in the Version Range group. If you select the Archive this version and older option, you can control the versions that are archived and/or deleted. The Version text box is enabled once you select the latter option, and it must be filled in using one of the following options:

  • Version Number: This is used to indicate the version number of project items you want archived and/or deleted. So, if you specify 15, all project item versions up to and including version 15 are archived and/or deleted.

  • Label: Use this to indicate a label that specifies a specific version of project items you want archived and/or deleted. This option requires the letter L as prefix. Therefore, if you specify LVersionLabel, all project item versions up to and including the items labeled VersionLabel, are archived and/or deleted.

  • Date: This option is used for specifying a specific date of project items you want archived and/or deleted. This option requires the letter D as prefix, and the date should be specified in the format of the machine on which you run the archive operation. Therefore, if you specify D06-01-03, all project item versions up to and including the date June 1, 2003, are archived and/or deleted.

    Note

    If you specify a version to archive and this version doesn't exist, an error message is displayed.

Restoring a Database or Project

You might want to restore a database or project in order to move to and/or copy data from another database, or to retrieve archived items that no longer exist in the database. To restore a database or project, select Archive ® Restore Projects in the Visual SourceSafe Administration application.

As with the archive operation, a wizard guides you through the steps of the restore process. The Restore Wizard Step 1 of 3 page is shown in Figure 11-25. Here, you specify the path and file name of the archive file to restore. You can either type its name in the text box or click the Browse button to open the Open dialog box and navigate to the archive file.

Click To expand
Figure 11-25: Restore Wizard, Step 1 of 3

The Restore Wizard, Step 2 of 3 page, shown in Figure 11-26, has a Display subprojects option, which is not selected by default. When you select it (as in Figure 11-26), you can see all of the subprojects of the selected archive file and select which ones you want to restore; you don't have to restore every subproject in a project.

Click To expand
Figure 11-26: Restore Wizard, Step 2 of 3

In the final wizard step, shown in Figure 11-27, you have two options:

Click To expand
Figure 11-27: Restore Wizard, Step 3 of 3

  • Restore to the project the item the project was archived from: This option is most often used to restore a previous version of a project to a database.

  • Restore the project to a different location: This option is used for specifying a different target project than the one on which the archiving was performed. If you select this option, the corresponding text box and Browse button are enabled, forcing you to enter the path and name of an existing project in the currently open database.

After selecting the restore option and path and file name of the project to restore to, click the Finish button to start the restore process. Once the restore has finished, a success or failure message is displayed, depending on the outcome of the restore process.

Changing the Location of Temporary Files

Database temporary files are normally placed in the temp subfolder of the main VSS folder (see Table 11-1, earlier in the chapter). However, if you wish, you can change this location through the General tab of the SourceSafe Options dialog box (see Figure 11-10, earlier in the chapter). One way to access this dialog box is though the Visual SourceSafe Explorer application, opened by choosing Start ®Microsoft Visual SourceSafe ® Microsoft Visual SourceSafe 6.0. In Visual SourceSafe Explorer, select Tools ® Options. In the Folder for temporary files text box, enter the new path to where you want the temporary files placed, or click the Browse button to browse to the folder, and click OK to save the new setting.

Caution

If the folder specified doesn't exist, you're prompted if you want to create it. No matter how weird a path you enter, it will be created if allowed by the underlying file system. Say you type in C:\Program Files\Microsoft Visual Stdio\VSS\temp, but the C:\Program Files\Microsoft Visual Stdio folder doesn't exist, because it's actually named C:\Program Files\Microsoft Visual Studio. In this case, the three folders in the path Microsoft Visual Stdio\VSS\temp are created. So, be careful if you type in the path instead of browsing to a folder.

Another way to access the General tab of the SourceSafe Options dialog box is from within the VS. NET IDE, as described in the "Source Control Options" section earlier in this chapter. Select Tools ® Options, select the Source Control category, choose the SCC Provider subcategory, and then click the Advanced button.

You should change the location of temporary files only when all users are logged out of the VSS database, and the database is locked during the operation, as described in the "Locking a Database for Maintenance" section earlier in this chapter.

Cleaning Up the Temporary Folder

The temporary folder used by VSS for storing temporary files is normally cleaned up automatically. However, sometimes events such as a machine crash can leave files in the temporary folder. This isn't necessarily a bad thing, but eventually this folder might be filled up with unwanted and unnecessary temporary files. That's why VSS has an option to clean up this folder, available from the Visual SourceSafe Administrator application. In this application, select Tools ®Clean up Temp Directory. This opens the Clean Up Local Temporary Files Directory dialog box, as shown in Figure 11-28.

Click To expand
Figure 11-28: Clean Up Local Temporary Files Directory dialog box

Notice that the word Local appears in the title of the dialog box. This indi cates that the action affects the local temporary folder, not the one on the VSS server (unless the two happen to be the same, which is the case when both the server and client are installed on the same physical machine).

Note

The folder specified in the Clean Up Local Temporary Files Directory dialog box is supplied by the Visual SourceSafe Administrator application and can't be changed.

When you click OK in the Clean Up Local Temporary Files Directory dialog box, you're prompted for confirmation of the action.

Although cleaning up the temporary files action doesn't touch any files in use, you should really only perform this action when all users are logged out of the VSS database and the database is locked.

Recovering a VSS Database after Losing the Admin Password

You've been there, haven't you? You've lost the password for the Admin account. Well, maybe you haven't experienced this with a VSS database, but more than likely, you have had this happen with another application, database, or network. In many cases it's impossible to recover such a password, which means you need to start from scratch and lose whatever information is in your application, database, or network. If you've actually lost the VSS password for Admin, you know there's no officially documented way of recovering it. However, there is a way, as long as you are an administrator.

When you lose the Admin password, or perhaps corrupt a user file, you must create a new user and rights file. This will remove all users from your database, but the default Admin and Guest user accounts are re-created with default settings; that is, without passwords. Any other user you want to recover, including user rights (if you're using user and project rights), must be created again manually. Pretty simple, don't you think?

If you haven't done this before, and you currently have lost the Admin password, I bet you let out a sigh of relief after reading the previous paragraphs. But although it's possible and seemingly simple, there are a number of tasks to perform, as you'll see from the following steps.

  1. Create a temporary folder on your local machine.

  2. Copy the users.txt file, which is located in the main VSS folder, to a different folder. You might want to print it out as well. This file holds a list of all the users of the database.

  3. Run the Visual SourceSafe Administrator application to create a new database in the temporary folder you created in the first step. Select Tools ®Create Database.

  4. Run the DDCONV command-line utility on the temporary folder to upgrade the database to version 6. DDCONV is located in the win32 subfolder.

  5. Copy the um.dat file from the temporary folder to the SourceSafe data folder. Rename or delete the rights.dat and status.dat files located in the data directory.

  6. Run the Analyze command-line utility from the win32 subfolder with the -f switch.

  7. Using the Visual SourceSafe Administrator application, you must now add all the users to your new setup. The copy of the users.txt file or your printout from step 2 will be of help here. If you get an "Access denied..." or a "...directory already exists..." error, just ignore it by clicking OK.

That's all there is to it.

[4]This is also referred to as the command-prompt executable or command-line shell and is indicated in the environment variables as the ComSpec variable, which can be set from the System applet in the Control Panel. This is most often the Cmd.exe file that comes with the Windows operating system (Windows 2000 and later), but you might have a different third- party shell installed.

[5]Check out the properties of the menu item shortcuts to see which command-line switches are being used.


Using Visual SourceSafe

Now that we've covered how you administer your VSS setup, it's time to look at how you actually use VSS. We've split this information into two sections:

  • Daily VSS tasks, such as retrieving the latest version of a project item and updating the database with any changes you've made.

  • More advanced tasks, such as creating or adding a VS .NET project from a VSS project. The advanced section also has information about tasks you don't perform on a daily basis.

Daily VSS Tasks

In this section, we will look at the various VSS tasks you'll perform on a daily basis. These include retrieving data from a database and updating the data in the database.

Note

In order to perform any of the tasks described in this section, your development project must be under source control. See the "Add a Development Solution or Project to Source Control" section or "Creating a New Development Project from Source Control" section (under "Advanced Tasks") later in this chapter for information about how to put your development project under source control.

Retrieving Data

Your first task when working with source control (VSS, in this case) is to retrieve the data you want to work with, or to be more specific, to make sure you have the correct version of the project item you want to work with. In most cases, this means retrieving the latest version.

Although all tasks in this section can be performed from the Visual SourceSafe Explorer application, we will concentrate on showing you how to perform them from within the VS .NET IDE. So, to follow along, in the IDE, open a development project that is under VSS source control.

Checking Out Items

When you want to work on a project item, you must first check it out. This will mean that the project item is marked in the VSS database as checked out to you, and no one else can check it out, until you check it back in. This is one of the fundamental concepts of source control: prevent overwriting changes made by other users.

  • You can check out project items in three ways:

  • Right-click the item in the Solution Explorer and select Check Out from the pop-up menu.

  • Select the item in the Solution Explorer, and then select File ® Check Out <project item name>.

  • Select the item in the Solution Explorer, and then select File ®Source Control ® Check Out <project item name>.

Any of these methods bring up the Check Out dialog box, shown in Figure 11-29.

Click To expand
Figure 11-29: Check Out dialog box

In the Check Out dialog box, you can choose the project items to check out and also add comments. Adding comments is generally a good idea, especially if you'll be checking the items out for a longer period. If you never or rarely add comments when checking out items silently, you will benefit from checking out items, as described in the next section.

Tip

If you add a comment, make sure that it describes what action you'll be performing on the item. This gives anyone wanting to check out the item a chance to see what is going on, and it also might save you an angry e-mail or phone call from whoever wants to edit the item.

Checking Out Items Silently

If you rarely add comments when checking out project items, it's beneficial to check out items silently, which simply means that you're not prompted to add a comment to the check-out operation.

As explained earlier in the chapter, you can set the source control options in the IDE so that the menus display the silent check out command (through the General options under Source Control in the Options dialog box). Also, from within the Check Out dialog box (Figure 11-29), you can select the Display silent checkout command in menus option. Both of these methods will display the Check Out Now command in the pop-up menus that appear when you right-click an item under source control in the Solution Explorer. The Check Out Now command replaces the regular Check Out command.

If you want to check out an item and add a comment to it after you've changed the menus for silent check out, you need to select the item in Solution Explorer, and then select the Check Out <project item name> menu item from the File ®Source Control menu, which will offer both the silent and the standard check out commands, after you've enabled silent check out of items.

Click To expand

Note

If you perform a standard check out and leave the comment text box empty, this is the same operation as a silent check out. The silent check out option is offered simply to save you time; you won't need to click OK in a dialog box.
Undoing Check-out of Items

If you've checked out one or more items by mistake, and you don't want to save the changes you made, or you haven't made any changes and simply want it checked back in again, you can undo the check out. The Undo Checkout command will effectively roll back the check out.

Note

By default, checking in an unchanged item is the same as undoing a check out. This can be changed from the General tab of the Options dialog box in the Visual SourceSafe Explorer application or from the Advanced settings in the SourceSafe Options dialog box (see Figure 11-10 earlier in this chapter).

To undo a check out, right-click the checked-out item in the Solution Explorer and select Undo Checkout from the pop-up menu. Alternatively, select File ®Source Control ®Undo Checkout <project item name>. This brings up the Undo Checkout dialog box, shown in Figure 11-30.

Click To expand
Figure 11-30: Undo Checkout dialog box

The Undo Checkout dialog box gives you the option of canceling the undo checkout command, if you invoked the command in error, or to unselect any checked-out item that shouldn't be undone. This can be the case if you select several files in the Solution Explorer, prior to invoking the command. If so, all the selected files will be shown in the Undo Checkout dialog box. You can simply unselect the desired items before clicking the Undo Checkout button. This is quicker than closing the dialog box, selecting the correct items in the Solution Explorer, and then reinvoking Undo Checkout.

Getting the Latest Versions of Items

When you're working on a project with more than one developer, there are bound to be changes to project items that you rely on. This means that you somehow need to have the changed files copied to your machine. You could check out the items in question, but this will prevent anyone else from editing the items, which isn't what you want (unless you need to change them, of course). Instead, you can use the Get Latest Version command to transfer a copy of the latest checked-in version of the items to your machine.

When you want to get the latest version of a file, you have three options:

  • Select the desired item in the Solution Explorer, and then select File ®Get Latest Version of <project item>.

  • Select the desired item in the Solution Explorer, and then select File ®Source Control ® Get Latest Version of <project item>.

  • Right-click the desired item in the Solution Explorer and select Get Latest Version.

Whichever way you invoke the Get Latest Version command, the latest checked-in version is copied to your machine, and the operation output is dis played in the Output window (as discussed in the "Output Window" section earlier in this chapter).

Note

The Get Latest Version command can be used on any items, including checked-out items. If you try to get the latest checked-in version of a checked-out item, you're required to confirm or cancel the operation.

The Get Latest Version command is one that you will probably use often. In fact, many organizations require developers to get the latest version of all project items at least once a day, or even every time the development solution is opened. The latter is easily achieved without manually invoking the command every time. All you need to do is to select the Get everything when a solution is opened option in the VS. NET IDE Options dialog box (Figure 11-6), as described in the "Source Control Options" section earlier in this chapter.

Updating Data in the Database

When you check out items from VSS, you generally do so to make changes to them. After you have finished making changes to an item, and you've tested and verified that the changes work as intended, you should update the project in the VSS database with your changes, by checking in the item.

Checking In Items

You can check in project items in three ways:

  • Right-click the item in the Solution Explorer and select Check In from the pop-up menu.

  • Select the item in the Solution Explorer, and then select File ® Check In <project item name>.

  • Select the item in the Solution Explorer, and then select File ® Source Control ® Check In <project item name>.

When you select Check In, the Check In dialog box appears, as shown in Figure 11-31. In this dialog box, you can check in one or more project items and choose to add a comment to the project items being checked in. We recommend that you always add a comment, but make sure that it describes what action you have performed on the items. This gives anyone wanting to check out or get the latest version of the items a chance to see what has been changed.

Click To expand
Figure 11-31: Check In dialog box

If you never or rarely add comments when checking items in, you can choose to check in items silently, as described in the next section.

Checking in Items Silently

If you don't add a comment when checking in project items, it's quicker to use the check in silently command, which doesn't prompt you to add a comment to the check-in operation.

As with the check out silently command, you can change the menus to display the silent check in command by using the Source Control options in the VS .NET IDE Options dialog box (Figure 11-6), as described in the "Source Control Options" section earlier in this chapter. Alternatively, you can select the Display silent check in command in menus option in the Check In dialog box (Figure 11-31). Both of these methods will display the Check In Now command in the pop-up menus, replacing the Check In command, when you right-click an item under source control in the Solution Explorer.

Click To expand

If you want to check in an item and add a comment to it after you've changed the menus, you need to first select the item in Solution Explorer, and then select File ® Source Control ® Check In <project item name>.

Note

If you perform a standard check in and leave the comment text box empty, this is the same operation as a silent check in. The silent check in option is simply to save you time; you don't need to click OK in a dialog box.

Adding Items to a VSS Project

When you add a new item to a development project that is under source control, you also need to consider whether it should also be added to the VSS project. If your development project is under source control, the item is automatically added to the VSS project after it has been added to your development project. However, you can manually remove it, as described in the next section.

If an item has been manually removed from source control, or if you've otherwise managed to add an item to your project without automatically putting it under source control, it's rather simple to add it to your VSS project. Simply select the item in question in the Solution Explorer, and then select File ® Source Control. You'll see that the Exclude <project item name> from Source Control menu item is checked. Select that menu item to uncheck it.

Excluding Items from a VSS Project

Sometimes, you have items in your development project that you don't want to be under source control for the simple reason that they are your private files; they don't concern any of the other team members working on the same project. These items can be simple text files, test files, or any temporary files you work with. These files are specific to you and/or the machine on which you run the devel opment project. One such file is the output file, created when you compile and build your solution. In most cases, it doesn't make sense to include it as part of your VSS project. It's easier to have each team member compile and build the output file on his or her own machine. Checked-in items are marked read-only, which means that the item must be checked out in order to build the solution. This also means that only one team member can compile at any given time.

To remove an item from source control, select it in the Solution Explorer, and then select File ® Source Control ® Exclude <project item name> from Source Control. When an item in your development project isn't under source control, this Source Control menu item will be checked when the excluded item is selected in the Solution Explorer. In addition, the project item is marked with a different icon in the Solution Explorer.

Deleting and Destroying Items

When an item in your development project is obsolete, you generally remove it from the project or delete it. If the item is under source control, you also need to consider whether it should be deleted and destroyed from here as well. This is one of those actions you must perform in the Visual SourceSafe Explorer appli cation, rather than from within the VS .NET IDE.

To delete an item from the Visual SourceSafe Explorer application, first open the VSS database, expand the project tree view on the left, and select your project. Then right-click the item in question in the item pane on the right and select Delete. Alternatively, you can select the item in the item pane and press Delete or select File ® Delete. You'll see the Delete dialog box, as shown in Figure 11-32.

Click To expand
Figure 11-32: Delete dialog box of the Visual SourceSafe Explorer application

In the Delete dialog box, click OK to delete the item from source control. This doesn't remove the history and earlier versions of item, meaning that you can undo the deletion. If you really want to delete the item permanently, you must select the Destroy permanently option before you click OK. In either case, you're prompted to confirm the deletion/destruction of the item. The history is kept intact, whichever action you choose.

Caution

The destruction of an item is irreversible—not just the latest version, but also all stored versions of the item are destroyed!

Advanced Tasks

Now, we will look at the more advanced VSS tasks, as well as VSS tasks that you don't perform on a daily basis. These include connecting to a VSS database, adding projects or solutions to source control, removing a project from a database, allowing multiple checkouts, comparing and merging versions, and manipulating item versions.

Connecting to a VSS Database

In most smaller organizations, only one VSS database exists; larger organizations tend to have several databases. If you need to switch databases, you can do so from within the VS .NET IDE, as follows:

  1. Select Tools ®Options to open the Options dialog box.

  2. Expand the Source Control category, and select the SCC Provider subcategory.

  3. Click the Advanced button to open the Visual SourceSafe Login dialog box.

  4. Type in the user name and password assigned to you.

  5. Browse to the database, or type in the database path in the form \\MachineName\ShareName, unless it exists on the local machine, in which case you can use default path syntax, such as \Program Files\Microsoft Visual Studio\VSS.

  6. Click OK.

Adding a Development Solution or Project to Source Control

You may have an existing development solution or project, or you may have just created a new one, that isn't under source control. It's pretty simple to add the development project to a VSS database. First, you need to open the project in the VS .NET IDE. From there, you can either add the solution—meaning all projects within the solution—to source control or add one or more projects within the open solution to source control. The latter option is based on which projects are selected in the Solution Explorer. Both of these options are available on the File ®Source Control menu.

Click To expand

If you want to add the solution to source control, another method is to right- click any item in the Solution Explorer and select Add Solution to Source Control from the pop-up menu.

Choosing one of these menu items brings up the Add to SourceSafe Project dialog box, with the solution name added to the Project text box, as shown in Figure 11-33. You can't really tell from the dialog box whether you chose to add a solution or a project, or can you? Actually, you can. As you can see from the Project text box, a .root extension has been added to the name of the solution, which is WindowsApplication2. If you add a project, this extension is not added to the name of the project.

Click To expand
Figure 11-33: Add to SourceSafe Project dialog box

In the Add to SourceSafe Project dialog box, you can choose in which SourceSafe project you want to put your development. You simply expand the tree to the node that represents the SourceSafe project. If the SourceSafe project doesn't exist, or if you want to create a new project under an existing project, type the name of the project in the Project text box, and then click Create. If the default name suggested by VSS (WindowsApplication2.root in Figure 11-33) is the one you want to use, you don't need to click Create. Simply select the VSS project and click OK. If the project named in the Project text box doesn't exist in the selected VSS project, you'll be prompted to have it created.

Creating a New Development Project from Source Control

If an existing project already exists in a VSS database, you can create a new devel opment project from it. To do so, select File ® Source Control ® Open From Source Control. This menu item is always shown, whether or not a solution is open in the VS .NET IDE. This command brings up the Create local project from SourceSafe dialog box, as shown in Figure 11-34.

Click To expand
Figure 11-34: Create local project from SourceSafe dialog box

In this dialog box, you can select an existing VSS project and create a devel opment project from it. Once you've selected the VSS project, you must specify a local folder in which to store the items— the VSS working folder—in the Create a new project in the folder text box. When you're ready to create the development project, simply select OK. The new project will be created, and you can manip ulate it in the same way as any other development project under source control.

Note

If an existing project by the same name exists in the working folder you suggest in the Create local project from SourceSafe dialog box, you'll be prompted to overwrite it.

If you already have a solution to which you want to add a project from VSS, you can do this as described in the next section.

Adding an Existing Project from Source Control

When working with enterprise projects or solutions, you may have a solution to which you need to add another existing development project. If this project isn't under source control, you simply add it to your project using the VS .NET com mands. However, if it exists in VSS, you need to add it from there, even if you have direct access to the project.

To add a project from source control to an existing solution, open your solution in VS .NET, and then select File ®Source Control ® Add Project From Source Control. This brings up the Create local project from SourceSafe dialog box (Figure 11-34). Wait a minute—isn't that the exact same dialog box that's used when creating a new development project from source control? It sure is, and the only real difference is that the existing solution files for the VSS projects are manipulated after the project has been copied to your local machine. This means that the appropriate source control entries and tags are inserted into solution files.

Select the VSS project and specify a local folder to be used as the VSS working folder in the Create a new project in the folder text box. When you select OK, the project is added to your existing solution.

Removing a Project from a Database

If you need to remove your project from the VSS database, you can do this from within the VS .NET IDE. However, let's first consider why you want to remove it:

  • You're moving the project to a different VSS database.

  • The project is obsolete and needs archiving.

  • You're the only developer on the project and you don't need versioning.

Sure, there are other possible reasons for wanting to remove the project, but we'll keep it simple for now. The point is that if you're moving or archiving a project, you should be using the archive and restore facilities of the Visual SourceSafe Administration application, as described in the "Archiving Databases and Projects" and "Restoring Databases and Projects" sections earlier in this chapter, not simply deleting the project. (The third reason listed for removing it is somewhat silly, but we've seen that reasoning, so we decided to include it.)

However, if you need to remove the project from the VSS database, or rather if you want to unbind the project from VSS, open the solution containing the project in the VS .NET IDE, and then select File ® Source Control ® Change Source Control to open the Change Source Control dialog box, as shown in Figure 11-35.

Click To expand
Figure 11-35: Change Source Control dialog box

In the Change Source Control dialog box, make sure you have selected the solution and the project on the list, and then click the Unbind button. You're prompted to confirm this action.

Realize that this doesn't delete the project from the VSS database; it only unbinds your local project from the database. So, if any other developer needed to keep working with the VSS version, that would still be possible. You, on the other hand, have removed any association between the local project and the VSS project.

If your desired action is to remove the project completely from the VSS database, you need to use the Visual SourceSafe Explorer application. Just right- click the project you want to delete, and then select Delete from the pop-up menu. The Delete dialog box also has a Destroy permanently option. If you select this option, the project will be removed without the possibility of recovery later. So, be careful what you do at this stage. Click OK to continue, and you'll be prompted to confirm the deletion/destruction of the project, any subprojects, and all items in the project.

Allowing Multiple Checkouts

Although it's not normally desirable to have more than one person check out an item, you can choose to allow this. For example, two people may need to work on the same item but on different parts.

To allow multiple checkouts, in the Visual SourceSafe Administrator appli cation, select Tools ®Options to open the SourceSafe Options dialog box. On the General tab of the SourceSafe Options dialog box, select the Allow multiple checkouts option, as shown in Figure 11-36. Be aware that this setting is valid for all projects and items in the VSS database you're logged in to. Note that this only applies to text files and not binary files, because they cannot be merged if potential conflicts arise.

Click To expand
Figure 11-36: General tab of the SourceSafe Options dialog box

Comparing Item Versions

You may need to compare two different versions of a project item. This is useful when an item has been checked out to two or more team members. The version of the item you check in may be different from the currently checked-in version. Well, it's different because you made changes to it, but the checked-in version might contain modifications that aren't reflected in your version. This means that you now have two different versions that need merging, which is covered in the next section. You can compare (and merge) text files but not binary files, such as .dll, .exe, or Word files.

When you have more than one version of a project item, you can compare these versions, but it is also possible to compare items under source control to files on disk.

Tip

Because you can compare source control items to files on disk, you have a chance of comparing an existing source control item to a local version you have on disk. This saves you the hassle of checking in the local version just to do a comparison, although you eventually might decide to merge the two items and/or check in the local version.

To compare an item, right-click it in the Solution Explorer in the VS .NET IDE and select Compare Versions from the pop-up menu. Alternatively, you can select the item in the Solution Explorer, and then select File ® Source Control ®Compare Versions. This brings up the Difference Options dialog box, as shown in Figure 11-37.

Click To expand
Figure 11-37: Difference Options dialog box

In the Difference Options dialog box, the items to compare are specified in the Compare and To text fields. By default, the checked-in version of the item appears in the Compare text field and the local version appears in the To field. If you need to compare other versions or files or items, click the Browse button next to the text fields, and select whether you want to specify a file on disk or an item in the current VSS database. (If you need to compare an entire project, in the Difference Options dialog box for one of the items in the project, click the Project button to bring up the Project Differences dialog box.)

If the files being compared aren't different, you will see the message, "The files are identical." Otherwise, the Differences dialog box appears, as shown in Figure 11-38.

Click To expand
Figure 11-38: Differences dialog box

In the Differences dialog box, you can see the two items compared, with the version specified in the Compare text field in the left pane and the version specified in the To text field in the right pane. The lines that are changed are color-coded, with blue for deleted lines, red for modified lines, and green for inserted lines.

Modified lines, which are marked in red, include lines where one or more char acters have been deleted or inserted. The blue marking is used only when entire lines of text have been deleted, and the green marking appears when full lines of new text have been inserted.

You can navigate the compared items (useful for large files) using the various buttons on the toolbar, which includes the following buttons:

  • Find, Find Next, and Find Previous buttons for searching for specific text

  • Toggle Bookmark, Next Bookmark, Previous Bookmark, and Clear All Bookmarks buttons for manipulating bookmarks in line with the ones you have in the code editor of VS .NET

  • Previous Difference and Next Difference buttons for jumping back and forth between the detected changes

    Note

    You cannot make changes to the items in the Differences dialog box. You can only view the detected differences.

If you want to compare different versions of an item already in the VSS database, you need to use the history functionality, as described in the "Viewing Item History" section later in this chapter.

Merging Item Versions

After you've compared different versions of a project item, as described in the previous section, you may want to merge the two versions into one. As with com parisons, merges are possible for only text files.

Tip

If you really need to merge different version of Word documents, Word has its own merge facilities. In fact, Word 2003 and Microsoft Office 2003 have their own versioning system, which is also used by Microsoft SharePoint Portal Server. See your Microsoft Office documentation for more information.

VSS have some automatic merging facilities that are invoked when you check in an item that has been modified in the VSS database after you checked the item out. In some cases, VSS handles minor changes automatically and merges the changes from the checked-in item with the checked-out item. This is done in memory, and the message shown in Figure 11-39 appears.

Click To expand
Figure 11-39: Automatic item merge message

This standard merge warning displayed by VSS provides the following options:

  • The Yes and Yes All buttons will check in the merged items, and local files will be updated, so they are the same as the items checked in.

  • The No and No All buttons will update the local files as with the automatically merged items, but the items in the VSS database are left unchanged.

  • The Cancel button will cancel the check-in operation, and the items in the VSS database and the local files are left unchanged, meaning the automatic merge changes are not applied to any of the items or files.

In case VSS can't merge the two items versions automatically, such as when different changes have been made to the same lines, you're prompted to merge these changes manually using the Merge SourceSafe version into Local version dialog box, shown in Figure 11-40.

Click To expand
Figure 11-40: Merge SourceSafe version into Local version dialog box

As with the Differences dialog box used for comparing different versions of an item, changes to the two versions are marked in three different colors:

  • Blue is used for marking lines that have been deleted in either or both of the two versions. This can be handled automatically, and it's not treated as a conflict.

  • Red is used for marking conflicts, meaning where different changes have been applied to the same lines in the two versions. These kinds of changes are treated as conflicts and must be handled manually.

  • Green is used for marking lines that have been inserted in either or both of the two versions. This can be handled automatically, and it's not treated as a conflict.

As you can probably guess, only conflicts need to be resolved. In Figure 11-40, there's a conflict on Line 50 (SourceSafe version), where the two versions have different values for the Text property of the Form1 form. In the merged pane at the bottom, you can see the original value of this property Form1, which has been changed to Form2 in the checked-in version and Main Form in the local version.

Now, you need to resolve this conflict. You can click the change in the appro priate pane, and the change is applied to the Merged version pane. You can also use the Previous Conflict and Next Conflict toolbar buttons to locate all conflicts in the two versions. Once all conflicts have been resolved, you can click the Save button on the toolbar, and then close the Merge SourceSafe version into Local version dialog box. You're then required to confirm that all conflicts have been resolved, after which the local version is updated with the changes. However, you need to perform the check-in operation once more to update the VSS database with the changes.

Manipulating Item Versions

In the VSS database, you normally have a number of versions of the same item. This means that you can actually go back and view the content of previous versions of an item, which is handy in case a team member has modified or deleted some thing that should not have been modified or deleted. Because different versions are stored, you can recover previous versions of an item in different ways, as explained in the following sections.

Viewing Item History

You can view the history for a specific item by selecting it in the Solution Explorer of the VS .NET IDE and selecting File ® Source Control ® History. This brings up the History Options dialog box, as shown in Figure 11-41.

Click To expand
Figure 11-41: History Options dialog box

The History Options dialog box, which is similar to the Difference Options dialog box for comparing versions, can be used to filter out a specific version of the selected item. You can specify dates in the To and From text fields; remember to use the local date format used on the system. In the User text field, you can specify the name of a user. The user name you enter must be exactly as it appears in the VSS database; otherwise, the versions won't be located. You can't use wild- cards in a user name, so you can't locate all versions of an item that users with names beginning with John have modified, for example. Click OK to see the item versions that satisfy the filter criteria. If no versions of the selected item match the criteria, the "There are no items in the list." message is shown. Otherwise, the History dialog box appears, as shown in Figure 11-42.

Click To expand
Figure 11-42: History dialog box

Some of the buttons on the right side of the History dialog box are self- explanatory. Here is what the less obvious ones do:

  • View: This button is used for viewing the selected version in an editor/viewer of your choice.

  • Details: This button opens the History Details dialog box, which shows the various details, such as version number, user name, checked-in date, and comment.

  • Get: This button retrieves the selected version and overwrites the existing local version. Be careful, because you're not prompted about overwriting the existing local version.

  • Check Out: This button is used for checking out the selected version. Be careful, because you're not prompted about overwriting the existing local version.

  • Diff: This button opens the Difference Options dialog box (Figure 11-37), as discussed in the "Comparing Item Versions" section earlier in this chapter. The difference is that from here, you can compare different versions stored in the VSS database.

  • Pin: This button is used for pinning/unpinning an item version. In general pinning is used for locking a specific item version so that this version becomes the version used in your project. It is not possible to make changes to a pinned item.

  • Rollback: This button will roll back any changes made after the selected version. Although you're required to confirm this action, it cannot be undone, so be careful.

Removing Solution and Project Files from VSS Source Control

If you have a solution or a project that was under source control and the link to the VSS database is broken, you have a problem in that you can't remove this link using VS .NET or VSS. This can happen, for instance, when a less fortunate team member accidentally deletes the project from source control.

Fortunately, there's a simple fix for this, which involves some manual cleaning up of your solution and/or project files. However, if you want the solution and/or project added to the source control after you've performed the manual cleaning up of the files, you'll most likely lose all item versioning and project history. We specifically state "most likely," because it might be possible to add the solution and/or project to the VSS project, if it still exists. In that case, you might be able to simply move the project from one VSS database to another.

Here is the procedure for fully removing a solution and project from VSS source control:

Caution

This procedure may not work for you. Make sure to back up your solution before attempting this operation.

  1. Delete the following files from your solution or project folder and any project folders in this folder: *.scc, * .vspscc, and *.vssscc.

  2. Select all remaining files and folders in the solution or project folder, and remove the read-only attribute from the selected files and folders. VSS uses the read-only attribute for items that are checked in, so you need to remove this attribute before editing any files. Keep in mind that some projects may be located outside the parent solution folder. This is nearly always true for Web projects, which are usually located in the Inetpub\wwwroot folder.

  3. If you want to remove a solution file from VSS source control, edit the solution file (.sln) in a plain text editor like Notepad. Remove the SourceCodeControl GlobalSection section. Remove from and including this line:

    GlobalSection(SourceCodeControl) = preSolution

    to and including this line:

    EndGlobalSection

  4. Edit any project files (.vbproj or .csproj) in a plain text editor. Remove these four lines, which are located at the top of the project file in either the VisualBasic or CSHARP node:

    SccProjectName = "SAK"
SccLocalPath = "SAK"
SccAuxPath = "SAK"
SccProvider = "SAK"

  5. If you have enterprise template project files (.eto), they also must be edited, remove the SourceControlSettings node including content, from the start tag <SourceControlSettings> to the end tag </SourceControlSettings>.

That's all you need to do. Your solution and project are now fully removed from VSS source control.

Start Sidebar
Visual SourceSafe Extras

VSS has some shortcomings. One of the major weaknesses of VSS is accessing a server on a remote network with no direct access.[6] Another weakness is that you cannot use Windows user authentication. However, an advantage of VSS is that there are many third-party products that work with VSS. Microsoft has included some recommendations on the Microsoft VSS web site, at http://msdn.microsoft.com/ssafe/downloads/ addon.asp.

One of the tools recommended by Microsoft is SourceOffSite (http://www.sourcegear.com/sos/index.asp) by SourceGear Corporation. This excellent tool has been around for nearly as long as SourceSafe, and it's used for accessing a VSS database on a remote network. We've had the pleasure of working with SourceOffSite (Classic) in a number of different companies, and today SourceOffSite Classic is an integral part of our own development setup. Versions 3.5.3 and 4.0 also integrate seamlessly into the VS .NET IDE. Although there are other tools that have SourceOffSite's functionality, we warmly recommend SourceOffSite Classic.

End Sidebar

[6]No direct access, in this case, means accessing the VSS database on a different network, across a WAN like the Internet.


Best Practices for Using Source Control

In this section, we'll give you some advice, based on our practical experience with source control. There is also plenty of good advice on the Microsoft VSS site, at http://msdn.microsoft.com/library/?url=/library/en-us/dnvss/html/vssbest.asp?frame=true.

The best practices provided here are some we feel rather strongly about, and although some of them do add a little extra time when performing your daily routines, you should consider applying them.

Check In Frequently

If you check in frequently, you minimize the amount of code that can't be checked in at the end of the day because of unfinished items. When you've fixed a bug or finished a new procedure and tested it, check it in, even if you have a few more things to do, before finishing the scheduled work. This way, you make sure that the other team members have access to your fixes and new features relatively quickly, as compared to checking in less frequently, such as once a day.

This way, every version checked in contains only one or more changes, all relating to the same problem. This helps when you want to go back to a previous version of a particular project item, because the changes are easily isolated. It also makes commenting the check-in a lot easier.

Don't Check In Unfinished Items

You should never check in unfinished items. We know that it sounds like some thing obvious, but you would be surprised how many developers actually do it. The problem with checking in unfinished items is that other people will get this version on their setup, and it might not compile, or it might have runtime errors that can be costly to track down for the other team members.

Say you're going on vacation, and you have an unfinished item. What should you do? Well, if you follow our advice to check in frequently, you won't have that many changes you need to finish. So, you can make a copy of the items you haven't checked in, and then undo the check-out, so that others can work on the items while you're gone. When you come back, check out the items, add your changes, and finish them before you check in. You might need to use the VSS compare and merge facilities for this purpose, as described earlier in this chapter.

Comment All Item Check-ins

When you check in an item, make sure you comment the changes you've made. It's extremely valuable to have the comments when a problem occurs and you need to find a previous version.

In some cases, you can search by date, but if not, it's good to be able to search for specific words, such as the name of the procedure that was changed. Along with procedure names, your comments can include references to variables, modules, and UI element. Reference them in short sentences, like these:

  • Renamed addButton to insertButton.

  • Changed caption of insertButton to "Insert."

  • Added logonName variable to DisplayUserInfo procedure.

  • Moved DisplayUserInfo procedure from Utils module to User class.

At least one sentence for a comment is a rule of thumb. You'll want your comments to be brief enough that you can type them in quickly, in a minute or two. If you check in often, it's easy to comment a change with just a few words. If you check in less frequently, it can be quite hard to add a meaningful comment to the revisions made.

You shouldn't mention Author, Date, or File Name in your comments, because they're automatically part of properties for the checked-in items.

Establish a User Naming Convention

When you add users to a SourceSafe database, you shouldn't use the same password as the user uses for network login. The reason for this is that you shouldn't really know the network password for any user, except your own and perhaps the administrator's. In addition, because there are tools out there that can read the user ID and password combinations in VSS, anyone using such a tool might be able to access the network.

In the General tab of the SourceSafe Options dialog box of the Visual SourceSafe Administrator application (see Figure 11-36), there's an option that might prompt you to use the same user ID as the network login: Use network name for automatic user log in. If this option is selected, the Visual SourceSafe Login dialog box will display the network login name in the Username text box, leaving just the password to be filled in.

Validate Database Integrity Frequently

The VSS database is known for being somewhat unstable, so it's a good idea to validate the database integrity frequently, which means at least once a week. In general, this is something you should do at night, or whenever all of the users are logged off the VSS database. You use the Analyze command-line utility for this purpose, as described in the "Validating Database Integrity" section earlier in this chapter.

Although it's best to validate the database when all users are logged off the database, you can actually run the validation with one or more users logged on by specifying the –x command-line switch/option. This will prevent the Analyze utility from locking the database, and it can be used to test the database integrity without fixing any problems.

You can ask your system administrator to set up a schedule for database val idation. All the administrator needs to know is the command-line syntax, and he or she can set up the Windows Scheduler to run the validation at the specified dates and times.


Summary

In this chapter, you've seen how you can use VSS to lock and effectively control access to your source code and related documents.

Although VSS has some shortcomings, it's more than an adequate tool. However, there are many other source control tools out there. We suggest that you talk to your colleagues about their experience with source control tools and what they might recommend, or alternatively do a search on the Internet for source control tools.

Although we recommend VSS for source control with VS .NET, we also recommend that Microsoft use a different file system approach than the current one. We think that using a SQL Server database is a much better approach.[7]

The next chapter discusses how to use VEA 2003 for modeling your software solutions and database schema.

[7]What do you think? We would love to hear your opinions on this one, and you can reach us at carstent@dotnetservices.biz.


Chapter 12: Visio for Enterprise Architects 2003

Overview

This chapter describes the core functionality of Visio for Enterprise Architects 2003 (VEA 2003). In this chapter, we'll focus on the VEA's code generation, error checking, and reporting functions. You've learned about some of this functionality in previous chapters. You can consider this chapter as a summary or a brush-up on the core VEA functionality.

In this book, we don't cover Visio as a product, but merely as a tool for UML modeling. UML is the de facto standard in software modeling, but VEA is not. This is why we advise you to focus on UML instead of the tool (VEA) when you are modeling your enterprise solutions. Still, VEA is an excellent choice for .NET developers, because VEA targets the Windows platform only and focuses on .NET, and—best of all—it comes as part of the VS .NET Enterprise Architect (VSEA) edition. (Remember that VEA only comes with VSEA.)

Note

As noted in Chapter 1, there are various editions of Visio, but only VEA 2003 has the UML add-on that allows code generation, reverse engineering, and forward engineering from UML diagrams. For information about the various editions of Visio, see http://www.microsoft.com/office/visio/prodinfo/ editions.mspx and http://www.microsoft.com/office/ visio/prodinfo/compare.mspx.


Generating Automatic Code and UML Models

VEA can generate code from your UML models and create UML documentation from your VS .NET solutions. These processes are referred to as forward engineering and reverse engineering, and we cover both in the following sections.

Note

Many other tools, such as IBM Rational Rose and IBM Rational XDE, can also do round-trip engineering, a process that can update your code and UML documentation automatically once you've started your project; that is, once you're beyond the initial setup. VEA can't do round-trip engineering. You can find more information about IBM Rational Rose and IBM Rational XDE, as well as a comparison of VEA and IBM Rational XDE, in Chapters 18 and 19.

Forward Engineering

In VEA, you can automatically generate a code skeleton from your UML diagrams (static structure diagrams). This is extremely effective, because you get some of your work done automatically and it reduces the chances for errors at this stage. You've seen this in action several times in Chapter 5.

To forward-engineer code (generate code from your diagram), select UML ®Code ® Generate. This brings up the Generate dialog box, as shown in Figure 12-1.

Click To expand
Figure 12-1: Generate dialog box

In the Generate dialog box, you can select the target language and which classes to generate, but your most important decision is whether to add the gen erated code to a Visual Studio project or generate stand-alone code files. In most cases, you'll want to add the code to a VS .NET project. However, sometimes you may want to generate stand-alone code files, such as when you just need the class file to pass to someone else for inclusion in his or her project.

If you want to add the generated code to a Visual Studio project, you can specify which type of Visual Studio project you want to generate. Visual Studio then creates a new solution with all the files necessary for that solution type. As you can see from Figure 12-1, you can choose from several templates. The available templates vary, depending on which programming language you select from the Target language list.

Note

Although VEA uses Visual Studio to create a new solution file containing the new project, VEA cannot specify that multiple projects within a solution should be generated. If you have multiple models and packages in a VEA document and try generating code, all classes will be added to the same VS .NET project within the solution.

In Figure 12-2, you can see code generated and added to a Visual Studio project, using the Empty Project template. The generated TopPackage solution has been opened in the VS .NET IDE, and the Customer class (Customer.vb) is shown in the code editor.

Click To expand
Figure 12-2: Generated code added to a Visual Studio project, using the Empty Project template
Note

Depending on the amount of code to generate and the performance of your machine, you'll see that the VS .NET IDE is opened (using OLE) for creating the project for the generated code. This is why any errors that occur during the code generation are handled by VS .NET, rather than by VEA.

In Exercise 12-1, you'll generate code and add it to a Visual Studio project. Rather than choosing the Empty Project template (as in Figure 12-2), you'll choose to add it to the Windows Application template.

Note

All of the sample code for this book is available from the Downloads section of the Apress Web site (www.apress.com).

Exercise 12-1
Start example

  1. Open the Exercises 5-10 to 5-11.vsd file located in the Chapter 05 folder of the accompanying sample files.

  2. Select UML ® Code ® Generate to open the Generate dialog box (Figure 12-1).

  3. Select the Add Classes to Visual Studio Project option.

  4. Select the Windows Application template.

  5. Name the project TopPackage1 and set the location to \EDWVSNETUMLMSF\Chapter 12.

  6. Click OK.

  7. Open the TopPackage.sln solution file in VS .NET. Your VS .NET IDE should look like Figure 12-3.

    Click To expand
    Figure 12-3: Generated code added to a Visual Studio project using the Windows Application template

End example

Figure 12-3 shows the VEA generated code (VIPCustomer.vb file) added to a new Visual Studio Windows Application project. As you can see, the TopPackage1 project has been added to the existing TopPackage.sln solution. Why is that? Well, if you look at Figure 12-1, you can see that you can specify both the solution and project names. This means that if you set the location to an existing folder con taining a solution file of the same name as the one you specify in the Generate dialog box, the project is added to the existing solution; the solution file won't be overwritten.[1]

Okay, so now you know how to add a project to an existing solution, but what about adding one or more classes to an existing project? This is fairly simple, and it's similar to how you add to an existing solution: You set the location to an existing folder with a project of the same name as the project name in the Generate dialog box (see Figure 12-1). In Exercise 12-2, you'll add a class to the TopPackage1 project you worked with in Exercise 12-1.

Exercise 12-2
Start example

  1. Open the Exercise 12-2.vsd file located in the Chapter 12 folder of the accompanying sample files.

  2. Add a new class to the MyClassDiagram diagram, named Test.

  3. Open the Generate dialog box.

  4. Select the Add Classes to Visual Studio Project option.

  5. Select the Windows Application template.

  6. Name the project TopPackage1 and set the location to \EDWVSNETUMLMSF\Chapter 12.

  7. Select the Test class. Then click OK.

  8. You'll be prompted to verify that you want to add the selected classes to the existing project (if you followed Exercise 12-1). Select Yes.

    Click To expand

  9. Open the TopPackage.sln solution file in VS .NET. You will see the selected class has been generated and added to the existing project, as shown in Figure 12-4.

    Click To expand
    Figure 12-4: Test class added to the TopPackage1 project of the TopPackage solution

End example

In Figure 12-4, you can see the Test class has been added to the TopPackage1 project.

As you saw in Exercise 12-2, when you select to add a class and choose an existing project, you'll see the UML Code Generation dialog box asking if you want to add the files selected in the Generate dialog box to that existing project. If you click No, the code generation is canceled, but the only evidence of the cancel lation is shown in the Code pane of the Output window, as shown in Figure 12-5.

Click To expand
Figure 12-5: Code-generation cancellation shown in the Code pane of the Output window

Reverse Engineering

Reverse engineering simply means that you can generate a UML model from existing code, and in our case, that means a Visual Studio project. This is useful if you want to document a solution and don't have any UML models; for example, when you have an existing solution for which you have no documentation. In addition, it's useful for upgrading an existing solution, because you can first doc ument the existing solution.

Reverse engineering takes place directly from the Visual Studio IDE. If, for example, you open the sample application named Duwamish, located in the \Program Files\Microsoft Visual Studio .NET 2003\Enterprise Samples\ Duwamish 7.0 VB folder, you can reverse-engineer this project into UML.

Note

Be sure to read the Readme.htm file located in the sample's folder before you install and open the sample application. If you haven't installed the application yet, a Windows Installer file (Duwamish.msi) is located in the folder, and it can be run by double- clicking it from Windows Explorer. You can find more information about the Windows Installer and Windows Installer files in Chapter 15, which covers deployment. If you need to install the sample project, make sure you read the notes and warnings in the dialog boxes when installing.

In Figure 12-6, you can see the Solution Explorer with the Duwamish 7.0 VB sample application. The solution consists of six projects, such as a Web project containing the solution front end (a bunch of ASP.NET pages). Another project is DataAccess, which contains the VB .NET classes used for the data access.

Click To expand
Figure 12-6: Duwamish 7.0 VB sample application in the Solution Explorer

If you highlight the DataAccess project in the Solution Explorer (as shown in Figure 12-6), you can generate a UML model for this specific project by selecting Project ® Visio UML ® Reverse Engineer. You'll try this in Exercise 12-3.

Exercise 12-3
Start example

  1. Open the Duwamish 7.0 VB sample application (located in the \Program Files\Microsoft Visual Studio .NET 2003\Enterprise Samples\ Duwamish 7.0 VB folder) in VS .NET.

  2. Select the DataAccess project in the Solution Explorer (see Figure 12-6).

  3. Select Project ® Visio UML ® Reverse Engineer.

  4. Save the UML model as Duwamish-DataAccess.vsd in the C:\EDWVSNETUMLMSF\Chapter 12 folder (using the Select Visio UML File dialog box). The Visio file is added to the Duwamish solution, as shown in Figure 12-7, and the UML model is opened in VEA, as shown in Figure 12-8.

    Click To expand
    Figure 12-7: Duwamish-DataAccess.vsd added to the duwamish solution

    Click To expand
    Figure 12-8: VEA with the reverse-engineered DataAccess project

End example

In Figure 12-7, you can see how the new Visio file is added to the Duwamish solution in the Solution Items folder. In Figure 12-8, you can see the Model Explorer in VEA for the reverse-engineered DataAccess project. The DataAccess project is modeled as a subsystem, because it's a project, and therefore contains everything for the project. A subsystem in UML is illustrated by a red package.

All the classes in the DataAccess project have been reverse-engineered as classes in the UML model and placed in the DataAccess package, but as you can see from Figure 12-8, they haven't been placed on a diagram. To add a class to a diagram, you just need to drag it onto the diagram, as shown in the example in Figure 12-9. In the example, the Books class has been dragged onto a static structure diagram. You can see that all of the operations and attributes of the Book class have been reverse-engineered along with the parameters and data types.

Click To expand
Figure 12-9: Reverse-engineered Books class on a static structure diagram

Besides the classes under the DataAccess package, some classes also exist under the External Classes package. The classes placed here are the classes whose references cannot be resolved. This happens if the project (or solution) hasn't been built before you reverse-engineer it.

So, what happens if the reverse engineering takes place after the project has been built? Follow Exercise 12-4 to get the answer.

Exercise 12-4
Start example

  1. Close the Duwamish-DataAccess.vsd UML model.

  2. Open the Duwamish 7.0 VB sample application in VS .NET (if isn't already open).

  3. Select the DataAccess project in the Solution Explorer (see Figure 12-6).

  4. Build the DataAccess project.

  5. Select Project ® Visio UML ® Reverse Engineer.

  6. Save the UML model as Duwamish-DataAccess.vsd in the \EDWVSNETUMLMSF\Chapter 12 folder (using the Select Visio UML File dialog box).

  7. Overwrite the existing Duwamish-DataAccess.vsd document (created in Exercise 12-3). As in Exercise 12-3, the Visio file is added to the Duwamish solution (as in Figure 12-7), and the UML model is now opened in VEA (as in Figure 12-8). It seems the result is the same…

End example

As demonstrated in Exercise 12-4, it appears that the result is the same if the reverse engineering takes place after the project has been built. It's true that the result isn't any more positive, because you still have irresolvable classes placed in the External Classes package. However, this time it's not because the project hasn't been built, but simply because the classes referred to don't exist in the DataAccess project, which is the only project being reverse-engineered.

Tip

Always build your solution before reverse engineering the solution or single projects. This way, you can easily tell that classes placed under the External Classes package aren't available in the project (or solution).

To solve the problem with the external classes, you need to reverse-engineer the entire solution, because this is the only way that VEA can reference classes placed in other projects. You'll do this in Exercise 12-5.

Exercise 12-5
Start example

  1. Close the Duwamish-DataAccess.vsd UML model.

  2. Open the Duwamish 7.0 VB sample application in VS .NET (if it's not already open).

  3. Select the Duwamish solution in the Solution Explorer.

  4. Build the solution.

  5. Select Project ® Visio UML ® Reverse Engineer.

  6. Save the UML model as Duwamish.vsd in the \EDWVSNETUMLMSF\ Chapter 12 folder. As in Exercises 12-3 and 12-4, the Visio file is added to the Duwamish solution (as in Figure 12-7), and the UML model is now opened in VEA. The full reverse-engineered solution is shown in Figure 12-10.

    Figure 12-10: VEA Model Explorer with the complete Duwamish 7.0 VB sample application

End example

In Figure 12-10, you can see that after an entire solution has been reverse- engineered, there are no classes in the External Classes package. In fact, the External Classes package doesn't exist, because all classes are now grouped in the Top Package package.

Reverse engineering is not just a way of documenting an existing solution; it's also a great way to learn how to model specific issues you come across. If you don't know how to model something, create it in Visual Studio and see how it looks in UML by reverse-engineering it.

[1] We think this is a good thing, but we also think that you should at least have the option of overwriting the existing solution file, possibly by means of a warning message with the two options when you click OK in the Generate dialog box.


Error Checking in VEA

VEA provides you with comprehensive help in checking your model for errors on the fly. VEA differentiates between two kinds of errors and error checking:

  • Semantic errors

  • Programmatic errors

We'll look at both types of errors in the following sections.

Semantic Errors

Semantic errors are the notation errors in your model. If your UML model doesn't conform to the UML 1.2 notation[2] and standard, you'll have semantic errors. This can happen, for example, if you've forgotten some information, given two elements the same name, or drawn an association between two elements that can't be connected.

In Exercise 12-6, you'll create a model that contains semantic errors to see how they are marked.

Exercise 12-6
Start example

  1. Open VEA (if it's not already open).

  2. Create a new UML model.

  3. Drag a Class shape onto the diagram and name it Customer.

  4. Drag a second Class shape onto the diagram and name it Customer as well.

  5. Drag a Class shape onto the diagram and name it Order.

  6. Drag a Package shape onto the diagram.

  7. Create a binary association between the Customer class and the Package1 package.

  8. Create a binary association between the Customer and Order classes.

  9. If the Output window isn't displayed, choose UML ® View ® Output to show it. In the Output window, display the Errors pane. Your static structure diagram should look like Figure 12-11.

    Click To expand
    Figure 12-11: Semantic errors in a static structure diagram

    Note

    Your diagram might display the end names for the associations. This doesn't have any effect on the semantic errors, so just leave them if that's the case.
End example

As you can see in Figure 12-11, semantic errors related to your model are shown in the Errors pane of the Output window. In Figure 12-11, the semantic error was caused by the creation of two classes with the same name within the same namespace. Elements with semantic errors are displayed with a thick, red marking. If you double-click a semantic error in the Output window, the corre sponding element will receive the focus in the Model Explorer and on the diagram as well.

Note

If you delete an element in order to eliminate an error, keep in mind that deleting an element from the diagram doesn't remove it from the model. You'll need to delete it from the Model Explorer. This isn't a Visio-ism, but generally applies to most UML tools. In Visio, you can change an option to be prompted to delete an element from the model as well when you remove it from a diagram. This is done from the UML Add-on tab of the UML Options dialog box (opened by selecting UML ® Options), where you can select the option Prompt for model element(s) delete on delete of shape(s).

You can turn on and off semantic error checking by selecting UML ® Options and selecting the Check semantic errors on UML model element option on the UML Add-on page. Another option relating to semantic errors, Relax semantic error checking, is on the UML Document page. This option is selected by default, but if you deselect it, you can apply full UML 1.2 specification compliance to your models.

Programmatic Errors

Programmatic errors are the errors that don't violate the UML 1.2 standard but might cause errors in the generated code. For example, if you select a C# unsigned integer as the return type for an operation for which you want to generate VB. NET code, this will cause a programmatic error in your generated code, because VB doesn't support unsigned data types.

To check if your model contains programmatic errors, select UML ® Code®Check. Any programmatic errors will be shown in the Code pane of the Output window (select Code from the list at the top of the Output window), as shown in Figure 12-12. Note that the Visio element in the diagram is not marked in red, as it is with semantic errors.

Click To expand
Figure 12-12: Programmatic error caused by an unsigned integer in VB .NET code

If you disregard the programmatic error, you can still generate the code, but it will look like the code generated in Figure 12-13.

Click To expand
Figure 12-13: Code preview for an element with a programmatic error

[2] The use case creation is a bit different in UML 1.2 than in UML 1.4 and later. However, class diagrams, which this book focuses on, are basically identical in the two versions.


Using Code Templates

You've seen how VEA automatically can generate code from your UML diagrams (the static structure diagram, that is). You've learned that code can be generated for the VB .NET, C#, or C++ programming languages. VEA generates code by mapping the UML elements to the programming code constructs of the target language you select. In Chapter 5, you saw how the mapping between UML and code is applied.

VEA also offers you some control over what your generated code will look like. You can specify what the code generation engine output should look like by using code templates. Code templates are customizable.

To access the code templates, open the Preferences dialog box by selecting UML ® Code® Preferences, and choose the Code Templates category from the Default Settings list, as shown in Figure 12-14. The Templates list shows the available templates for the selected target language and category.

Click To expand
Figure 12-14: Code Templates settings in the Preferences dialog box

A default code template exists for each category, in each of the target languages. In both VB .NET and C#, there are code templates for the following categories:

  • Attributes

  • Relationships

  • Class implementations

  • Method implementations

You can customize the default code templates by clicking the Edit button, or you can choose to create your own by clicking the New button.

The VB. NET code template settings are stored in the Registry in this key:

HKEY_CURRENT_USER\Software\Microsoft\Visio\Solution\UML Solution 2002\Code Generation\Visual Basic\Templates

The C# code template settings are stored in the Registry in this key:

HKEY_CURRENT_USER\Software\Microsoft\Visio\Solution\UML Solution 2002\Code Generation\C#\Templates
Note

Your code templates are not model-specific. Code templates are saved in VEA and are available for all your UML models.

Using the Default Code Templates

Figure 12-15 shows the default VB .NET code template for a class implementation (ClassImpl). The template is shown in the Edit Template dialog box, which appears when you select a template in the Code Template page of the Preferences dialog box and click the Edit button.

Click To expand
Figure 12-15: Default code template for VB .NET class implementation

Suppose that you selected to use the default VB. NET template for generating code for the following class:

Your generated code will look like the code shown in Figure 12-16.

Click To expand
Figure 12-16: VB .NET generated code for the Customer class, based on ClassImpl template

As you can see in Figure 12-15, the code templates are constructed by text and macros (macros are enclosed by the percent sign, %). When generating code, the code generation engine replaces the macros with the macro content. For example, the %class_name% macro will be replaced by the name of the class. If a macro name can't be found during code generation, the macro will be regarded as if it were ordinary text. Table 12-1 lists the available macros and their corre sponding code elements.

Table 12-1. Macros for Use with Code Templates
Macro Name | Description | Code Element(s)
%attrib_name% | Attribute name | Attribute
%author_name% | Name of the author who created the document | Attribute, Class, Operation
%class_comments% | Documentation specified for the class | Class
%class_name% | Class name. | Class
%comments% | Documentation specified for the element | Attribute, Operation
%date% | Date the document was last saved | Attribute, Class, Operation
%end_class_comments% | End of class documentation—the comments that come directly after the end of the class (End keyword in VB.NET and }- character in C#) | Class
%file_name% | Name of the file the class will be saved in, including the specified path |
%friends% | Code for the friends class (C++) |
%indent% | Aligns and indents code to the location/ position specified by the %mark_indent%macro | Attribute, Class, Operation
%innerclasses% | Code for the inner classes (or nested types) | Class
%mark_indent% | Indicates the location where indenting begins; each new line with a parameter will indent to the position/column where the macro is specified (often used with procedure and property parameters when they wrap onto two or more lines; can be used in conjunction with the %indent% macro) | Attribute, Class, Operation
%method_body% | Method body specified for the operation | Operation
%method_name% | Method name | Operation
%package_name% | Name of the package in which the element is logically grouped (this is the namespace in .NET) | Attribute, Class, Operation
%params% | Parameters, including data type | Operation
%params_and_comments% | Parameters and the comments associated with them | Operation
%params_as_comments% | Parameters written as comments, each on a separate line, specifying the data type | Operation
%private_attributes% | Code for the definition of private attributes | Class
%private_methods% | Code for the definition of private methods | Class
%protected_attributes% | Code for the definition of protected attributes | Class
%protected_methods% | Code for the definition of protected methods | Class
%public_attributes% | Code for the definition of public attributes | Class
%public_methods% | Code for the definition of public methods | Class
%super_class_name% | The super or base class name—the class that this class inherits from (specified with the Inherits keyword in VB .NET and a colon, :, in C#, both followed by the name of the super/base class) | Class
%type_name% | Data type name, such as Integer in VB .NET and int in C# Attribute, Operation %visibility% Element's visibility, such as Public/ public or Protected/protected | Attribute, Class, Operation

In Table 12-1, you can see the macro names and the content they are replaced by at code generation time. Table 12-2 shows how the different relation ships map to .NET data types by default.

Table 12-2: Relationship to .NET Data Type Mapping
Relationship Type | Default .NET Data Type
Ordered collection | System.Collections.SortedList
Qualified collection | System.Collections.Hashtable
Unordered collection | System.Collections.ArrayList

Modifying Code Templates

You can modify a default code template by selecting it in the Code Templates page of the Preferences dialog box (shown in Figure 12-14 earlier in this chapter), and then clicking the Edit button. The code template will appear in the Edit Template dialog box (shown in Figure 12-15 earlier in the chapter), where you can make changes to it.

In Exercise 12-7, you'll modify a VB. NET code template and then use it to generate code.

Exercise 12-7
Start example

  1. In VEA, create a new UML model.

  2. Select UML ® Code ® Preferences to open the Preferences dialog box, and choose the Code Templates category from the Default Settings list.

  3. Select Visual Basic from the Target language list.

  4. Select ClassImpl from the Categories list. The only template for this target language and category is the ClassImpl template, so it's automatically selected in the Templates list.

  5. Click the Edit button to open the Edit Template dialog box, which contains the code template you selected (see Figure 12-15).

  6. Edit the text for the code template to add the following under %class_comments%:

    ' This class is part of the main solution and should run on our
' server. Author: %author_name%

  7. In the following line, beginning with %visibility%, change class to Class. Your edited template should look like Figure 12-17.

    Click To expand
    Figure 12-17: Edited VB .NET ClassImpl code template

  8. Click OK.

  9. In the Preferences dialog box, choose the Class category from the Default settings list.

  10. Select ClassImpl from the Implementation list of the Class template group.

  11. Click OK.

  12. Drag a Class shape onto the open diagram and name it Customer.

  13. Add a private attribute named Name to the Customer class. It should be of data type VB::String.

  14. Add a public operation named GetList to the Customer class. The operation must have a VB::Boolean return type.

  15. Add an ingoing parameter named customerTypeID to the GetList operation. It must be of the VB::Integer data type. The static structure diagram should now look like this:

  16. Open the UML Class properties dialog box (if it's not already open) for the Customer class.

  17. Select Code Generation Options from the Categories list.

  18. Make sure Visual Basic is selected in the Target language list and ClassImpl is selected in the Implementation list of the Class template group.

  19. Click the Preview Code button. The code generated in the Code Preview dialog box should look like Figure 12-18 (with the name you used for registering VEA on your system, instead of Carsten Thomsen, of course).

    Click To expand
    Figure 12-18: Generated Customer class code based on the custom ClassImpl VB .NET template

  20. Select C# from the Target language list.

  21. Click the Preview Code button. The code generated in the Code Preview dialog box should look like Figure 12-19.

    Click To expand
    Figure 12-19: Generated Customer class code based on the default ClassImpl C# template

End example

As shown in Figure 12-19, if you generate code with C# as target language, the lines you added to the VB. NET ClassImpl template are not created. This is because the C# code template is different from the VB .NET code template.

Note

If you click the Restore Default button in the Preferences dialog box, the default code templates will be restored to their initial form, and any changes you made to code templates will be lost.


Generating Reports

In VEA, you can generate reports using predefined report templates, which are customizable. The content of the reports is not all that exciting, or even that surprising. A report can contain information about the following elements:

  • Code generation

  • Constraints

  • Documentation

  • Tagged values

The elements shown are common for all report types, but there are specific categories for each type of report.

To create a report, select UML ® Report to open the UML Report dialog box. The following report types are available:

  • UML Activity Report

  • UML Component Report

  • UML Deployment Report

  • UML Statechart Report

  • UML Static Structure Report

Figure 12-20 shows an example of the UML Static Structure Report for the Exercise 12-7.vsd Visio model.

Click To expand
Figure 12-20: UML Static Structure Report in the UML Report preview window

You can export a report to RTF format, and then open it in most word processor applications, including Microsoft Word. To export your report, click the Export button in the UML Report dialog box.

Besides exporting the reports, you can also choose to preview them before you do the actual printing. To preview your report, click the Preview button in the UML Report dialog box.

Note

The Report Preview works only if you have installed a printer in Windows.

You can also save your model as a Web page, as discussed in the next section, which is especially useful if you want to distribute your report to those who don't have access to VEA.

Saving Your Model As Web Page

To save your model as a Web page, select File ® Save As Web Page to open the Save As dialog box, as shown in Figure 12-21. (Alternatively, you can select File ® Save As, and then select Web Page as the Save As type.)

Click To expand
Figure 12-21: Selecting to save a model as a Web page in the Save As dialog box

If you click the Publish button in the Save As dialog box, you'll be able to customize your HTML files. For example, you can choose to generate VML graphics (this requires Internet Explorer 5.0 or later) or GIF graphics, for older browser capacity. This is a great way to document your use case diagrams, sequence diagrams, and collaboration diagrams, as described in the next section. Unfortu nately, only the diagrams are saved; the documentation entered for the elements are not generated.[3]

If you click the Save button in the Save As dialog box, the UML model is saved to disk, and the resulting HTML document is opened in Internet Explorer.

What About Creating Reports for the Other UML Diagrams?

VEA's reporting function does not allow you to generate reports for use case diagrams, sequence diagrams, and collaboration diagrams. Obviously, they also contain fundamental information for your development, and you'll probably want to create these reports.

Note

We have no idea why Microsoft hasn't implemented report types for the other UML diagrams. However, a wild guess is that the focus has primarily been on code, code generation, and the static structure diagram (which indeed has an associated report template). We think this is a shame and a major shortcoming of the product. We haven't been able to find any information indicating if Microsoft plans to implement the missing report types in future versions, so we're not too optimistic that this may happen soon. In fact, with the new modeling capabilities in the upcoming version of VS .NET, currently code-named Whidbey, we doubt this will ever happen.

You have three ways of working around this major omission:

  • Save the model as a Web page and deploy it through an intranet or the Internet.

  • Distribute the Visio .VSD file and a link to the Visio Internet Explorer addin, Visio Viewer, which allows Visio .VSD files to be viewed in the browser.

  • Create a VBA macro that does what you need.

Creating a VBA macro can be a bit tricky, and it certainly is a lot more work than your other options. We suggest that you distribute the Visio .VSD file with a link to the Visio Viewer, or simply save the model as a Web page and make it available on a Web server.

If you choose to distribute the Visio .VSD file and a link to the Visio Viewer, your target audience must have Internet Explorer 5.0 or later installed. The Visio Viewer can be downloaded free of charge at this address: http://www.microsoft.com/downloads/details.aspx?FamilyId=3FB3BD5C-FED1-46CF-BD53-DA23635AB2DF& displaylang=en. The Visio Viewer ActiveX component will enable you to view Visio drawings (VSD or VDX formats) in Internet Explorer (5.0 or later). It provides full-fidelity rendering for files. It works with Visio files created in Visio 5.0, Visio 2000, Visio 2002, and Visio 2003. Figure 12-22 shows the Exercise 12-7.vsd Visio model opened in Internet Explorer with Visio Viewer installed.

Click To expand
Figure 12-22: Visio VSD file opened in Internet Explorer
Start Sidebar
Evaluating VEA

Now, we've said it in other chapters, and we'll say it again: VEA is a decent UML tool and it's free with VSEA. However, it does have some significant shortcomings, which we've mentioned in previous chapters and will also talk about in upcoming chapters. A shortcoming we haven't fully commented on elsewhere is VEA's rather poor support of statechart diagramming, with the following limitations:

  • You have little control over the layout.

  • Assigning an event is somewhat confusing.

  • Compound statecharts are implemented very poorly.

  • There is no integration with elements on the class diagram.

We think that the lack of round-trip engineering is by far the single biggest problem with VEA, and for us, that is the killer feature. Can you live without it?

Now, if you can live with these and the shortcomings mentioned in other chapters, VEA could very well be the tool for you. If not, look elsewhere, such as IBM Rational XDE or MagicDraw from No Magic (http://www.magicdraw.com).

Do keep in mind that the upcoming release of VS .NET, code-named Whidbey, will offer significant improvement in the software modeling area (code-named Whitehorse). You can find out more about the future release at http://msdn.microsoft.com/vstudio/productinfo/roadmap.aspx#whidbey. Obviously, it's too early to say how the upcoming version will work. However, we think that upgrading any VEA diagrams to Whitehorse should be a fairly straightforward process. Watch out for announcements from Microsoft concerning this, or even better, get in on the official beta.

End Sidebar

[3]Frankly, VEA is still not state-of-the-art when it comes to reporting.


Summary

In this chapter, you were introduced to the functionality in VEA that is important from a UML and enterprise development point of view. First, you saw how to generate code directly from UML diagrams (static structure diagrams), followed by an introduction to reverse engineering, where an existing VS .NET solution was reverse-engineered to UML models (not the diagrams, just the elements).

Next, you learned that two kinds of error checking exist in VEA: semantic errors and programmatic errors. Semantic errors are errors not conforming to the UML 1.2 standard, and programmatic errors are those that cause errors in the generated code (even though the UML 1.2 standard hasn't been violated).

Then you were introduced to code templates, which you can modify to have some degree of control over how VEA will generate code.

Finally, you learned about report generation at a high level. An important point was VEA's lack of reporting for certain types of diagrams, including use cases. We mentioned a few workarounds for how to generate the missing reports.

The next chapter will introduce you to another one of the enterprise features of VS .NET: Microsoft Application Center Test (ACT) for analyzing your Web application's performance and stress testing your Web servers.


Chapter 13: Application Center Test

Overview

In this chapter, you'll learn how you can use Microsoft Application Center Test (ACT) to analyze your Web applications' performance and stress-test your Web servers. We'll present an overview of ACT, and then move on to cover manipulating users and groups, creating projects and tests, running tests, and examining test results.

We'll direct you to the ACT documentation where appropriate. That said, this overview chapter contains some basic information you won't find in the documentation.

Note

If you need information on performance-testing your distributed applications, please refer to Chapter 14.


Introducing ACT

As we stated previously, ACT used is for analyzing the performance of Web appli cations and stress-testing Web servers. You can use ACT with any Web application and any Web server that complies with Hypertext Transfer Protocol (HTTP) 1.1. This is great news, because not only can you use ACT with your .NET Web appli cations and .NET Web servers (i.e., Web servers capable of running .NET Web applications and Web services; in other words, Web servers with the .NET Framework installed), but you can also use it with existing Web applications and servers. This means that it's a great tool for analyzing existing Web servers and applications, and effectively establishing a baseline. You can then use this baseline for comparison with new Web servers and/or applications you put into place.

Tip

Use ACT to establish a baseline for existing systems that you want to upgrade.

ACT comes with both of the Enterprise editions of VS .NET 2003, and it's named accordingly: Microsoft Application Center Test .NET Edition. It's also bundled with Microsoft Application Center 2000, and this is a more complete tool if you really want to get into scalability, manageability, and availability, as well as the features of ACT. (You can find more information about Microsoft Application Center 2000 at http://www.microsoft.com/applicationcenter.) In addition, ACT is bundled with both of the Enterprise editions of VS .NET 2002, but unlike the main VS .NET package, which has been upgraded, ACT still comes in version 1.0, as it did with VS .NET 2002.

You use ACT to test your Web applications and servers using dynamic tests. These dynamic tests are scripts written in either VBScript or JScript. After running a test, you can analyze the results. Now that's simple enough, isn't it? Well, getting started is pretty easy, but don't let that fool you—you can use ACT for some serious testing.

Because dynamic tests are written in either of the aforementioned pro gramming languages (VBScript or JScript), we obviously depart from VS .NET as they're not managed programming languages. We won't explain how to use either programming language in this chapter. We recommend the following books for those who want further information:

  • VBScript in a Nutshell, 2nd Edition, written by Paul Lomax et al., published by O'Reilly & Associates, April 2003 (ISBN: 0-59600-488-5).

  • JavaScript: The Definitive Guide, 4th Edition, written by David Flanagan, published by O'Reilly & Associates, December 2001 (ISBN: 0-59600-048-0).

Now that you know a little bit about ACT, let's get started using it. In the following sections, you'll cover the various ACT computer roles, and you'll learn how to create and set up projects and tests from the ACT stand-alone application as well as from within the VS .NET IDE. You'll also look at which project environment best suits your needs.

Understanding ACT Computer Roles

ACT specifies two roles for the computers involved in the testing: the controller and the client.

Note

Actually, there's a third role: the Web server that's tested (i.e., the Web server to which the test requests are sent).

An ACT controller is the computer in control of the test, which means it performs the following functions:

  • Initiates the test

  • Manages the running test

  • Collects the test results

  • Stores the test results

  • Stops the test

In the context of ACT, a client is a computer that sends requests to the Web server and subsequently runs the test. Actually, Microsoft refers to the clients as "test clients," which makes sense. Anyway, the version of ACT that comes with VS .NET doesn't support multiple clients, so in our case there will always be just one client. Multiple clients are supported by Microsoft Application Center 2000.

Note

An ACT controller is also a client.

Using the ACT Stand-Alone Application

ACT comes as a stand-alone application. To open it, click the Start menu button and select the Microsoft Visual Studio .NET Application Center Test menu item from Programs ® Microsoft Visual Studio .NET 2003 ® Visual Studio .NET Enter prise Features. It's worth noting that ACT isn't installed in the default Visual Studio .NET folder. You can find it in the \Program Files\Microsoft ACT folder instead.

The ACT stand-alone application's UI is clean and easy to understand. The first time you open ACT, you'll see the dialog box shown in Figure 13-1.

Click To expand
Figure 13-1: Opening ACT for the first time

In the New Project dialog box shown in Figure 13-1, you're prompted for a name and location for a new project. This dialog box appears every time you open ACT, until you actually create or open a project. Although you can cancel this dialog box, it doesn't make much sense to do so, because you can't run ACT without a project.

Tip

You can reset ACT so that the New Project dialog box is shown when ACT opens if you delete the LastProject string value of the My Computer\HKEY_CURRENT_USER\Software\Microsoft\ACT\ Settings key in the Registry.

Enter a project name in the Name field of the New Project dialog box and a location in the Location field to create a new project, or open an existing project by pressing Ctrl+O or selecting File ® Open Project (if the New Project dialog box is shown, you must click Cancel or press Esc first to close this dialog box). When a project is open in ACT, it looks similar to Figure 13-2.

Click To expand
Figure 13-2: ACT UI with a project opened

In Figure 13-2, you can see the ACT UI with the newly created NewACTProject project open. If you inspect the menus, you'll find that there aren't many menu items that relate to the project or the various tests; nearly all of them relate to the UI, for example, the font settings. However, this doesn't mean that there aren't any project- or test-related settings—they're all in the two different Properties dialog boxes. You'll find more information about the project and test properties later in this chapter in the "Setting Project Properties" and "Setting Test Properties" sections, respectively.

After you save a new ACT project, the files listed in Table 13-1 are created for you.

Table 13-1: Microsoft ACT Project Files
File Name | Description
<ProjectName>.act | This is the actual ACT project file, which you can open from both the ACT stand-alone application and the VS .NET IDE. This is an XML file that has references to the other files that make up the project, as well as values for when the project was created and last modified.
clientGroup-Default Clients Group.xml | This is the default clients group file, which holds information about the clients used for testing the Web server(s) and application(s). The default file holds only information about the localhost client. It's the clientGroup part of the file name that signals to ACT that this is a client group file, which means that any new client group files will be named clientGroup-<Name of Client Group>.xml. One file holds one client group and the information for all the clients contained in the client group. You can find more information about clients in the "Understanding ACT Computer Roles" section earlier in this chapter.
properties.xml | This file holds the default values for the project and the tests contained in the project.
userGroup-Default Users Group.xml | This is the default users group file, which holds creden tials for 200 users, User0 through User199, with a default password of password. It's the userGroup part of the file name that signals to ACT that this is a user group file, which means that any new user group files will be named userGroup-<Name of User Group>.xml. One file holds one user group and the credentials for all the users contained in the user group. You can find more information about users and groups in the "Users and Groups" section later in this chapter.

Using ACT Within the Visual Studio .NET IDE

When you're using either of the Enterprise editions of VS .NET, you can open and create ACT projects. You create a new ACT project by opening the New Project dialog box (press Ctrl+Shift+N or select File ® New Project). In the New Project dialog box, select the Application Center Test Projects project type in the Other Projects category, and because there's only one type of this kind of project, all you need to do is set the location and name of the new ACT project, as shown in Figure 13-3.

Click To expand
Figure 13-3: Creating a new ACT project in the VS .NET IDE

When you click OK to create the ACT project, your VS .NET IDE will look similar to Figure 13-4.

Click To expand
Figure 13-4: VS .NET IDE with a new ACT project

If you inspect the menus, you'll find that you can't really do anything with the project yet, except set the project properties and add one or more tests, which is really what it's all about.

When you create a new ACT project from within the VS .NET IDE (or open an existing project created with the ACT stand-alone application), the files listed in Table 13-2 are created in addition to the files listed in Table 13-1.

Table 13-2: VS .NET Application Center Test Project Files
File Name | Description
<ProjectName>.actproj | This is the VS .NET ACT project file, which is used as any other VS .NET project file, such as .vbproj for VB .NET projects and .csproj for C# project files. The project settings are stored in the <ProjectName>.act file (see Table 13-1), but the <ProjectName>.actproj file is needed as a "link" between the VS .NET solution and the actual ACT project file. If ACT didn't exist as a stand-alone application, the .act and <ProjectName>.actproj files could supposedly be merged into one.
<SolutionName>.sln | This is the solution file for the VS .NET solution.

Choosing the ACT Project Environment

Both the ACT stand-alone application and the VS .NET IDE environments give you the same options, and they're both based on an ACT project. Once created, an ACT project can be used in either environment. So why choose one environment over the other? That's a very good question, and we feel it comes down to preference.

Note

You can't open an ACT project in both the VS .NET IDE and the ACT stand-alone application at the same time—an ACT project file can be opened in only one environment at a time.

Here are some reasons for using the ACT stand-alone application environment for your ACT projects:

  • It doesn't consume as many resources—mainly memory—as the VS .NET IDE.

  • You want to view test reports.

  • You don't need the project as part of a VS .NET solution.

  • You want to easily set up users and groups through the UI.

  • Here are some reasons for using the VS .NET IDE for your ACT projects:

  • You need the ACT project as part of a VS .NET solution with other VS .NET projects.

  • You're used to the VS .NET IDE and find it easier to navigate in and control than the ACT stand-alone application environment.

As you can see from the reasons just listed, you might well find that you use both environments, or you may use one over the other because you find it easier to use. Personally, we use the VS .NET IDE because we use it for many other projects.


Users and Groups

A user is, generally speaking, a person who uses the software and/or hardware you supply.[1] In terms of ACT, a user is much the same: a person who uses the Web server and the applications on it. Figuratively speaking, because there aren't any "real" users, ACT helps you simulate one or more users, depending on your needs. A single user corresponds to a single browser connection, which means that if you need, say, 20 simultaneous browser connections to the Web server you want to test, you need at least 20 users.

Users are organized into groups, meaning that a user must belong to a group. However, you can have several users with the same name in different groups. This implies that tests are carried out based on at least one group of users, so you can't perform tests without a user group. If the Web server you're testing doesn't require you to log on and you don't need to keep session cookies (ACT associates HTTP session cookie information with each user) after the test ends, you can have ACT create the users for you. If you do have either of these requirements, you need to create the users manually. In line with any sort of authentication, you can assign a password to a user, and you can even create user accounts that cor respond to your local Windows user accounts.

Note

Users and groups are project dependent, meaning that the users you create in a project won't be part of any other projects you might have.

In the next section, we'll describe how to manipulate users and groups in ACT.

Manipulating Users and Groups

Users and groups go hand-in-hand in ACT, and in general you'll create a group before you create users. If you already have a group, you can add users to, remove users from, or modify users in the existing group. Although it's possible to set up users and groups in the VS .NET IDE, you must do this manually by editing the appropriate XML-based text files (see Table 13-1). In this section, we'll show you how to work with users and groups from within the ACT stand-alone application.

Tip

If you need to manipulate the users and/or groups for a VS .NET ACT project, we recommend you open your project in the ACT stand- alone application and use the UI for this purpose. In our opinion, this is easier than using the VS .NET IDE.

You create a group by right-clicking the Users node in the pane on the left of the ACT stand-alone application and selecting Add from the pop-up menu. This adds a new user group to the User node. The new user group is appended to the end of the list of groups, and it's automatically named New Users Group x, where x is a consecutive number. So, when you create your first new group, it's named New Users Group, and if you don't rename this group, the next new groups will be named New Users Group 1, New Users Group 2, and so on.

Note

The user groups aren't arranged alphabetically, but you can rearrange the order in which they appear by editing the project file(.act). You are able to arrange the global UserGroupDef nodes within the Project node in the order you want them displayed in the UI. The only group (and associated users) that's part of all new projects is the Default Users Group, which contains 200 users.

When you've created the user groups you want to add users to, select the group in the Users node, as shown in Figure 13-5.

Click To expand
Figure 13-5: New Users Group

In Figure 13-5, you can see the New Users Group group selected in the pane on the left and the associated users (none by default) in the right pane. You now have three options for creating new users:

  • You can enter user names and passwords manually in the pane on the right. When you type the name of a user into the last visible row in the user grid, a new row is automatically added to the grid.

  • You can generate users automatically by selecting Action ® Generate Users. This brings up the Generate Users dialog box, in which you can specify the number of users you want, enter the names of the users (they'll have the same name, suffixed with a number, such as User0, User1, User2, and so on), and the password, which initially will be the same for all users.

  • You can import the users from a comma-delimited list by selecting Action ®Import Users. This brings up the standard Windows Open dialog box, in which you can select the file containing the users and associated passwords. The file you import must use the comma (,) as the separator and not the list separator your system is set up to use, such as the semicolon (;). In addition, each user must be separated from the next by a carriage return. The rows must have exactly two columns (user name and password), or the values of subsequent columns will be imported as part of the password, including the separating comma.

You can delete users by selecting them in the user grid and pressing Delete or by choosing Edit®Delete. Please note that you're not prompted to confirm the deletion. If you need to change the user name and/or password, you simply modify the existing values for the desired user. Changes to the users and groups are saved when you save the project.

Note

If you need to use user information from your Windows network, such as when integrated Windows authentication is turned on for a site you're testing, you can enter the user name prefixed with the machine or domain name, like this: DomainName\UserName.

[1]We realize that this statement is only partially true, because users and user accounts can be two different things. In Windows authentication you have a number of user accounts that aren't used by "real" users, such as the local system account.


Setting Project Properties

In each project you create, you can set a number of properties that will affect how all the tests in the project are performed. You can see the various properties in Figures 13-6 and 13-7. Here's how you can view and modify the project properties:

  • ACT stand-alone application: Right-click the project in the left pane or select the project in the left pane and select Actions ® Properties. This brings up the Properties dialog box.

  • VS .NET IDE: Select the project in the Solution Explorer, and view and modify the properties in the Properties window, just as you would the properties of any other element in the Solution Explorer. You can open/show the Properties window by pressing F4, if it's not already open/shown.

In this section, we'll walk you through the various project properties as you see them in the ACT stand-alone application. We'll point out any differences between working in the stand-alone application and working in the VS .NET IDE.

In Figure 13-6, you can see the more general project properties, including a check for Robots.txt and options for using a proxy server to connect to the Web server.

Click To expand
Figure 13-6: General tab of the project Properties dialog box

The properties on the General tab are as follows:

  • Check for existence of "Robots.txt": The Robots.txt file is used to specify what files and folders to search on the Web server. Among other things, it's used by search engines (such as Google) when crawling your Web site(s). This property isn't available in the VS .NET IDE. This property may or may not influence your tests. If you test specific pages (i.e., pages you know are available), this property has no meaning. However, it will have an effect if you're dynamically accessing all the pages on a Web site and some of them are marked in the Robots.txt file as off-limits. At a minimum, it will certainly affect the time it takes to test the pages on a Web site.

  • Proxy settings: We won't delve into how to use proxy servers for accessing Web servers, but we encourage you to take a look at the same options in Internet Explorer and the associated help if you're using proxy settings to access the Internet. Be aware that even if you do use a proxy server to access the Internet, the Web servers you're testing might all be accessible from inside the proxy server. Ask your system administrator for help setting this up.

In Figure 13-7, you can see the project debugging properties, which you use for tracing your test runs, including a socket request time-out value and an option for logging the tracing information. Please see the ACT documentation for more information about debugging your tests.

Click To expand
Figure 13-7: Debugging tab of the project Properties dialog box

The properties on the Debugging tab are as follows:

  • Socket request time-out (seconds): The value you specify for this property indicates how many seconds to wait before closing an inactive connection. Specifying a value that's too low can result in send and receive errors, whereas specifying a value that's too high might affect the load placed on your server. Which value is appropriate and what a too low or too high value means in your case depends on your circumstances. In general, we've found that the default value of 120 is adequate in many situations. You should consult your Windows and/or network documentation if you need more information on sockets and socket settings.

  • Enable logging of test runs: This option specifies whether or not to log the test runs. When you select this option, you can also specify the maximum size of the log file, as well as where to save the log file. The default value, (automatic), saves the log file to the \Program Files\Microsoft ACT folder, unless you specify a different installation folder. In VS .NET, everything is logged to the Test Run pane of the Output window.

Now that you've set your project properties, you're ready to test your project, which is what we'll cover in the next section.


Creating a Test

When you have a project open in ACT or the VS .NET IDE, you need to create one or more tests to run to test your Web application or server. In ACT, you do this by selecting the Tests node, right-clicking it, and selecting New Test form the pop up menu. Alternatively, you can select Actions ® New Test. In the VS .NET IDE, you right-click the project in the Solution Explorer and select Add ® Add New Item from the pop-up menu. You can also select Project ® Add New Item or press Ctrl+Shift+A if the project is selected in the Solution Explorer. Any of these will bring up the Add New Item dialog box.

In both environments, you choose between an automatic, browser-recorded test and a manual test. If you choose the manual test, you also need to choose between VBScript and JScript as the scripting language.

Note

Browser-recorded tests can record actions only in VBScript.

Whether you should choose automatic recording over the manual way of creating a test is a matter of preference and is also dependent on the task at hand. However, if you know that a number of the tasks you want as part of the test are easily recorded, and you're fine with using VBScript as the scripting language, you can use the automatic recording as the basis for your own manual test, which will save you some time. This brings us to an important aspect of ACT. Although it's a great tool for testing your Web servers and applications, there's still a signif icant amount of time involved in creating the correct tests.

Now, we're not going to show you how to create manual VBScript or JScript code, but we will walk you through the browser recording of a test in both the ACT stand-alone application and the VS .NET IDE in the following section.

Recording a Test

To record a test in the ACT stand-alone application, follow these steps:

  1. Right-click the Test node in the left pane and select New Test from the pop-up menu. Alternatively, select Actions ® New Test.

  2. The New Test Wizard will appear. Click Next on the first page of the wizard to go to the Test Source page, on which you select the Record a new test option and click Next.

  3. On the Test Type page, you can select which scripting language you want to use for the test. Currently, only VBScript is supported for recording a test, and because this option is selected by default, all you need to do is click Next.

  4. This brings you to the Browser Record page, on which you need to click the Start recording button to start the recording.

  5. A browser window will appear in which you can perform any actions you want recorded. Click the Stop recording button to stop the recording, and click Next to show the Test Properties page, in which you can name the test.

  6. Type in the test name, click Next, and finally click Finish to save the recorded script. The test is now added to the Test node in the left pane. Select it to view the record script.

To record a test in the VS .NET IDE UI, follow these steps:

  1. Right-click the project node in the Solution Explorer and select Add ®Add New Item from the pop-up menu. Alternatively, you can select the project in the Solution Explorer and press Ctrl+Shift+A, or select Project ®Add New Item.

  2. The Add New Item dialog box appears, in which you select the Browser Recorded Test template, name the test, and click OK.

  3. In the Browser Record dialog box, click the Start button to start the recording.

  4. A browser window will appear in which you can perform any actions you want recorded. Click the Stop button to stop the recording, and click OK to save the recorded script. The script is then shown in the code editor.

    Tip

    We think that automatic browser recording is a great feature, and we recommend that you try it. You'll get a good feel for what it can do for you, and you'll see the scripting code that it produces. In many situations, you should use automatic browser recording when you need to know what code corresponds to a certain browser action.

Now let's take a look at one of the tests that comes with ACT, just to give you an idea of what to expect during testing and what you can actually do with ACT. In the Samples folder (\Program Files\Microsoft ACT\Samples\ACTSamples), you can find the ACTSamples project (ACTSamples.act), which has a number of tests, as you can see in Figure 13-8.

Click To expand
Figure 13-8: ACTSamples project in ACT

We'll look at the contents of some of the tests in the next section.

Examining Test Scripting Code

Remember that when you create tests manually, you have to use either VBScript or JScript. If you're new to scripting languages, this can be a problem, so you may want to first have a look at the resources we mentioned at the beginning of this chapter. Even if you're familiar with or proficient at either scripting language, you still need to know the ACT automation model. We won't cover the automation model in this chapter, but please do look at your documentation for information on the Application object model, as the automation model is called in ACT.

Now let's take a brief look at some of the tests in the ACTSamples project that we started examining in the previous section. You'll be able to reuse many of these in your own tests. The "description" we refer to in the following list is the text at the very top of the code files. The sample tests we describe in this section require some sort of setup, and the instructions are written in the description. One of the setup requirements is that the contents of the \Program Files\Microsoft ACT\ Samples\TestFiles folder are copied to the root virtual directory on the machine that runs Internet Information Services (IIS) (i.e., the machine/Web server that you're testing). If you don't do this, you'll get nothing but errors from all the requests made in the tests. The reason the Test folder must be copied to the root virtual directory on the Web server is that it's the Web server's default Web site that is tested, not any virtual directories or virtual servers.

  • Browser Type: The Browser Type test is appropriately named, because you can use it for impersonating or mimicking various browser types. You do this by specifying different browser headers and agent strings, as you can see from the description. This kind of test is obviously interesting when your Web server/application must serve different kinds of browsers and not just Internet Explorer.

  • Body Search: You can use the Body Search test for a number of tests in which you want to look at the HTML code produced by the server. This particular test searches for the presence of an HTML body by looking for the </HTML> closing tag. The example is a bit contrived, but it certainly shows you how simple it is to get to the HTML served to the client browser by the Web server.

The two tests just listed make use of the Test class from the automation model, especially for creating a connection to the Web server. This is the most important class in the automation model. Other important classes are Project, User, UserGroup, Controller, and Report.


Setting Test Properties

Any test in a project uses the project properties described in the "Setting Project Properties" section, but it also uses some specific test properties, as shown in Figures 13-9 through 13-11.

In Figure 13-9, you can see the more general test properties, including a value for how many simultaneous browser connections your test requires.

Click To expand
Figure 13-9: General tab of the test Properties dialog box

The Simultaneous browser connections value must be less than or equal to the number of users in the user group assigned, if you opt not to have ACT create the users automatically.

The Test duration group of controls and values is more or less self-explanatory; basically, you can run the test for a specified time or a certain number of times. The Advanced button gives you the option to generate detailed test results, which is the default setting.

Figure 13-10 shows the user properties for a test. You can have ACT auto- generate the users needed, or you can select a predefined group of users. Please keep in mind that if you select a predefined group of users, this group must hold at least the number of users specified as the Simultaneous browser connections value on the General tab of the test Properties dialog box. (Please see Figure 13-9 for more information.)

Click To expand
Figure 13-10: Users tab of the test Properties dialog box

If the Web server or application that you're testing requires a login, or if you want the session-state cookies to be preserved after the test run ends, you can't use the Automatically generate users option on the Users tab of the test Properties dialog box. Instead, you'll need to select a predefined group of users.

Figure 13-11 shows the Counters tab of the test Properties dialog box. Here, you can add and remove Windows performance counters for your test. Actually, the performance counters aren't test specific—they're machine specific—but they're collected for the test for which you specify them. This also means that you can add performance counters for any machine for which you feel it's necessary to measure performance when the test runs. Most often, you'll choose to measure performance on the Web server you test, but you might also want to measure the performance on the test client and/or on any other machine that's even remotely part of the Web server setup, such as a database or business logic server.

Click To expand
Figure 13-11: Counters tab of the test Properties dialog box

We won't discuss performance counters here, but we will mention that the more commonly used counters help you diagnose your setup by finding processor, memory, and disk bottlenecks. You can find a good overview of Windows 2000 Performance Counters at http://msdn.microsoft.com/library/ default.asp?url=/library/en-us/counter/default.asp.


Running a Test

When you've created your test, you can run it from within ACT or the VS .NET IDE. It's a pretty simple process in either environment.

  • In ACT, you select the test under the Test node (see Figure 13-2), right-click it, and select Run Test from the pop-up menu. Alternatively, you can press Ctrl+F5 or select Action ® Start Test once you've selected the test.

  • In the VS .NET IDE, you select the test in the Solution Explorer, right-click it, and select Start Test from the pop-up menu. Alternatively, you can select Test®Start Test once you've selected the test in the Solution Explorer.

    Note

    When you run your tests, you need to make sure the project files are located on a local disk. If the files aren't on a local disk, you risk getting error messages such as these:

    "Could not access the project folder. Verify that the ACT User account
has sufficient privileges on the folder."
"Could not create the Windows Management locator object."

Output from the test is stored as a report, as we cover in the next section, "Examining Test Results." However, in the VS .NET IDE, intermediate test infor mation is output to the Output window, as shown in Figure 13-12, which allows you to follow along as the test is executed.

Click To expand
Figure 13-12: Intermediate test output in the Output window in the VS .NET IDE

This intermediate output is the same you get in ACT. In ACT, however, the output is shown in the Test Status dialog box, as you can see in Figure 13-13.

Click To expand
Figure 13-13: Intermediate test output in the Test Status dialog box in ACT
Tip

If you get an error message saying that a test is already running, and you're sure that no test is currently running, it's likely that the ACTTrace.log file is locked (perhaps because of a previously failed test). The intermediate test output file is located in the \Program Files\ Microsoft ACT folder, and a reboot is necessary, unless you're a person who is able to kill the correct Windows process (i.e., the process that has a lock on the log file).

If a test is running for too long, or if you simply want to cut a test short, you can stop it immediately, as follows:

  • In ACT, select Action® Stop Test or click Stop Test in the Test Status dialog box (see Figure 13-13).

  • In the VS .NET IDE, select the test in the Solution Explorer, right-click it, and select Stop Test from the pop-up menu. Alternatively, select Test ®Stop Test.


Examining Test Results

After you run a test, the results are stored as a report that's accessible under the Results node in ACT (see Figure 13-2) or by right-clicking the test in the Solution Explorer in the VS .NET IDE and selecting View Results. Alternatively, you can select the test in the Solution Explorer and select Test ® View Results. In the VS .NET IDE, the Application Center Test Results dialog box appears, as shown in Figure 13-14.

Click To expand
Figure 13-14: Application Center Test Results dialog box in the VS .NET IDE

The Application Center Test Results dialog box shows all the results stored for the test you selected in the Solution Explorer. So now you can see a list of reports, but how do you view them? You can't! Yes, we really are saying that you can't view the reports in the VS .NET IDE—you need to open them in ACT to view them.

In ACT you expand the test shown in the Test runs pane after you select the Results node, as shown in Figure 13-15. This brings up the same list as shown in Figure 13-14, but unlike in the VS .NET IDE, you can actually view the reports by selecting them. The reports are very detailed, and you can see such information as the number of errors, the kinds of errors, detailed response and request infor mation, and so on.

Click To expand
Figure 13-15: Test reports in ACT

The reports are divided into seven categories:

  • Overview: Summary

  • Test Run Graph

  • Properties

  • Summary

  • Errors Counts

  • Additional Network Statistics

  • Response Codes

We present a brief description of each category in the following sections.

Overview: Summary

This category shows a summary overview that contains the test name, when the test started, how long the test ran, how many iterations there were in the test, and any notes.

Test Run Graph

This category displays a graph of the test run, as shown in Figure 13-16.

Click To expand
Figure 13-16: Test run graph

On the x-axis of the graph you have the number of requests, and on the y-axis you have the time specified in seconds. On the right side of the graph is a legend for the various values depicted on the graph. As you can see from the legend, errors are also shown on the graph, but you can remove them by clicking the Hide Errors link at the bottom left (the link then changes to Show Errors, which is the default). As you can see, there are no errors in the graph in Figure 13-16.

Properties

This category shows such information as test type (which is always dynamic with the .NET edition of ACT), the number of simultaneous browser connections, the test duration, and the number of iterations.

Summary

This category shows the total number of requests and connections. Then the following average information is shown:

  • Requests per second

  • Time to the first and last byte in milliseconds

  • Number of unique requests and response codes

Errors Counts

This category shows the total number of errors divided in the following three areas: HTTP, DNS, and Socket.

Additional Network Statistics

This category shows information about the network in general during the test, including such information as the average bandwidth measured in bytes trans ferred per second; the number of bytes sent and received; the average rate of bytes sent and received; and the number of connection, send, receive, and time out errors.

Response Codes

This category shows any response codes that might have been returned, such as 404 Page Not Found.


Summary

In this chapter, you examined Microsoft Application Center Test, a tool designed to stress-test and analyze the performance of Web applications and servers. You learned about ACT in general, including the computer roles; how to manipulate users and groups; how to create projects and tests; how to run tests; and how to examine test results.

In the next chapter, you'll learn how to use Visual Studio Analyzer for ana lyzing the performance of your distributed applications.


Chapter 14: Visual Studio Analyzer

Overview

Visual studio analyzer is a tool for collecting analysis information about distributed applications. Visual Studio Analyzer comes with both of the Enterprise editions of VS .NET 2003: VSEA and VSED. It is a high-level tool that works at the component level, effectively helping you isolate the components of your application that poten tially need optimizing. Most profiling tools, such as code profilers, generally work at the method level, profiling the code in your methods. You'll use those kinds of profiling tools once you've identified the components of your distributed application that need to be optimized by using Visual Studio Analyzer.

In this chapter, you'll see how you can use Visual Studio Analyzer for analyzing your distributed application's performance. Visual Studio Analyzer complements Microsoft Application Center Test (ACT), which you can find more information about in Chapter 13. Although this is a short survey chapter, we're confident that you'll get to know the basics of Visual Studio Analyzer, so you'll know when and for what purpose to use it.


Visual Studio Analyzer Architecture

Visual Studio Analyzer is really nothing more than a client/server application. The server is the computer that hosts the components to be analyzed, and the client is the computer that collects results from the analysis performed on the server. In practice, the server and client can be the same computer.

The Visual Studio Analyzer client is responsible for collecting the analysis results from the Visual Studio Analyzer server, and also possibly displaying those results. The Visual Studio Analyzer server collects results from the components running on the computer on which it is installed. Figure 14-1 shows a very simple overview of a Visual Studio Analyzer setup, with two servers.

Click To expand
Figure 14-1: Simple Visual Studio Analyzer architecture

Now, although this simple setup is correct, there is obviously more to it than that. The event collection and analysis works like this:

  1. On each server, a Local Event Concentrator (LEC) is responsible for collecting events, such as writing to disk or communicating with a database server, from an event source. An event source is any component that has been activated by the LEC.

  2. The component/event source generates events using an In-process Event Creator (IEC) that the LEC collects and filters. This filter is set by you using the Visual Studio Analyzer interface.

  3. The events that are filtered are passed back to the Public Event Collector (PEC) on the client that initiated the analysis.

  4. The PEC saves the events to an event log.

Figure 14-2 illustrates the Visual Studio Analyzer event collection and analysis process. You can see how the PEC sends filters to the LECs, which in turn activate the event sources on the local computer, based on the filter received. The event sources use the IEC to generate events that are then collected by the LEC, which sends them back to the PEC.

Click To expand
Figure 14-2: Visual Studio Analyzer event collection and analysis process

In Figure 14-2, the event sources are COM components, which will probably account for most, if not all, of your event sources. However, Visual Studio Analyzer can also be used for analyzing applications on non-Windows systems using a Remote Procedure Call (RPC) bridge. (Refer to your documentation for more information about using an RPC bridge.)

So, does this mean that your .NET components can't be used with Visual Studio Analyzer? It's true that .NET components cannot be used directly. However, you can choose to make your .NET components visible to COM with a COM Callable Wrapper (CCW), which is the way forward.[1] (See your documen tation for more information about CCWs.)

Note

You can create your own Visual Studio Analyzer client using the Visual Studio Analyzer automation model, and view and analyze it any way you see fit. In this case, the events are not stored in an event log. Consult your documentation for more information about how to do this.

[1]Keep in mind that COM Interop has a performance penalty, so this will have an affect on the accuracy of your measurements.


Installing Visual Studio Analyzer Components

You need to install the Visual Studio Analyzer client and possibly the server, too, on your development machine. You also need to install the Visual Studio Ana lyzer server on any machine from which you need to collect and analyze events.

Note

A Visual Studio Analyzer client and a Visual Studio Analyzer server can operate on the same computer.

When you install either of the VS. NET Enterprise editions, you can select to install the client, server, and SDK, as shown in Figure 14-3.

Figure 14-3: Visual Studio Analyzer setup options

  • The Visual Studio Analyzer server is installed by selecting the Visual Studio Analyzer Server option from the Server Components category.

  • The Visual Studio Analyzer client is installed by selecting Visual Studio Analyzer from the Enterprise Development Tools category.

  • If you want to install the SDK for automation and "live" performance analysis in your applications, select the Visual Studio Analyzer SDK in the Visual Studio SDKs category under the Enterprise Development Tools category.

If you need to install the Visual Studio Analyzer Server software on a machine that doesn't host the VS .NET development tools, you can use the Remote Compo nents Setup option in the main Visual Studio .NET Setup window, as shown in Figure 14-4. Click the option to install Visual Studio Analyzer server on any machine from which you need to collect event data.

Click To expand
Figure 14-4: Remote Components Setup option

You need to make sure the Visual Studio Analyzer server software is running when you want to collect event data. On Windows 2000 and later, the Visual Studio Analyzer server is started automatically. Your documentation will guide you on how to run your Visual Studio Analyzer server on the various platforms.


Creating a Visual Studio Analyzer Project

Once you have installed the Visual Studio Analyzer client and server on the required machines, as described in the previous section, you can create and run a Visual Studio Analyzer project. You can set up your project manually or use the Analyzer Wizard, as shown in Figure 14-5.

Click To expand
Figure 14-5: Visual Studio Analyzer projects in the VS: NET IDE

We recommend that you use the Analyzer Wizard until you become familiar with Analyzer projects. It will save you a lot of time, and also give you an idea of what to do and how to use Visual Studio Analyzer. The Visual Studio Analyzer Project Wizard takes you through selecting the Visual Studio Analyzer server or servers, the component or components to watch, and finally the events to collect.

Here, we'll go through the steps in using the wizard:

  1. In the first step of the Visual Studio Analyzer Project Wizard, select the Visual Studio Analyzer server or servers you want to collect events from, as shown in Figure 14-6. Type in the NETBIOS name[2] of the Visual Studio Analyzer server and click Add to add it to your project. Click Next to proceed to step 2 of the wizard.

    Click To expand
    Figure 14-6: Visual Studio Analyzer Project Wizard, Step 1

    Note

    You can add a machine by any name; it doesn't have to exist, nor does it need to have Visual Studio Analyzer server components installed for you to add it at this stage. However, when you move onto the next steps, you will get an error message, if any of the two mentioned conditions are true. So, the lesson here is that the validation of the machine name doesn't take place in the first step.

  2. In the second step of the Visual Studio Analyzer Project Wizard, you must select the components, or rather group of components, from which you want to collect events, as shown in Figure 14-7. By default, all registered event sources are selected, but you can deselect any of them. You need to select at least one of the components. This step is repeated for each Visual Studio Analyzer server you've added in the first step. Click Next to proceed to step 3 of the wizard.

    Click To expand
    Figure 14-7: Visual Studio Analyzer Project Wizard, Step 2

  3. In the third step of the Visual Studio Analyzer Project Wizard, you can select one or more of the predefined collection filters, as shown in Figure 14-8. Collection filters are used by Visual Studio Analyzer to decide which events are generated and collected. By default, all of the predefined collection filters are selected, but you can deselect any of them. In the next section, you'll learn how to use custom collection filters. Click Next to proceed to the summary part of the wizard.

    Click To expand
    Figure 14-8: Visual Studio Analyzer Project Wizard, Step 3

  4. Click Finish to start the event filtering and collection on the selected Visual Studio Analyzer server or servers. The Visual Studio Analyzer event recording/collection dialog box appears, as shown in Figure 14-9.

    Click To expand
    Figure 14-9: Visual Studio Analyzer event recording/collection dialog box

The Visual Studio Analyzer event recording/collection dialog box gives you an overview of when the recording was started, the name of the event log in which the events are stored, and so on. You can also use this dialog box to pause and resume, or stop the event recording/collection, as described in the "Stopping and Starting Event Collection" section, later in this chapter.

[2]IP addresses don't seem to work, although you can connect using them.


Using Collection Filters

As noted in the previous section, collection filters are used by Visual Studio Ana lyzer to decide which events are generated and collected. Collection filters are set up on the client. Basically, a collection filter holds information about which machine, which component on the machine, and which event of the component to filter. Visual Studio Analyzer evaluates this collection filter as an expression, meaning it compares the information in the event source with the collection filter; if they match, an event is generated and subsequently collected by the Visual Studio Analyzer client.

For example, a collection filter can filter object activation events for COM components. Events are generally grouped in categories, making it easier to nav igate and find your events. The Object Activation category, for instance, holds the Object Activate and Object Deactivate events.

As you saw in the previous section, the Visual Studio Analyzer Project Wizard in the VS .NET IDE comes with some predefined collection filters, ready for you to use. However, in most cases, you'll probably want to create your own col lection filters. Or, you may choose to customize the predefined collection filters once you've added them to your project, without making changes to the pre defined filter templates.

Note

There are two kinds of filters with Visual Studio Analyzer: the collection filter and the view filter. View filters are used to filter the events that have been collected and stored in the event log on the Visual Studio Analyzer client. They work the same as the filters you can use in the Windows Event Viewer application.

When you have a Visual Studio Analyzer project, you can manipulate your collection filters in various ways. You can add predefined filters, create custom ones from scratch, edit existing filters (predefined or custom), or remove existing filters from your project.

Once you've created and/or modified your filters on the Visual Studio Analyzer client, which in our case is in a VS .NET project, they're pushed to the Visual Studio Analyzer server when you start the event recording/collection, where the event sources described in the filters are registered and activated. The generation and collection of events is a continuous process that stops only when you stop the recording/collection. Once the event generation and collection is stopped, the events stored in the event log can be analyzed.[3]

Adding a Predefined Filter

To add a predefined filter to your project, select the Filters node in the Solution Explorer, and then use any of the following methods:

  • Select File® Add New Item or press Ctrl-Shift-A to open the Add New Item dialog box, with the predefined filter templates.

  • Right-click the Filters node in the Solution Explorer and select Add New Item menu from the pop-up menu.

  • Right-click the Filters node in the Solution Explorer and select the predefined collection filter from the Add Predefined Filter submenu of the popup menu.

    Note

    The Templates pane of the Add New Item dialog box will also hold templates other than the predefined collection templates.

Adding a Custom Filter

Instead of using a predefined filter, you can create your own filter from within the VS .NET IDE. To add a custom filter, select the Filters node in the Solution Explorer, open the Add New Item dialog box (using either of the methods described in the previous section), and select the Filter template. Alternatively, right-click the Filters node in the Solution Explorer and select Add Filter.

You will see the Edit New Filter dialog box, shown in Figure 14-10, in which you can select the servers, components, and categories/events to filter.

Click To expand
Figure 14-10: Edit New Filter dialog box
Start Sidebar
Deciding Which Components and Events to Analyze

It can be hard to decide which components to analyze, and within each component, you need to decide which events you want to analyze. In general, it makes sense to analyze your own distributed components during the development and/or testing phase. However, you might be using third-party COM components, and they also might not behave as expected.

Obviously, you don't have the source code for any third-party components, but you might find that one or more components is spending too much time executing a particular event, in which case, you might want to talk to the vendor, or you might just want to try out a similar component from another vendor. Now, the latter is a serious move, unless it's done early in the development phase, because it can have all sorts of implications on other parts of your solution.

Okay, third-party components aside, what about your own components and events—which do you analyze?

If you're new to Visual Studio Analyzer and it's your first test run, you should analyze whatever you feel you have the time to analyze. Visual Studio Analyzer is an excellent product that can be used for analyzing many different events, and you really need to get a feel for using it—it's not enough to read about it. Once you've done your test runs, you might have an idea of which components and/ or events to analyze.

As an overview of which type of events we generally recommend for analysis, consider the following actions, which always have an impact on performance:

  • Calls across the network (internal as well as external)

  • Database connections

  • Disk read and write operations

  • Complex math calculations, including creating heavy graphics

  • Memory-hogging operations

End Sidebar

Editing a Filter

You can edit any of the filters in your project, whether they are custom or predefined. To open the Edit Filter dialog box, select the filter to edit in the Solution Explorer, right-click it, and select View Filter Editor (or select View ® View Filter Editor). In the Edit Filter dialog box, select the server or servers, component or components, and categories/events to filter.

In the Edit Filter dialog box, which looks just like the Edit New Filter dialog box (see Figure 14-10), you can only select from the various lists. If you're experi enced with collection filters, you might want to use the text editor instead. It's much the same as creating your SQL statements in plain text instead of using say the Query By Example (QBE) window in Microsoft Access. If you click the Edit Text button in the Edit Filter dialog box, the editor changes to a plain text editor. You can also open the text editor for filters by selecting the filter to edit in the Solution Explorer, right-clicking, and selecting View Filter Text, or by choosing View ®View Filter Text.

Removing a Filter

You can remove any filter in your project, in the same way that you delete any other project item. Simply select the filter in the Solution Explorer, and then perform any of the following actions:

  • Select Edit® Remove.

  • Press Delete.

  • Right-click the filter in the Solution Explorer and select Remove from the pop-up menu.

When you choose to remove a filter, you'll be asked whether you want to remove the filter from the project only, or if you want to permanently delete the filter.

[3]Actually, the event log can be viewed at any time, but in most cases, it makes sense to wait until after the collection/recording has been stopped.


Starting and Stopping Event Collection

After setting up a Visual Studio Analyzer project, you need to start collecting events for any of the defined filters, and stop it once you have collected the amount of data you want to analyze.

Starting Event Collection

When you run the Visual Studio Analyzer Project Wizard, event collection is started automatically after you click Finish on the last page of the wizard. However, you can also start the collection manually using either of these methods:

  • Select Analyzer ® Start Recording.

  • Click the Start Event Recording button on the Analyzer toolbar.

This brings up the Visual Studio Analyzer event recording/collection dialog box (see Figure 14-9). However, you need to set the recording filter before any event collection is performed. You can choose to do this before opening the Visual Studio Analyzer event recording/collection dialog box, in which case, the collection is started as soon as the dialog box appears.

To set the recording filter (before or after opening the event recording/collection dialog box), select the filter you want to use in the Solution Explorer, right-click, and select Set Record Filter (or select Analyzer ® Set Record Filter).

Note

You can collect and record events for only one filter at a time.

Stopping Event Collection

When an event collection is running, you should stop it once you've collected the desired amount of data to analyze. You can stop event collection in one of the following ways:

  • Select Analyzer ® Stop Recording.

  • Click the Stop Recording Events button in the Visual Studio Analyzer event recording/collection dialog box (see Figure 14-9).

  • Click the Stop Event Recording button on the Analyzer toolbar.

When you stop an event collection, the Visual Studio Analyzer event recording/ collection dialog box is closed. Then you can start analyzing the data, as described in the "Analyzing Data" section later in this chapter.

Note

When you stop event collection, the event log in which the events are stored is closed. This means that any new event collection will be saved to a new event log. This is in contrast to what happens when you pause an event collection and then resume it. When you pause an event collection, the events are still stored to the same event log when you resume the collection.

Pausing and Resuming Event Collection

When an event collection is running, you can pause it. For example, there might be too much temporary traffic on the network you're accessing, the server may be temporarily overloaded, or you may simply want to collect the events at certain intervals.

To pause event collection, use one of the following methods:

  • Select Analyzer ® Pause Recording.

  • Click the Pause Recording Events button in the Visual Studio Analyzer event recording/collection dialog box (see Figure 14-9).

  • Click the Pause Event Recording button on the Analyzer toolbar.

When an event collection is paused, you can resume it by selecting the same button or menu item you used to pause the event collection.


Analyzing Data

After you have run and stopped an event collection/recording, it's time to analyze the data collected. You can use various view filters, view the data in the event log, and view predefined diagrams (machine, process, and component).

View filters are used to filter the events that have already been collected and stored in the event log on the Visual Studio Analyzer client. To add a view filter to an event log, opening the desired event log in the Solution Explorer, right-click the filter you want to apply to the event log, and select Apply Filter to View from the pop-up menu.

Viewing the Event Log

The event log gives you the most detailed view of the events collected, and you can view it by double-clicking it in the Solution Explorer or by right-clicking the event log and selecting the Event List menu item from the pop-up menu. This brings up the Visual Studio Analyzer Event List, as shown in Figure 14-11.

Click To expand
Figure 14-11: Visual Studio Analyzer Event List

In Figure 14-11, you can see the Event List for a filter applied to the Visual Studio Analyzer server ESBJERG. The Event List shows which events have occurred, which server they occurred on, at what time, and the duration of the event. You can also see the source and target server, source and target component, source and destination session, and source and target process (not shown in Figure 14-11).

But how can you actually use this information? One of the most important items you can see in the Event List is the duration of the event. This will help you decide if further debugging is needed for a component that seems to be spending too much time executing one or more events.

If you need further details for any event on the list, simply double-click it to see a detailed list of event attributes and values.

Start Sidebar
What Is Too Much Time for a Component to Spend?

What is too much time, or what is the acceptable level of performance, for a component? Well, that is hard to figure out, and there really aren't general ballpark figures for you to use. It obviously depends on many factors, such as network traffic, network bandwidth, network congestion, and the load on the server hosting the component.

However, your organization might establish some baseline values for certain components and/or events that you can use. Establishing baseline figures for accessing a database, creating local and remote objects, writing to disk, and other general activities is the way forward, because then you have some figures you can compare with the analysis done by Visual Studio Analyzer.

When you find out that an event, or perhaps all events in a component, is spending too much time executing, you need to actually debug your component. Check your documentation for information about how to use the debugger (and possibly the remote debugger, if the component is located on a remote server).

End Sidebar

Viewing Server, Process, and Component Interaction Diagrams

Some diagrams can assist you at a high level, to understand the interaction of the servers (referred to as machines), processes, and components. These diagrams give you a view of the servers, process, or components, and you can replay the events collected/recorded and see the events in an animated sequence.

To select a diagram, select the event log in the Solution Explorer, right-click, and select the diagram you want to see. Alternatively, select the desired diagram menu item from the View ® Analyzer menu. Figure 14-12 shows a process diagram, displayed by selecting View ® Analyzer ® Process Diagram.

Click To expand
Figure 14-12: Process diagram

The process diagram in Figure 14-12 shows three processes on the machine ESBJERG. You can see which events occur between the processes. At the time this figure was shot, the ComponentStop event occurred on the machine ESBJERG within the same process (1876). This means that two threads are communicating within the same process. There's another process shown on the diagram: the COM+ application (4044).


Summary

In this chapter, we looked at the Visual Studio Analyzer, a tool designed to analyze the performance of your distributed applications. You learned how to filter and collect events, and then analyze the collected events.

In the next chapter, we'll look at VS .NET deployment, including the various setup projects provided by VS .NET.


Chapter 15: Deploying Your Applications

Overview

In this chapter, you'll learn how to use VS .NET for deploying your applications. Deployment is the process where you copy your solution to or install your solution on other machines. Generally, deployment is one of those often-overlooked areas of the software development process. In many organizations, it's out there with testing—a task that will be performed after you finish the development, time per mitting.[1] But you now know that deployment (and testing) should be part of the overall project, and you should start planning it when you plan the development. We're not saying that you should start building deployment projects as soon as you start developing, but you should have an idea of what to deploy and to where.

Deployment and ongoing management is actually one of the six goals of the MSF Team Model that must be fulfilled for a project to be considered successful. It's also the task of the Logistics Manager. Deployment is part of the physical design, and you can find more information about physical design and planning deployment in Chapters 2 and 20.

Of course, if an application consists of just an executable, and no component registrations are needed on the target machine, it's simple to deploy that appli cation. However, this is hardly true for most applications these days, especially enterprise applications. Enterprise applications consist of many smaller units (components, assemblies, modules, and so on) that are often placed on different machines, depending on the physical design. In these cases, you often need a cen tralized deployment. That's what this chapter is all about: the various deployment options offered by VS .NET. Most of this chapter is about manual deployment, but we'll look at automated deployment functionality toward the end of the chapter.

[1]It's possible, although obviously very unwise, to ship without testing. However, you can't decide not to deploy an application, unless you kill it; you can only deploy it badly.


An Overview of VS .NET Deployment

VS .NET offers many deployment choices, ranging from a simple file-copy operation to automated setup applications. Knowing the methods available to you allows you to choose the right one for the job.

In this section, we'll provide an overview of the types of deployment packages available, properties, and editors used in the process.

Note

In this chapter, we refer to applications and setup and deployment projects that use VB .NET or C# as the programming language only; we do not cover C++ or any other programming language. We do, however, look at how to deploy COM components as well as .NET assemblies.

Types of Setup and Deployment Projects

VS .NET commonly refers to deployment packages as setup and deployment projects. A setup and deployment project should be added to an existing solution. Although it's possible to create a setup and deployment project in a blank solution, it doesn't make sense in most cases. This is because you want to add the output from at least one other project, and be able to easily discover and include the output files from that project.

In Figure 15-1, you can see the Setup and Deployment Projects category in the Add New Project dialog box (right-click the solution file in the Solution Explorer and select New Project from the pop-up menu or select File® Add Project ® New Project to open this dialog box). In the Add New Project dialog box, expand the Setup and Deployment Projects node in the Project Types list to see the various setup and deployment projects.

Click To expand
Figure 15-1: VS .NET Setup and Deployment Projects

In the Templates pane of the Add New Project dialog box, you can see all of the deployment projects offered by VS .NET (the New Project dialog box offers the same project type options), and yet this isn't quite true. You also have the simplest option: a simple file-copy operation to the target machine, called XCOPY, for the old DOS and command-line utility used to copy more than one file and folder at a time. Table 15-1 provides a summary of the VS. NET setup and deployment projects.

Table 15-1. VS .NET Setup and Deployment Options
Name | Description | Typical Use
XCOPY | Simplest of the setup and deployment choices—a manual file-copy operation to the target machine. However, it can be used in batch and script files. | Smaller applications requiring no registration, deployed to a single target machine.
Setup Project | Used to deploy Windows applications to machines with Windows installed. | For deploying Windows appli cations to Windows platforms with the Windows Installer installed. You can optionally include a link to where the Windows Installer files can be downloaded from, or include them as part of the setup.
Web Setup Project | Used to deploy Web applications to machines with Windows installed. | For deploying Web applications to Windows platforms with the Windows Installer installed. You can optionally include a link to where the Windows Installer files can be downloaded from, or include them as part of the setup.
Merge Module Project | Used for creating modules to be shared by other setup projects. This type of project cannot be installed separately; it must be part of a setup project. | If you have one or more assemblies, components, etc. you want to share between two or more projects, you can add them to a Merge Module Project, and then add the project to the setup projects in which you want to use the content of the merge module.
Setup Wizard | Used to help you select the appropriate deployment package. | If you're unsure of which deployment package to choose, use the Setup Wizard.
Cab Project | Used to package ActiveX controls to be downloaded directly from a Web server to a Web browser. | Use this project for simple download and installation of ActiveX controls in any Web browser that supports ActiveX controls.
Web Project Copy | A simple copy operation directly to the target Web server from within the VS .NET IDE. | Used with Web projects only.

Project Properties

Although the VB .NET setup and deployment projects help you with many tasks, you must still set some project properties manually. You can set properties by using the various editors, the Properties window, and the Property Pages dialog box. We'll take a closer look at the editors in the next section, "Setup Project Editors."

There are two types of properties: the general project ones and the configuration-specific ones. The project-specific properties for a setup project are handled much the same way as properties for any other type of project, and they're accessed through the Properties window, which is shown in Figure 15-2. Open the Properties window by pressing F4. The Properties window shows the general properties for any element currently selected in the VS .NET IDE. In this example, it's the Setup1.vdproj file, selected in the Solution Explorer.

Click To expand
Figure 15-2: Properties window

The configuration-dependent properties are, as the name implies, dependent on the current configuration. A configuration generally relates to if you want to run/deploy a debug or release version of your solution. You can see the configuration-dependent properties in the Property Pages dialog box, which you can open in any of the following ways:

  • Right-click the setup project's project file in the Solution Explorer and select Properties from the pop-up menu.

  • Select the setup project's project file in the Solution Explorer and press Shift-F4.

  • Select the setup project's project file in the Solution Explorer and select View ® Property Pages menu.

  • Select the setup project's project file in the Solution Explorer and select Project ®Properties.

  • Select any item of the setup project except the project file in the Solution Explorer, and then select Project ® <ProjectName> Properties.

Figure 15-3 shows the configuration-dependent properties for the current configuration for a setup project. As you can see, the current (active) configu ration is Debug. You can select the configuration from the Configuration list in the upper-left corner of the dialog box.

Click To expand
Figure 15-3: Property Pages dialog box for a setup project showing configuration- dependent properties
Tip

If you don't have different property settings for your different configurations, select All configurations from the Configuration list in the Property Pages dialog box.

Setup Project Editors

All of the setup and deployment projects, except for the Cab Project, make use of some editors for setting the properties of the project. In this section, we introduce each of these editors. We'll be referring to these sections in the remainder of the chapter, so feel free to skip this section, if you want to go straight to a specific deployment section, such as "Deploying Windows Applications" or "Deploying ASP.NET Applications." However, you might just want to read on, because you'll get a good understanding of general VS .NET deployment packaging.

File System Editor

For all of the VS .NET deployment projects, you need to specify which files to copy to the target machine. The File System Editor, shown in Figure 15-4, is used for specifying the files—such as standard project outputs, assemblies, and any other file—to be copied onto the target machine. The File System Editor is auto matically shown when you create a new setup and deployment project. However, if you close it, you can open it by right-clicking the setup and deployment project in the Solution Explorer and selecting View ® File System from the pop-up menu, or by selecting the setup and deployment project in the Solution Explorer and selecting View ® Editor ® File System.

Click To expand
Figure 15-4: File System Editor

Basically, you use the File System Editor to do the following:

  • Identify which files to copy as part of your setup and deployment project.

  • Specify where to put the files on the target machine, including if a folder should be created if it doesn't exist.

  • Specify which conditions, if any, must be satisfied for the file to be copied.

Let's take a look at the various folders and conditions for file installation and folder creation.

Note

The various setup and deployment projects will help you with determining which files to copy, but there are instances where you need to step in manually, such as when one COM component relies on another COM component. We'll look at this in the "Deploying Windows Applications" section later in this chapter.
Target Folders

The target folders are the folders that either exist or will be created on the target machine. This includes system folders, such as the Program Files folder, and application-specific folders. In Figure 15-4, you can see the folders most frequently used in a setup and deployment project: Application Folder, User's Desktop, and User's Programs Menu. However, there are many more system folders that you can add. To see the list of system folders, or special folders as they're called in VS .NET terminology, right-click the File System on Target Machine node in the navigation pane of the File System Editor.

Click To expand

Besides the special folders, you can also add custom folders, if your appli cation needs to place files in application-specific folders on the target machine.

The list of special folders includes all of the most common Windows folders, and certainly the ones you need when installing your applications. These special folders help you focus on the deployment at a higher level, not bothering with the actual file location on the target machine. This means that you don't need to know what the main Windows folder is called and where it is placed on the target machine, where the Program Files folder is located, or even where the current user's desktop is located. The setup and deployment executable will locate these for you, by looking them up in the Registry on the target machine.

The actual content of the folders you deploy on the target machine can vary, but Table 15-2 shows some of the most common file-to-folder deployments. The files listed in Table 15-2 can be placed in alternative locations, if you wish; the table merely provides suggestions for common applications.

Table 15-2: . File-to-Folder Deployment
File | Folder | Description
Main executable | Application folder | This file should always be put in the application folder, where it's safe[a] from being accidentally overwritten by another setup application.
Configuration files | Application folder | Generally, configuration files, such as XML-based .config files or simple text files, should be placed in the appli cation folder with the main executable or a subfolder of the application folder. Exceptions to this are when you have configuration files that hold infor mation applicable to more than one application, in which case, you need to find a common folder, such as Common Files Folder\Company Name.
Shared assemblies | Global Assembly Cache folder | This really is the only place to put shared assemblies. Otherwise, you need to know the exact path of the assembly when using it from your application.
Non-shared assemblies | Application folder | Non-shared assemblies should be put in the application folder with the main executable. The exception here is satellite assemblies that must be put in specific subfolders of the application folder.
Graphics files | Application folder | If images and other graphics aren't retrieved from a database or a URL, they should be placed in the appli cation folder. It's common to create a subfolder in the application folder, and possibly subfolders to this folder, to host the graphics files. This depends on the amount of graphics files; a few can easily be placed in the application folder, whereas a handful or more will make it difficult to locate the files.
Shortcuts | User's desktop | Shortcuts are often placed on the user's desktop and on the Start menu, but it's good to ask the user if a shortcut should be installed.
[a] Well, at least in theory, until someone with a less-than-decent setup does it anyway.

Another consideration is where to put the application folder—should it go in the default Program Files folder or elsewhere? The default is a good place for most applications, but keep in mind that some companies may want to have all their applications installed in subfolders within a single "company" folder.

Note

If you need to delete a target folder, select it in the navigation pane of the File System Editor and press the Delete key, or select Edit ®Delete. You can delete only empty folders, so if you've placed files in a folder, you need to remove these first, by selecting them and pressing the Delete key.

Conditions

When you specify which files to deploy or folders to create, you also have the option of specifying certain conditions to be met for the file to be installed or folder to be created. The condition for a file or folder is specified using the Condition property, which can be accessed through the Properties window, once the file or folder is selected in the File System Editor.

You can specify the following types of conditions:

  • Property values exposed by any other element in the installer at installation time

  • Custom properties specified for custom folders (only custom folders can have custom properties)

  • Properties exposed by the Windows Installer

For example, you can specify that you want to install a file or create a folder on only a specific operating system, such as Windows XP.

Tip

You can find more information about Windows Installer properties, such as date/time and hardware, at http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/msi/setup/ property_reference.asp. Conditions can be complex, and they can be constructed from several Boolean statements. You can find the statement syntax at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/conditional_statement_syntax.asp.

File Types Editor

The File Types Editor is a fairly simple one, and it's easy to work with, especially if you have ever tried associating various file types (such as .jpg, and .gif) with a specific application using a Windows operating system. In Figure 15-5, you can see the various file types registered on a Windows system and their associated applications.

Click To expand
Figure 15-5: File types in the Windows Folder Options dialog box

Association is the key word here, because that's what you do with the File Types Editor: you associate one or more file types with a specific application. This generally means that if you double-click a file of a type that has been asso ciated with an application, it will be opened in that specific application. In general, you need to use the File Types Editor only if you plan on introducing new file types that must be opened by your application. However, sometimes you have several applications that can open the same file types, and if your deployed application hooks into or depends on one of these, you might want to make sure that this file type is opened with the application of your choice.

To open the File System Editor, right-click the setup project's project file in the Solution Explorer and select View ® File Types. There are no file type associ ations specified here by default. To add an association, right-click the root node (File Types on Target Machine) and select Add File Type from the pop-up menu. This adds a new file type with a default name and one action/verb, Open, as shown in Figure 15-6.

Click To expand
Figure 15-6: File Types Editor

After you add a new file type, you need to change the file type name, which is done in any of the following ways:

  • Select the file type in the File Types Editor and click the file type once more.

  • Select the file type in the File Types Editor and press F2.

  • Select the file type in the File Types Editor, right-click the file type, and select Rename from the pop-up menu.

In most cases, an association means that the associated application opens the file. However, this isn't always the case. If you need to add more actions/verbs, right-click the file type and select Add Action from the pop-up menu.

Tip

You can read more about actions/verbs and file associations at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/ programmersguide/shell_basics/shell_basics_extending/ fileassociations/fa_verbs.asp.

Registry Editor

As you probably know, the Registry is a hierarchical database repository for infor mation about a computer's configuration, including the applications installed on it. In general, the Registry contains information such as user profiles and hardware. The Registry also contains information about the programs installed on your computer and the types of documents that each can create. The Registry is made up of hives (root nodes), keys, and values.

The Registry Editor, shown in Figure 15-7, is used for adding any Registry key and/or value to the Registry on the target machine. All of the Registry hives are already created for you to add your own custom keys and values to (you can't create your own hive).

Click To expand
Figure 15-7: Registry Editor

The first four hives correspond directly to the hives in the user's Registry. The last one, the User/Machine Hive, corresponds to the HKEY_CURRENT_USER or the HKEY_USERS hive. Keys and values in the User/Machine Hive deployment hive are stored in either of these Registry hives at installation time, depending on whether the user selects Just Me (to make the application available to the current user) or Everyone (to make the application available to all users on the system) during the installation.

The Registry Editor looks and feels much like the Registry editor on your Windows setup (if you use Regedt32.exe). If you have any experience manipu lating the Registry, you'll have an easy time using the Registry Editor.

Tip

If you need to know more about the Registry, here's a document worth checking out: http://www.microsoft.com/windows2000/en/advanced/help/under_stand_reged.htm.

User Interface Editor

You can manipulate the interface exposed to the user—the dialog boxes—at installation time in a number of ways using the User Interface Editor. To open this editor, right-click the setup and deployment project in the Solution Explorer and select View ® User Interface from the pop-up menu, or select the setup and deployment project in the Solution Explorer and select View ® Editor ® User Interface. As you can see in Figure 15-8, the User Interface Editor groups a number of dialog boxes into categories/stages and two different installation types.

Click To expand
Figure 15-8: User Interface Editor
Note

You can't edit the various dialog boxes directly; you can only edit the text displayed in them.

The two types of installations are Install and Administrative Install. The Install type is for a standard installation when a user runs the setup. The Administrative Install type is for when an administrator uploads the setup to a network location, so that the end user can run the setup from that location. Basically, the Adminis trative Install type is for the administrator to set some default properties for the standard setup, such as the location (path or URL).

If you want to specify some properties that must not be overridden by the end user, you can do so by removing the dialog box that accepts input for this property from the standard installation, and have this dialog box appear only in the administrative installation. Both of the installation types are divided into three stages, which correspond to the stages the user goes through when installing an application:

  • Start: The startup, when you accept a license agreement, enter user information, application location, and so on.

  • Progress: The progress, where you can see the installation progress, such as the file being copied, registered, and so on.

  • End: The end, when you finish the installation. Generally, this means displaying a dialog box indicating that the installation has finished (whether successfully or not).

You can change the order in which the dialog boxes in a stage are displayed to the user by right-clicking a dialog box and selecting Move Up or Move Down from the pop-up menu. Alternatively, you can use drag-and-drop.

Note

It's not possible to move a dialog box from one stage to another using the pop-up menu; you must drag-and-drop a dialog box between the stages. A move cannot be undone, except by manually moving the dialog box back where it was originally.

You can't create new stages/categories, nor can you create new dialog boxes for any of the three stages. However, you can add predefined dialog boxes to the stages. To add a dialog box, right-click a stage and select Add Dialog from the pop-up menu. You'll see the Add Dialog dialog box, as shown in Figure 15-9.

Click To expand
Figure 15-9: Add Dialog dialog box

The content of the Add Dialog box changes depending on which installation type you have invoked the dialog box for and which dialog boxes already exist for the stage. In Figure 15-9, the Add Dialog box has been invoked for the Start stage of the standard installation (Install) type, with the default dialog boxes already added.

We'll look at some of the customizations you can perform with the User Interface Editor, including changing the text and graphics for the dialog boxes, in the "Customizing Setup Projects" section later in this chapter.

Custom Actions Editor

The Custom Actions Editor, shown in Figure 15-10, helps you add custom actions to your setup. To open this editor, right-click the setup and deployment project in the Solution Explorer and select View ® Custom Actions, or select the setup and deployment project in the Solution Explorer and select View ® Editor ®Custom Actions.

Click To expand
Figure 15-10: Custom Actions Editor

But what are custom actions? They are anything you want—anything you can't do with any of the other editors, such as creating a database or text file, or displaying a specific Web page at the end of the setup. But before you add a custom action, you need to decide in which phase/stage of the installation the actions should occur:

  • Install: Add custom actions to this phase when you want them executed directly after the copying of the files has finished. If you want your action to be executed only when the setup finishes successfully, you should add your action to the Commit phase/stage.

  • Commit: You should add your action to this phase when you want the action to be taken once the setup has finished successfully. If you want the action to be taken at the end of the setup, regardless of whether or not the setup finished successfully, add your action to the Install phase.

  • Rollback: This phase should be used for your custom actions when you want the action taken when a rollback of the setup has finished. A rollback can be triggered by the user canceling the setup or by an installation error.

  • Uninstall: This is really a separate phase that is run only when the user decides to uninstall your application. In general, you should add custom actions that perform the opposite of the actions you have added to the Install and/or Commit phases, such as removing a database that was created.

You can create any kind of custom action you like, but the action must be compiled into a DLL or EXE file, or created as an assembly or a script (VBScript or JScript). You add an action by right-clicking a phase and selecting Add Action from the pop-up menu. This brings up the Select Item in Project dialog box, as shown in Figure 15-11.

Click To expand
Figure 15-11: Select Item in Project dialog box

As you can gather from the name of the dialog box, you add an item from the setup project. So, does this mean that it must have been added to the setup project prior to this action? No, not really. You can add existing files, output, and assemblies, using the buttons on the right side of the Select Item in Project dialog box. These buttons are enabled once you select the folder (Application Folder, User's Desktop, or User's Program Menu) from which to select the file, output, or assembly. If you choose to add an action contained in a file, output, or assembly that hasn't been added to the setup project, it's automatically added to the setup project in the selected folder once you add the action contained in it.

Launch Conditions Editor

The Launch Conditions Editor, shown in Figure 15-12, helps you create conditions for the setup to launch. In other words, you can set up custom or predefined con ditions that must evaluate to true for the application setup to run successfully. To open the Launch Conditions Editor, right-click the setup and deployment project in the Solution Explorer and select View® Launch Conditions, or select the setup and deployment project in the Solution Explorer and select View ® Editor ®Launch Conditions.

Click To expand
Figure 15-12: Launch Conditions Editor

The Launch Conditions Editor deals with requirements that must be met on the target machine. This can be a predefined launch condition or a search for a file, a Registry key/value, or a Windows Installer package on the target machine.


The Microsoft Windows Installer

What is the Microsoft Windows Installer? The Windows Installer is an installer service technology that can be used by any application package for deployment on the Windows operating system.

Note

For more detailed technical information about the Windows Installer, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsintro7/html/ vbconwhatyouneedtoknowaboutmicrosoftwindowsinstaller.asp.

The deployment tools in VS .NET build on the Windows Installer service, and in particular version 2.0. This version is automatically included on Windows XP[2]and Windows Server 2003 systems, but not on earlier versions of Windows. Most likely, version 1.1 is installed on earlier versions on the Windows operating system, unless it has been downloaded using Windows Update or another setup has installed it.

So, you really need to make sure that version 2.0 of the Windows Installer is installed on the target system before you install your application. One way to do this is to provide your users with a link to the official download site: http://www.microsoft.com/downloads/details.aspx?FamilyID=cebbacd8-c094-4255-b702-de3bb768148f&displaylang=en.

Another way to make sure that Windows Installer 2.0 is installed is to modify the Bootstrapper option of the Property Pages dialog box. (To open the Property Pages dialog box, right-click the setup and deployment project in the Solution Explorer and selecting Properties, or select the setup and deployment project in the Solution Explorer and select Project ®Properties.) The Bootstrapper option has three values:

  • None: Your deployment package will not be bootstrapped.

  • Windows Installer Bootstrapper: Your deployment package will be bootstrapped for installation on a Windows computer.

  • Web Bootstrapper: Your deployment package will be bootstrapped for Web download. The bootstrapper includes authentication for safe downloading.

    Note

    If you include the .NET Framework as part of your deployment package, you also automatically ensure that Windows Installer version 2.0 is installed on the target system. See the "Including the .NET Framework" section later in this chapter for more information.

If you're creating a Web download and you select the Web Bootstrapper value for the Bootstrapper option, the Web Bootstrapper Settings dialog box opens. In this dialog box, you can specify two URLs:

  • Setup folder URL: Specifies a folder where the setup and associated files are located. You can also place the executable Windows Installer files in this folder, and thus make sure the target system is automatically updated to the correct Windows Installer version when you run setup.

  • Windows Installer upgrade folder URL: This optional text field is used for specifying a folder that contains the executable Windows Installer files. You don't need to specify this value if you have placed the files in the folder specified with the Setup folder URL text field.

[2]SP2 for Windows XP, scheduled for release mid-2004, will include version 3.0 of the Windows Installer.


Deploying Windows Applications

In this section, we'll look at the steps for deploying a Windows application. We'll cover how to add a setup project to your solution, add files to the setup project, and customize the deployed items. The related topics of handling .NET Framework issues, implementing security, customizing a setup project, and versioning are covered later in this chapter.

For the Exercises in this section, we've created a sample Windows solution named WindowsDeploymentProject, to which you can add your setup project. It's a simple application with just a single Windows form containing a button that changes a few properties when clicked.

You can find the solution in the accompanying sample code, which can be downloaded from the Apress Web site (http:\\www.apress.com). The sample solution is in the Chapter 15\WindowsDeploymentProject folder, and the solution with all of the Exercises performed is in the Chapter 15\WindowsDeploymentProject2 folder.

The WindowsDeploymentProject sample application contains the following items, as shown in Figure 15-13.

Figure 15-13: WindowsDeploymentProject project items

  • COMTest.dll COM component created in VB 6

  • Various .NET Framework assemblies

  • TestAssembly1 .NET component

  • 1590590422.jpg picture of the book cover

  • app.config application configuration file

  • AssemblyInfo.vb assembly information file

  • Form1.vb Windows form

  • Form1.resx neutral culture (en-US default culture) resource file

  • Form1.da.resx Danish culture resource file

All of the files listed play a part in what is deployed, but there is also one file that isn't part of the project, Author.jpg, which is loaded at runtime, and an assembly that's referenced by another assembly, TestAssembly2.dll.

You can't run the sample application from your development environment without runtime errors. This is due to the location of dynamically loaded files that will be placed correctly when the application has been deployed.

Adding a Setup Project to the Solution

Your first step is to add a setup project to the solution, but which type of setup project should you choose? The Setup Project project is the obvious choice for deploying a Windows application, and it's also the only project that can be run directly from Windows Explorer.[3]

In Exercise 15-1, you'll add a setup project to your existing solution.

Exercise 15-1
Start example

  1. Open the WindowsDeploymentProject solution/project in VS .NET.

  2. Right-click the solution file in the Solution Explorer and select New Project from the pop-up menu.

  3. In the Add New Project dialog box, expand the Setup and Deployment Projects node in the Project Types list to see the various setup and deployment projects.

  4. Choose Setup Project, and then add a setup project named DeploymentProject to the solution.

End example

At this stage, you can actually build your setup project, but it would be pointless, because there's nothing in it. You need to do a few things manually first, and it starts with determining which files to copy. You know that the executable assembly from your Windows application needs to be copied across to the target machine, but what other files do you need to include? The next section answers that question.

Adding Files to a Windows Setup and Deployment Project

When you need to add files from your application project to your setup and deployment project, you can rely on VS .NET to help you out. Let's take a look at which files you need to copy:

  • Project output: The output from your application project, usually an executable assembly.

  • Referenced assemblies: All the assemblies referenced in your application project.

  • Satellite assemblies: Assemblies for multiculture applications.

  • Referenced COM components: Any COM components, including ActiveX components.

  • Configuration files: Any XML-based configuration files, as well as any text files used for configuration of your application.

  • Graphics files: Any graphics files dynamically loaded at runtime. Only dynamically loaded graphics should be included; any other files are already part of the project output.

  • Miscellaneous files used by your application: Any other files your application depends on.

Let's use the list as a reference point, keeping in mind that we haven't listed all possible types of files that you might need to deploy with your application (hence, the miscellaneous files item).

Adding Windows Project Output

The project output in our example is the executable assembly, WindowsDeploymentProject.exe. To add it to the setup project, right-click the Setup and Deployment Project in the Solution Explorer and select Add ® Project Output. Alternatively, select the Setup and Deployment Project in the Solution Explorer and select Project ® Add ® Project Output. This brings up the Add Project Output Group dialog box, as shown in Figure 15-14.

Click To expand
Figure 15-14: Add Project Output Group dialog box

The Add Project Output Group dialog box includes five categories of project output:

  • Primary output: This is the assembly (EXE or DLL) created when building the project.

  • Localized resources: This refers to any satellite assemblies that your application uses for localization.

  • Debug Symbols: This category covers the debugging files (.pdb) in your project.

  • Content Files: This covers all files marked with the Content for the Build Action property. It's typically used for files that aren't compiled as part of the primary output, such as graphics files loaded dynamically.

  • Source Files: This includes all files marked with the Compile for the Build Action property, as well as the project file (.vbproj or .csproj), and the application configuration file (app.config).

You begin by adding the primary project output to the setup project.

Detecting Windows Project Dependencies

When you add the primary project output to the setup project, VS .NET tries to detect the dependencies the project output has. VS .NET cannot detect any refer ences your COM components might have. You must add those manually. However, any references in an assembly are automatically detected and added to the dependencies list in the setup project.

If you have COM components with references that VS. NET can't detect, you'll see a message to that effect. Basically, this is a situation where you need to know if any COM components used directly by your application have any references to other COM components or any other files that are needed at runtime. If you're familiar with programming in VB 6 or earlier, you know that dependencies also depend on the presence of the VB runtime on the target machine. This is true whether the EXE or DLL was compiled to P-code or native code.

You can add the required files to your setup project through the Add Files dialog box (right-click the Setup and Deployment Project in the Solution Explorer and select Add ®File, or select the Setup and Deployment Project in the Solution Explorer and select Project® Add ® File).

VS .NET does detect any references your .NET assemblies might have and adds them to the list of dependencies. Figure 15-15 shows the dependencies detected after adding the application executable for our sample Windows application:

Figure 15-15: DeploymentProject detected project dependencies

  • comtest.dll, the original COM object

  • dotnetfxredist_x86.msm, the Microsoft .NET Framework merge module

  • Interop.COMTest.dll, the COM Interop assembly for COMTest.dll, making it accessible to a .NET application

  • TestAssembly1.dll, the .NET assembly added as a reference to the project

  • TestAssembly2.dll, a .NET assembly detected by VS .NET through the metadata exposed by TestAssembly1.dll (TestAssembly1 references TestAssembly2)

You're not allowed to distribute the merge module (dotnetfxredist_x86.msm) with your applications. If you select the module in the Solution Explorer and look at the Exclude property, you'll see that it's set to True. If you set it to False and try building the setup project, you get the warning, "dotNETFXRedist_x86_enu.msm must not be used to redistribute the .NET Framework. Please exclude this merge module." The merge module has been included to tell you that the .NET Framework must be installed on the target machine and to help calculate dependencies.

However, you can work around this issue, as described in the "Including the .NET Framework" section later in this chapter.

Adding Windows Satellite Assemblies

Because an application can run without any satellite assemblies, it's often a critical point when it comes to testing. If your native language and the application's default language is English, the application will run and not complain about missing satellite assemblies at runtime. When the .NET Framework can't locate a specific culture, it will fall back and use the default culture, which is en-US, if you don't specifically change it. The default culture is always compiled as part of the main assembly, which means it's always there. So, when you take your setup project for a little test spin, you normally don't catch missing satellite assemblies. Make sure you include any required satellite assemblies.

Satellite assemblies are also part of the project output. You add them to your setup project by selecting the Localized resources category in the Add Project Output Group dialog box (see Figure 15-14).

There's only one satellite assembly for the WindowsDeploymentProject project, and that's the one for the Danish culture (da-DK). Now, you don't actually have to include it; the application will run without it. However, if you don't include the Danish satellite assembly on your setup project, your application won't be able to use the Danish culture on the target machine. Well, this isn't entirely true, because the formatting of numbers, dates, and so on provided by the operating system will be included. Only the custom strings, bitmaps, and so on that you provide yourself through the use of resource files will be missing.

Tip

If you want to know more about satellite assemblies and localization in general, we recommend you read this book: Internationalization and Localization Using Microsoft .Net, written by Nick Symmonds, published January 2002 (ISBN: 1590590023).
Adding Graphics Files

Any graphics files that are included as part of the project are compiled as part of the assembly. For example, the sample project includes 1590590422.jpg as part of the project, and it has been used as the value for the Image property of the staticPicture PictureBox on Form1. As soon as you assign a graphics file to a property of a control, it is added to the resource file (.resx) for the container of that control (Form1).

Graphics files that are loaded dynamically at runtime must be added manually to the setup project, and this is done using the Add Files dialog box (right-click the setup and deployment project in the Solution Explorer and select Add ® File). When you add files to your setup project, they're automatically tagged so that they'll be placed in the application folder on the target machine. This works if this is where the application expects to find the graphics file, but you can change it if this isn't the case. To change a file's storage location, select the file in the Solution Explorer and change the Folder property.

Adding Windows Configuration Files

An application configuration file named app.config is handled automatically by the application build process, meaning it's renamed to <ProjectName>.exe.config. There's only one configuration file in our sample application, and it's the default app.config. (This file holds a value for a dynamic property, namely the Text property of the initCOMTimeLabel Label control on Form1.) So, in our case, the app.config file is renamed to WindowsDeploymentProject.exe.config and copied to the bin folder, where the executable resides. This is the main configuration file, and it's automatically added to your setup project when you add the primary application output.

Note

If you look at the list of files in the setup project after adding the primary output, you won't see the exe.config file. However, it's still included at build time.

If you have any other configuration files in your application project, you must manually include them in your setup project if they're to be deployed to the target machine. One way of doing this is to change the value of the Build Action property of the file to Content, and then add the content files to the setup project. See the beginning of the "Adding Windows Project Output" section earlier in this chapter for more information about adding content project output. You can also add it manually using the Add Files dialog box.

In Exercise 15-2, you'll add all the files to the setup project that must copied to the target machine.

Exercise 15-2
Start example

  1. Right-click DeploymentProject in the Solution Explorer and select Add ®Project Output. In the Add Project Output Group dialog box, select Primary output (see Figure 15-14).

    • When you add the executable from the sample application to the setup project, a message is displayed informing you that COMTest.dll might have dependencies that can't be determined by VS .NET. In this case, you need to make sure that the msvbvm60.dll file is present and registered on the target machine. If you don't have VB 6 installed on your machine, you can download the VB 6 runtime files from http://support.microsoft.com/default.aspx? scid=http://support.microsoft.com:80/ support/kb/articles/Q192/4/61.ASP&NoWebContent=1.

    • The download package installs and registers the VB 6 runtime files on your machine, but what about the target machine? You could run the executable on the target machine, but what about potential errors when the executable is run? So, that's not a good idea. Instead, unpack the files from the Vbrun60.exe file, like this: Vbrun60.exe /t:c:\vb6runtime /c. This will extract all the files to the folder C:\vb6runtime.

    • Now, you can add the required files to your setup project. According to the URL download link, the required files are ASycFilt.dll, ComCat.dll, MSVBVM60.dll, OLEAut32.dll, OLEPro32.dll, and STDOLE2.tlb. Right- click the setup and deployment project in the Solution Explorer and select Add ® File to open the Add Files dialog box, and add the required files to the project.

  2. Once the required files are added to the setup project, you need to make sure they're registered on the target machine. Well, VS .NET actually does it for you, but for the sake of getting acquainted with the process, just follow along. Select each file in the Solution Explorer and set the Register property to the correct value. (Open the Properties window by pressing F4.) You can find a list and description of the values at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsintro7/html/ vxgrfregisterproperty.asp.

  3. Add the Danish satellite assembly to the setup project by selecting Localized resources in the Add Project Output Group dialog box.

  4. The Author.jpg file is loaded dynamically at runtime. Add this graphics file to the setup project using the Add Files dialog box.

Since the only configuration file in our application project, app.config, is auto matically renamed and added to the setup project, you don't need to manually add any configuration files to the setup project. The content of the DeploymentProject setup project should look like the list shown in Figure 15-16.

Click To expand
Figure 15-16: DeploymentProject content

End example

Customizing Windows Deployed Items on the Target Machine

Copying the files needed to run your application to the target machine is by far the most important task when deploying your application. However, you might still need to customize items that will be deployed on the target machine.

Note

We assume that you have already created your application the way you want it. If you need to customize the setup, see the "Customizing Setup Projects" section later in this chapter for information about how to do this.

Some of the files you deploy have attributes that can be set, such as copy right, company name, description, and so on. We recommend that you do set these attributes. There's also the information that's saved on the target machine relating to the installation, which is accessible from the Add or Remove Programs Control Panel applet. We'll look at these attributes in the following sections.

File Attributes

When a file is displayed in Windows Explorer (or any other file-browser utility), you can see various attributes. Figure 15-17 shows some of the attributes of the WindowsDeploymentProject.exe file, which is the primary output of our sample application.

Click To expand
Figure 15-17: File Properties dialog box
Note

The dialog box refers to the attributes as properties, but we like the term attributes in this case. For the sake of this discussion, the terms properties and attributes mean the same thing.

In Figure 15-17, you can see that we've set the Comments attribute to AssemblyDescription, and we've set a few other attributes as well. However, the properties displayed in the dialog box in Figure 15-17 don't correspond directly to an attribute or property in your application project.

To set the attributes, open the assembly information file in your project (AssemblyInfo.vb or AssemblyInfo.cs). Figure 15-18 shows the assembly information file for our sample project, but you can see the attributes here don't correspond directly to the file properties. The values set for the attributes in our sample project are not the default ones; they are ones that we set. Normally, none of the attributes, except for AssemblyVersion, are set by default. We'll describe the AssemblyVersion attribute in the "Versioning" section later in this chapter.

Click To expand
Figure 15-18: Assembly information file

Table 15-3 provides an overview of the most used attributes and how they map to the file properties.

Table 15-3: Assembly Attributes to File Properties Mapping
Assembly Attribute | File Property
AssemblyTitle | Description
AssemblyDescription | Comments
AssemblyCompany | Company
AssemblyProduct | Product Name
AssemblyCopyright | Copyright
AssemblyTrademark | Legal Trademarks
Tip

You can check and edit for assembly attributes programmatically without having to load the components. In order to do this, you must use the Dsofile utility from Microsoft. Refer to the document at http://support.microsoft.com/?kbid=224351.

In Exercise 15-3, you'll add some file attributes to the sample setup project.

Exercise 15-3
Start example

  1. Open the AssemblyInfo.vb file.

  2. Set the value of the AssemblyCompany attribute to ".NET Services".

  3. Set the value of the AssemblyTitle attribute to "This is a sample application for Chapter 15 of Enterprise Development with VS .NET, UML, and MSF".

  4. Set the value of the AssemblyProduct attribute to "WindowsDeploymentProject".

End example
Start Sidebar
Why Bother to Set File Attributes?

You don't need to set any file attributes, but we think it's a good idea. Having the attributes set is particularly helpful to someone who looks at the files on his or her machine and wants to know just a little more about those files.

Suppose that your application has been removed only partially from a machine, and one or more files are left behind. Say the executable is still on the machine, and the owner of the machine needs to know if he or she can delete it. By looking at the file name and the folder it's placed in, the user may be able to determine if it's okay to delete the file. However, in some cases, the user can't be sure, and this is one area where the assembly attributes come in handy. If you set a value for the AssemblyCompany, AssemblyProduct, and AssemblyTitle or AssemblyDescription attributes, you give whoever stumbles across your assemblies a good chance of finding out what the assembly does, who produced it, and if it can be safely deleted.

Additionally, setting the file attributes can be good marketing, as long as you create good applications, of course.

End Sidebar

Setup Attributes

The setup attributes are the ones you can specify using the properties in the Properties window in the VS .NET IDE, and they're accessible from the Add or Remove Programs Control Panel applet. To set the properties, select the setup project in the Solution Explorer and open the Properties window (by pressing F4).

In Figure 15-19, you can see the Support Info dialog box for the DeploymentProject application. We ran the setup and installed the application on our local machine. Users will see this information when they open the Add or Remove Programs Control Panel applet, select DeploymentProject from the Currently installed programs list, and click the Click here for support information link.

Click To expand
Figure 15-19: Support Info dialog box

Table 15-4 shows the most common setup attributes.

Table 15-4: Setup Project Properties to Add or Remove Programs Control Applet Mapping
Setup Project Property | Add or Remove Programs Control Applet Equivalent
Author | Contact
Description | Comments
Manufacturer (required) | Publisher
ManufacturerURL | Publisher (the Publisher text is a hyperlink)
ProductName (required) | Displayed in various places (Currently installed programs list in the Add or Remove Programs Control Panel applet and the Support Info dialog box)
SupportURL | Support Information
Version (required) | Version

In Exercise 15-4, you'll add some setup attributes to our sample setup project.

Exercise 15-4
Start example

  1. Select the setup project in the Solution Explorer and press F4 to open the Properties window.

  2. Set the value of the Author property to "Carsten Thomsen & John Hansen".

  3. Set the value of the Manufacturer property to ".NET Services".

  4. Set the value of the ProductName property to "WindowsDeploymentProject".

End example

[3]Not that you can't create a Cab Project and/or download and install from the Web, but we think the fully Windows-based Setup Project is the right choice for the sample application.


Deploying ASP.NET Applications

In this section, we'll look at the steps for deploying a Web application. As in the previous section's coverage of Windows application deployment, we'll work through the main tasks using a sample solution. The related topics of handling .NET Framework issues, providing security, customizing a setup project, and ver sioning are covered later in this chapter.

For the Exercises in this section, we've created a sample Web solution named WebDeploymentProject, to which you can add your setup project. It's a simple solution consisting of a Web application and a Web service.

You can find the solution in the accompanying sample code, which can be downloaded from the Downloads section of the Apress Web site (http\\:www.apress.com). The sample solution is located in the Chapter 15\WebDeploymentProject folder, and the solution with all of the Exercises performed is in the Chapter 15\WebDeploymentProject2 folder.

The WebDeploymentProject sample application contains the following items, as shown in Figure 15-20:

Figure 15-20: WebDeploymentProject project items

  • Various .NET Framework assemblies

  • TestAssembly1 .NET component

  • WebDevelopmentProjectWebService XML Web service

  • FLGDEN.gif and FLGUK.gif image files for changing languages

  • 1590590422.jpg picture of the book cover

  • AssemblyInfo.vb assembly information file

  • Global.asax global application class

  • Strings.da.resx Danish (da) culture resource file holding strings

  • Strings.resx default culture resource file holding strings

  • Styles.css default Cascading Style Sheet (CSS)

  • Web.config application configuration file

  • WebForm1.aspx Web form

  • WebForm1.aspx.vb Web form code-behind file (not shown)

  • WebForm1.aspx.resx resource file

All of the files listed play a part in what's deployed, but there's also one file that isn't part of the project, Author.jpg, which is loaded at runtime, and an assembly that's referenced by another assembly, TestAssembly2.dll (referenced by TestAssembly1.dll).

The WebDevelopmentProjectWebService XML Web service reference is actually another Web service project, and this project contains the following items:

  • COMTest.dll COM component created in VB 6

  • Various .NET Framework assemblies

  • AssemblyInfo.vb assembly information file

  • Global.asax global application class

  • Web.config application configuration file

  • WebDevelopmentProjectWebService.asmx Web service class file

Except for COMTest.dll, all of the files are part of a default Web service. Well, the Web service class file has been renamed from Service1.asmx to WebDevelopmentProjectWebService.asmx, but that's about it. Basically, the Web service calls the COM component and returns the result of a method call to the caller of the Web service method.

Adding Setup Projects to the Web Solution

First, you need to decide which type of setup project to add to the two projects in the solution. Table 15-1, at the beginning of this chapter, shows the various setup and deployment options available to you. If you run though the ones that can be used for Web application deployment and list the pros and cons, you'll find that the only suitable project for the two projects is the Web Setup Project. This is because it can register your application and service with IIS, as well as copy all of the required files and register the COM object.

In Exercise 15-5, you'll add setup projects to your existing solution.

Exercise 15-5
Start example

  1. Open the WebDeploymentProject solution/project in VS .NET.

  2. Right-click the solution file in the Solution Explorer and select New Project from the pop-up menu.

  3. In the Add New Project dialog box, expand the Setup and Deployment Projects node in the Project Types list to see the various setup and deployment projects.

  4. Add a Web Setup Project named WebDeployment to the solution.

  5. Repeat steps 2 and 3 to add a Web Setup Project named WSDeployment to the solution.

End example

Why add two setup projects? One Web setup project can deploy to only a single virtual directory on the target machine, meaning that both the Web appli cation as well as the Web service would be deployed to the same URL. This is doable, but we think it's better to have two different URLs. The main reason is the reference in the Web application to the Web service—it's location-specific, meaning that it points to the local machine at present.

Next, you need to copy the executable assembly from your Web application, as well as some other necessary files, as discussed in the next section.

Because we're now working with two separate setup projects, we also need to determine which one has the top priority, because the Web application references the Web service, and this reference is location (URL) specific. This means that the Web service must be built and deployed before you can update, build, and deploy the Web application.

Start Sidebar
Copy Project Feature

For deploying Web applications and services, VS .NET has a new and quite unique feature called Copy Project. Basically, it is used to copy your application or service to a Web server running IIS, with the correct .NET Framework installed. This feature is available if you select the project you want to copy (only one project at a time, not an entire solution) and select Project ® Copy Project. This brings up the Copy Project dialog box, as shown in Figure 15-21.

Click To expand
Figure 15-21: Copy Project dialog box

This dialog box is used for copying your Web project to a Web server, using the FrontPage (entering the URL) or File Share (entering the (UNC) path) Web access method. FrontPage Server extensions must be installed on the target server, if you want to use the FrontPage Web access method. If you want to use File Share, you must have write access to the folder on the Web server you're accessing.

The last thing you need to make a decision about before clicking OK is which files to include:

  • Only files needed to run this application: This is the default and as the name implies, only the files required to run the application will be copied across (project output and content files). Any files not part of the project, even if referenced from an assembly, will not be copied.

  • All project files: This will copy all files that are part of the project, as well as the files needed to run the application, such as the project output.

  • All files in the source project folder: This will copy all files located in the source project folder, including any subfolders.

In most cases, you'll probably use the default option, but if you're moving or copying your development project to another machine, you'll need to use one of the other two options.

Any files not part of the project, even if referenced from an assembly, will not be copied. If you have such files, as in our sample application, the Copy Project feature is not for you. The All files in the source project folder copy option can be used to include everything in the source project folder, including subfolders, but this doesn't include files loaded from folders located outside this structure.

End Sidebar

Adding Files to Web Setup and Deployment Projects

The types of files you need to add to a Web setup project are the same as those for a Windows setup project (see the "Adding Files to a Windows Setup and Deployment Project" earlier in the chapter), with one addition:

  • Web services: Any Web service references in your project.

Adding Web Project Output

The project output in our two projects is more than just one or two files, and we need to add them to our setup projects. As with the Windows deployment pro cedure described earlier in the chapter, you use the Add Project Output Group dialog box (see Figure 15-14 earlier in this chapter) to add project output. Open this dialog box by right-clicking the setup and deployment project in the Solution Explorer and selecting Add ® Project Output, or by selecting the setup and deployment project in the Solution Explorer and selecting Project ® Add ®Project Output.

If you followed the Exercises in the "Deploying Windows Applications" section earlier in this chapter, you noticed that the primary output was the only project output that was added to the setup project. Although the content of the Web application and Windows application sample projects are almost the same, there's one noticeable difference: how the static picture is deployed. In the Windows application, it's referenced from an Image control placed on a Windows form and thus part of the resource file for that form. However, for the Web form in the Web sample application, we only reference the picture using the ImageURL property of the Image Web control. This means that this picture, which is tagged as a content file, must be added to the setup project manually. You can do this by adding the content files.

Detecting Web Project Dependencies

When you add the primary project output to the setup project, VS .NET tries to detect the dependencies the project output has. The dependencies are grouped in two categories: COM Components and .NET Assemblies. You can find a good description of the two categories in the "Detecting Windows Project Dependencies" section earlier in this chapter.

The Web service application contains a reference to a COM component written in VB 6, so you need to include the files required for running it.

Adding Web Satellite Assemblies

Only the sample Web application project uses localization and satellite assem blies, and it uses the Danish culture (da-DK). See the "Adding Windows Satellite Assemblies" section earlier in this chapter for information about how to add the satellite assemblies to your setup project.

Adding Graphics Files

There are two graphics files used by the Web application: one (1590590422.jpg) has been included as part of the project, and one (Author.jpg) is loaded dynami cally at runtime. Actually, they're both loaded at runtime, but only one is included as part of the project and thus copied if you include the content files in your setup project. The other picture must be added manually to the setup project, and this is done using the Add Files dialog box. You can find instructions on how to add files in the "Detecting Windows Project Dependencies" section earlier in this chapter.

Also, as when you add files to a Windows setup project, the files are automat ically tagged so that they'll be placed in the application folder on the target machine. If desired, you can select the file in the Solution Explorer and change the Folder property.

Adding Web Configuration Files

There's only one configuration file in our application: the default Web.config. This file doesn't hold any values that we rely on in the Web application, so we could choose not to add it to our setup project. However, this will also remove any possibility of dynamically configuring our application with features such as redirecting errors and enabling/disabling debugging. For this reason, we always include the Web.config file when we deploy an application.

The Web.config file is the main configuration file. Unlike with Windows deployment, where the main configuration file is automatically added to your setup project when you add the primary application output, the Web.config file is part of the content files project output. This means that you must include it manually by adding the content files.

Note

If you look at the list of files in the setup project after adding the content files, you won't see the Web.config file, but it's still included at build time.

If you have any other configuration files in your application project, these also must be manually included in your setup project if they're to be deployed to the target machine. One way of doing this is to make sure the value of the Build Action property of the file is set to Content, and then add the content files to the setup project.

In Exercise 15-6, you'll add all the files to the Web setup project that must copied to the target machine. Referring back to our deployment priority, we need to build and deploy the Web service first, so all the instructions are given in that order.

Exercise 15-6
Start example

  1. Right-click WebDeployment in the Solution Explorer and select Add ®Project Output. In the Add Project Output Group dialog box, select WebDeploymentProject from the Project list, and select Primary output (see Figure 15-14). Click OK to close the dialog box.

  2. Right-click WSDeployment in the Solution Explorer, open the Add Project Output Group dialog box, select WebDeploymentProjectWS from the Project list, and select Primary output. Click OK to close the dialog box.

  3. The Author.jpg file is loaded dynamically at runtime. Add this graphics file to the WebDeployment project using the Add Files dialog box.

  4. The Web service application contains a reference to a COM component written in VB 6, so you need to include the files required for running it. See Exercise 15-3 for details on which files are required and how to acquire them. Right-click the WSDeployment project in the Solution Explorer and select Add ® File to open the Add Files dialog box. Add the files required for running a VB 6 component/executable.

  5. Only the WebDeployment project uses location and satellite assemblies. Add the Danish satellite assembly to this project, by selecting Localized resources in the Add Project Output Group dialog box.

  6. Add the content files from the Web application project to the WebDeployment project.

  7. Add the content files from the Web service project to the WSDeployment project.

The contents of the WebDeployment and WSDeployment projects should look like those listed in Figure 15-22.

Click To expand
Figure 15-22: Web setup projects content

End example

We've already covered the subject of customizing deployed items in the "Windows Application Deployment" section earlier in this chapter. You can use the techniques covered there to customize the File and Setup attributes of your Web applications.

Building and Deploying Web Setup Projects in the Correct Order

When you build and deploy the two sample Web setup projects you worked with in the previous Exercises, you need to do so in the proper order. We'll talk about building and running setup later in this chapter. Here, we just establish the correct order for these tasks:

  • Build the Web service application (WebDevelopmentProjectWS).

  • Build the Web setup project for the Web service (WSDeployment).

  • Deploy the Web service by running the Web Setup Project, accepting the default values presented at runtime.

  • Modify the Web application (WebDeploymentProject) so it refers to the deployed Web service. We used a dynamic URL behavior, so you can change it in the Web.config file of the Web application.

  • Build the Web application (WebDevelopmentProject) (see the "Building Setup" section later in this chapter for more information about building projects).

  • Deploy the Web application by running the Web setup project, accepting the default values presented at runtime (see the "Running Setup" section later in this chapter for more information about running setup packages).

If you're installing to your local machine where you also build and test the Web application and Web service, and you don't change the property values, you don't need to carry out the mentioned steps. However, when you deploy the application to users, the order is important, because of the effect of referencing a Web service project.


Handling .NET Framework Issues

When talking about deploying .NET applications, it's rather obvious that the .NET Framework must be installed on the target machine. If you are deploying internally or in an organization where you know for sure that the .NET Framework is installed on the target machine (like the setup for the sample code for this book), this isn't an issue.[4] However, in other situations, you need to make sure that the .NET Framework is installed before deployment.

Detecting the .NET Framework

The first step the setup must take on the target machine is to detect if the .NET Framework is installed. When you add the primary output from your application project, the Microsoft .NET Framework merge module (dotnetfxredist_x86.msm) is automatically added to the list of dependencies. This also means that a launch condition is added to the setup project, as shown in Figure 15-23. (See the "Launch Conditions Editor" section earlier in this chapter for a description of the Launch Conditions Editor.)

Click To expand
Figure 15-23: .NET Framework launch condition

The .NET Framework launch condition checks if the .NET Framework is installed on the target machine. This check is done by the Windows Installer loader, before the Windows Installer takes over and starts copying files. The con dition checks for a specific Framework version, v1.1.4322 in our case, as you can see from the SupportedRuntimes property.

So, what can you do if the condition detects that the .NET Framework is not installed? You have two main choices:

  • Display a warning message that can route the user to the .NET Framework Downloads page.

  • Include the .NET Framework as part of your setup.

The next sections describe both of these approaches.

Displaying a Warning

The standard way of dealing with the nonexistence of the .NET Framework on the target machine is to display a warning, like this one:

Click To expand

This the default message that appears when running the setup on a target machine where the appropriate .NET Framework hasn't been installed. If the user clicks Yes, a browser window is opened on the .NET Framework Downloads page of the MSDN Web site. From there, the user can download and install the .NET Framework. If the user clicks No, the setup is aborted.

Including the .NET Framework

Instead of displaying a message when the appropriate .NET Framework isn't detected on the target machine, you can choose to include it as part of your setup, and have it installed on the target machine before installing your application.

This can be done using the VS .NET Framework Bootstrapper, which can be down loaded from http://msdn.microsoft.com/vstudio/downloads/ tools/bootstrapper.

Caution

When you package the .NET Framework redistributable with your deployment package, you must have a validly licensed copy of the Microsoft .NET Framework SDK version 1.1 or VS .NET 2003. If you're packaging the .NET Framework 1.0, you need a validly licensed copy of the Microsoft .NET Framework SDK version 1.0 or VS .NET 2002. If you're working with VS .NET 2002, you can't use the VS .NET Framework Bootstrapper, but you can use the Setup.exe Bootstrapper (available from http://www.microsoft.com/downloads/details.aspx?FamilyId=BF253CFD-1EFC-4FC5-BA7E-6A6F21403495&displaylang=en.)

The VS .NET Framework Bootstrapper complements VS .NET 2003, because it's a VS .NET plug-in that modifies the bootstrapper (Setup.exe) that is shipped with your setup project. The modification means that the .NET Framework redis tributable file (dotnetfx.exe) is included as part of your setup package. When setup is run on the target machine, this message is displayed if the .NET Framework isn't detected:

Click To expand

If the user clicks Yes, the .NET Framework is installed. If the user clicks No, the setup is aborted.

Note

If you run the Windows Installer file (.msi) directly, instead of the bootstrapper (Setup.exe) you miss out on the functionality of the modified bootstrapper. However, a missing .NET Framework is still detected, but as is the case without the modified bootstrapper, you get a message directing you to a download page on MSDN.

When you include the .NET Framework as part of your deployment package, you also automatically ensure that Windows Installer version 2.0 is installed on the target system. This is because the .NET Framework redistributable includes Windows Installer 2.0, and if it is not detected on the target system, it's automat ically installed.

[4]You may still need to make sure that it's the right version of the .NET Framework.


Implementing Security

Although this chapter is about deployment, we'll give you quick rundown of how the .NET Framework implements security and what you can do to improve security with your deployment packages.

In general, the .NET Framework provides security that you don't normally have with applications running on a Windows operating system. Normally, when a Windows application has been installed on your machine, it can access any resource on the machine; there's no protection, meaning that potentially mali cious code could cause mayhem on your setup.[5] In contrast, the .NET Framework provides security mechanisms for securing all aspects of your machine, such as access to the file system and the Registry.

.NET Framework Security Mechanisms

Here is a summary of the three main security mechanisms that the .NET Framework provides:

  • ASP.NET security: You use this type of security for authentication and authorization of users to the various parts of your site. Generally, ASP.NET security is provided by IIS, and the user authentication is provided by Windows authentication, Microsoft Passport authentication, Forms authentication, or Client Certificate authentication. You can find more information about how ASP.NET security works at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconhowaspnetsecurityworks.asp.

  • Code-access security: This type of security is used for restricting access to protected resources, such as the file system, using permissions and permission sets. You can find an introduction to code-access security at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconintroductiontocodeaccesssecurity.asp.

  • Role-based security: This type of security is used for restricting resources to certain roles. Users are assigned to one or more roles, and the member roles are then checked when accessing a specific resource. You can find an introduction to role-based security at http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/cpguide/html/cpconintroductiontorole-basedsecurity.asp.

For more information about general .NET security, refer to .NET Security, written by Jason Bock, Tom Fischer, Nathan Smith, and Pete Stromquist; published July 2002 (ISBN: 1590590538). Another book that provides good information about .NET Framework security is .NET Security and Cryptography, written by Peter Thorsteinson and G. Ganesh, published August 2003 (ISBN: 013100851X).

Strong Names

When deploying an assembly to the Global Assembly Cache (GAC) on the target machine, it must be strong named.[6] Strong naming means signing an assembly with public key encryption. It's not only required for storing the assembly in the GAC, but it's also needed for versioning and to give the assembly a unique identity. You can read more about strong-named assemblies at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconstrong-namedassemblies.asp.

You generally deploy to the GAC in order to share your assembly among multiple applications, thus avoiding several copies of the same assembly on a machine.

Authenticode

Authenticode is a way of letting users identify that you're the publisher of a com ponent or assembly. It's used for signing your assemblies, making sure the signed assemblies haven't been tampered with since you packaged or deployed them. You can find an overview of Authenticode at http://msdn.microsoft.com/library/default.asp?url=/workshop/security/authcode/authenticode_ovw_entry.asp.

Authenticode signing is used from the Setup and Deployment Project Property Pages dialog box, shown in Figure 15-3 earlier in this chapter. See the "Project Properties" section earlier in this chapter for information about using this dialog box.

Obfuscation

When deploying Windows applications or assemblies to a target machine, they're easily decompiled, and thus your code and application logic is available to anyone with an interest. This can be prevented (or, at least, made a lot harder) by using obfuscation.

You can find a general overview of obfuscation at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dotfuscator/dotf3rax.asp. You can read about the Dotfuscator Community Edition, which is included with VS .NET 2003, at http://www.preemptive.com/dotfuscator/dotfuscator_ce.html.

Deployment Permissions

For the deployment scenarios we've discussed so far in this book, you need administrative rights on the machine to which you're deploying an application. With those rights, you can, by default, install and run the application without any problems. However, it is possible to change these permissions using the command- line CASPOL utility or the Windows UI-based .NET Configuration application, which is shown in Figure 15-24. You can access this application through the Administrative Tools menu.

Click To expand
Figure 15-24: .NET Configuration application (for .NET Framework 1.1)

As you can see from the description in the right pane of the .NET Configuration application, it can be used to configure assemblies, remoting services, and code access security policy.

Application Download Cache

No-touch deployment (discussed later in this chapter) uses the application download cache. When an application is downloaded to the cache, it's automat ically run with restricted permissions in order to prevent malicious code from executing. This is not a problem if your application doesn't try to access any external data, such as the file system, directly. However, if this is what you need, you must look into requesting permissions for your downloaded application. Here's an interesting article discussing this and other related topics:

  • Security in .NET: Enforce Code Access Rights with the Common Language Runtime: http://msdn.microsoft.com/msdnmag/ issues/01/02/CAS/default.aspx

.NET Wizards

The .NET Wizards can help you adjust the security for an assembly, strong named or not. You can run the wizards by selecting the Microsoft .NET Framework 1.1 Wizards menu item in the Administrative Tools menu. This brings up the .NET Wizards application, where you can select the Trust an Assembly Wizard. This wizard can be used to trust an assembly on your disk or located using a URL. If the assembly specified is strong named, you can choose to trust all versions of the assembly, not just the current one. You also need to specify the level of trust for the assembly, from no trust to full trust. Try running the wizard to see which level is correct for your assembly.

[5]We realize that it is possible to secure this to some extent, but it's cumbersome.

[6]You must have administrative rights on the target machine in order to install to the GAC.


Customizing a Setup Project

So far in this chapter, you've seen how you can customize the deployed items on the target machine, but it's also possible to customize the setup itself. You perform setup project customization using the User Interface Editor, which is described in the "User Interface Editor" section earlier in this chapter. In this section, we'll look at two of the most common customizations.

Note

You can't see the dialog boxes as they appear on screen during setup when you design them. You must run the setup before you can see the output of your design. See the "Running Setup" section later in this chapter for more information.

Adding a License Agreement

Many, if not most, distributed applications have some sort of a license agreement. Whether you distribute open-source, shareware, freeware, or licensed applications, it's good practice to let the user of the setup application know the terms under which the software can be used.

The setup and deployment projects actually make it easy for you to create and display license information in your setup. Using the User Interface Editor, you simply choose to add a License Agreement dialog box to the Start stage of the installation.

The License Agreement dialog box has only a few properties:

  • The LicenseFile property specifies the RTF file that contains the text for the dialog box.

  • The Sunken property specifies if the border around the license agreement text should be sunken or invisible.

  • The BannerBitmap property adds a banner logo to the dialog box, as described in the next section.

To put information in the dialog box, you use the LicenseFile property; without it, the dialog box will be empty. The LicenseFile property takes the file name of an RTF document, which is the file that holds the license agreement text. If this file doesn't already exist as part of the setup project, you can add it by using the LicenseFile property's Browse functionality. The RTF file won't be copied to the target machine by default. To have the file copied, you must change the value of its Exclude property to False (select the file in the Solution Explorer and open the Properties window to access its properties). Figure 15-25 shows an example of a License Agreement dialog box that has its LicenseFile property set to a valid RTF file.

Click To expand
Figure 15-25: License Agreement dialog box
Note

The file holding the license agreement text must be in RTF format.

Adding a Banner Logo

You can add a banner logo to any of the dialog boxes, using the BannerBitmap property. The logo is placed at the top of the dialog box, behind the banner text. The logo should be in Windows Bitmap or JPEG format.[7] We've been experi menting with the size of the logo, and a width of 615 pixels and a height of 90 pixels gives the best results. The logo will be stretched or shrunk to match the size of banner area.

Because the banner text is placed on top of the logo, you should make sure that the visual part of your banner is placed to the right of the banner text. The easiest way to set up the banner is to make it transparent or the same color as the banner area background. The BannerLogo.jpg picture file in the WebDeploymentProject folder is a good example.

In Exercise 15-7, you'll add a License Agreement dialog box with a banner logo to the WebDeployment Web setup project.

Exercise 15-7
Start example

  1. To open the User Interface Editor, right-click the WebDeployment setup project in the Solution Explorer and select View ® User Interface from the pop-up menu.

  2. Select the Start stage under Install, to add the dialog box to the standard installation at startup.

  3. Add a License Agreement by right-clicking the Start node and selecting Add Dialog from the pop-up menu. In the Add Dialog dialog box, select License Agreement and click OK.

  4. When you add a new dialog box to any of the installation stages, it's added as the last dialog box. To move the License Agreement dialog box up to appear as the second dialog box, right-click the dialog box and selecting Move Up from the pop-up menu, as many times as necessary.

  5. Set the value of the LicenseFile property of the License Agreement dialog box to license.rtf.

  6. Set the value of the BannerBitmap property of the License Agreement dialog box to BannerLogo.jpg.

Figure 15-26 shows the License Agreement dialog box with a banner logo in the banner area at the top of the dialog box.

Click To expand
Figure 15-26: License Agreement dialog box with a banner logo

End example

There are plenty of other customizations that you can make to your setup project. You can experiment with the properties and see how they change the appearance of the dialog boxes when the setup is run.

[7]We tried other formats, such as GIF and TIFF, but they don't show up in the dialog boxes.


Versioning

Versioning is a big issue, especially when it comes to deploying components. Ver sioning can be a cumbersome task, but VS .NET gives you a helping hand with some of it. Here, we'll look briefly at assembly versioning and application versioning.

Assembly Versioning

Assembly versioning is used for all strong-named assemblies (assemblies with public key encryption), which, in general, means shared assemblies. Versioning is used to programmatically determine if an application should load an assembly. The GAC can hold more than one version of a shared assembly. In many cases, besides the version number, only the internal code is different between different versions.

By default, an application uses only the version of an assembly with which it was built and configured—usually, the one it ships with. However, it is possible to update the assembly, ship it, and have the application use the newer assembly instead of the old one.

The assembly version is specified in the assembly information file (AssemblyInfo.vb or AssemblyInfo.cs) through the AssemblyVersion attribute. As you can see from the description of this attribute in the assembly information file (see Figure 15-18 earlier in the chapter), the version is divided into four groups: major version, minor version, build number, and revision. An example is 1.2.3.4, which means the major version is 1, the minor version is 2, the build version is 3, and the revision number is 4.

Application Versioning

Application versioning allows you to uniquely identify your application to the end users, and it's generally not used programmatically (although that is possible). Application versioning is specified using the Version property, which is of data type String. You access this property by selecting the setup project in the Solution Explorer and opening the Properties window.

When you create a new setup project, the default version number is 1.0.0, unlike the assembly version, which has four groups. Also unlike assembly ver sioning, you must manually change (increment) this number every time you release a new version; there's no automatic way of doing it.

Now, it's a string property so why not just add the revision to the version number? You can do that, but the Windows Installer won't recognize it, and you'll get a compiler error if you do so. So, you're stuck with the three groups.

The Version property is handled by the Windows Installer for most setup projects, but a CAB file or a merge module is also tagged with the version number. When an application is installed on a Windows target machine, you can see the version number in the Support Info dialog box of an installed application in the Add or Remove Programs Control Panel applet (see Figure 15-19 earlier in this chapter).

When you change the Version property, you're prompted to change the ProductCode property as well. The ProductCode property is a GUID that uniquely identifies the application, CAB file, or merge module. Since you're changing the version number, you should also change the ProductCode property, as this is a now a new product.[8]

We did say that this version number isn't used programmatically, but that isn't entirely true. The Windows Installer will detect if a newer version is already installed on the target machine and, optionally, abort the setup. You can achieve this by setting the value of the DetectNewerInstalledVersion property of the setup project to True (default). When you try to install your application on a target machine with a newer version installed, you'll see an error message like this:

Click To expand

Start Sidebar
Getting More Information About Versioning

There are many philosophies behind software versioning. Here are some articles and documents you might find of interest:

  • Towards a Versioning Model for Component-based Software Assembly: http://nenya.ms.mff.cuni.cz/publications/Gergic-Versioning.pdf

  • Landmark's software numbering scheme: http://www.lgc.com/resources/Software%20Version%20Scheme.doc

  • Creativyst Software Stability Ratings: http://www.creativyst.com/Doc/Std/StableSW/v10a/StabSW01.htm

  • One of the more fun articles written about versioning: http://llamasery.com/forum/ index.php?s=9a57b0a197c4b8836740ffeaba49c491&showtopic=3067

And here are some resources for more information about assembly versioning specifically:

  • Assembly versioning: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconassemblyversioning.asp

  • Windows Installer version: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/version.asp

  • AssemblyVersionAttribute class: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/ frlrfsystemreflectionassemblyversionattributeclasstopic.asp

End Sidebar

[8]Well, at least in terms of uniquely identifying an application.


Localization Issues

If you develop software for the market outside the US, you may want to have the setup use the same language as the application being deployed. Is this possible with VS .NET deployment? It sure is, but there's more than one issue here. You need to address setup localization and .NET Framework localization.

Setup Localization

The setup project itself can be localized just as easily as your applications can. Actually, it's easier than localizing your applications, because it's already done for you. Yes, that's right—the dialog boxes and the default text have already been localized; you need to worry only about localizing your own text and possibly graphics.

The VS .NET Installer currently supports the following languages/locales:

  • Neutral

  • Chinese

  • US English

  • French

  • German

  • Italian

  • Japanese

  • Korean

  • Spanish

    Note

    As you can see, if you are from a country with a language that's not one of the major languages, you're just not part of the bigger plan. The languages/locales listed cover a large part of the globe, but they don't include variations/dialects of the languages, such as UK English, Austrian German, and so on. Also missing are most of the Asian and African languages, and some of the European languages (including Scandinavian). Russian, Arabic, and Hindi are missing, too.

You simply change the value of the Localization property of the setup project to the desired locale. When you do so, you're informed of the results of your change.

The User Interface Editor and the various properties will keep using the English language in the VS .NET IDE; the actual translation takes place when you build your setup project.

Figure 15-27 shows how the License Agreement dialog box you added in Exercise 15-7 looks after changing the setup project's Location property to German. You can see that the text supplied by the VS .NET Installer is in German, but the banner logo and the license text, which we've supplied, are still in English. To have those appear in German as well, we would need to manually localize the text and graphics we supply.

Click To expand
Figure 15-27: License Agreement dialog box in German

Additionally, if you change any of the default text in any of the dialog boxes, the text will not be translated automatically. You'll need to do it manually. Furthermore, if you change some of the default text in the dialog boxes, such as the copyright warning in the Welcome dialog box, simply changing the text back to the original won't make it possible to have it translated automatically. When you modify the original text, the modified text is written to the .vdproj setup project file, instead of a reference to the VS .NET Installer.

Start Sidebar
Undoing Default Text Modifications

In Figure 15-28, you can see the value of the Value attribute of the Copyright property has the actual text specified. As you can see from the highlighted text, we modified the text, making a deliberate typo.

Click To expand
Figure 15-28: Setup project file (.vdproj) with text modified

If we were to fix the typo, the text would still be there, and it wouldn't be translated. We did some experimenting to see how we could undo such changes, and came up with this procedure: Replace the text in the Value attribute with the value of the DefaultValue attribute, and set the value of the Setting attribute to 3:1. What does that mean? Well, we're not entirely sure to be honest, but if you look at the value of the Setting attribute for the BannerBitMap property, you can see where we got the idea. This works on our system, if we close and reopen the setup project in VS .NET before building it. However, please be careful in attempting to do this on your system, since editing the setup project file could result in the file being unusable.

End Sidebar

Localized .NET Framework

If you choose to include the .NET Framework as part of your setup (see the "Including the .NET Framework" section earlier in this chapter), and you localize the application and setup, you might want to include the localized .NET Framework, if one exists. The .NET Framework has been localized into all the languages/locales supported by the VS .NET Installer, but also quite a few more, including all of the Scandinavian languages (Danish, Norwegian, and Swedish). Check this page to see if the .NET Framework exists in your language: http://www.microsoft.com/downloads/details.aspx?FamilyId=262D25E3-F589-4842-8157-034D1E7CF3A3&displaylang=en/.

Obtaining the .NET Framework redistributable file is one thing; another is getting it to work with the VS .NET Bootstrapper plug-in, because at the time of writing, it exists only in US English and Japanese. However, you can download the .NET Framework redistributable (dotnetfx.exe) and replace the English one placed by the VS .NET Bootstrapper plug-in setup in the \Program Files\Microsoft Visual Studio .NET 2003 Bootstrapper Plug-in\1033 folder. This way, the localized .NET Framework will be distributed with your setup package. Keep in mind that the VS .NET 2003 Bootstrapper itself is still in English, at least until it has been localized into your language/locale. You can localize the VS .NET 2003 Bootstrapper by editing the config.ini file located in the folder mentioned earlier.

Note

If you already have a different language version of the .NET Framework installed, that version will be distributed using the VS .NET 2003 Bootstrapper plug-in.


Building Setup Projects and Solutions

You've created your application and your setup project, so now it's time to build it.

  • To build a solution, select the solution in the Solution Explorer, and then select Build ® Build Solution, press Ctrl-Shift-B, or right-click the solution and select Build Solution from the pop-up menu.

  • To build a project, select the project in the Solution Explorer, and then select Build ® Build <ProjectName> or right-click the project and select Build from the pop-up menu.

The output from the build process depends on whether you have the VS .NET Bootstrapper plug-in installed. Table 15-5 shows the typical output from the build process, indicating which files are output only with the plug-in installed.

Table 15-5: Typical Build Output
File | Description | Requires Bootstrapper Plug-in
Config.ini | Contains the text displayed to the user before and after invoking the Windows Installer for the actual setup | Yes; it's the configuration file used by the VS .NET Bootstrapper at runtime
<SetupProjectName>.msi | Windows Installer package, containing the actual appli cation or component to be installed | No
dotnetfx.exe | .NET Framework redistributable file for installing the .NET Framework on the target machine (if necessary) | Yes
Setup.exe | VS .NET Bootstrapper | No
Settings.ini | VS .NET Bootstrapper configuration file, with settings such as where to look for the Windows Installer package and setup name | No; with the plug-in the file con tains where to look for the .NET Framework redistributable; without the plug-in, it includes the URL for downloading the .NET Framework redistributable
Note

If you execute the Windows Installer package instead of the VS .NET Bootstrapper, you don't have the option of installing the .NET Framework as part of the installation.

By default, when you build a solution, all of the projects contained in the solution are also built. However, when you build a solution that includes a setup project, the setup project isn't automatically built as part of the solution build; you need to do this manually.

If you really need the setup project to be built automatically, you can change the configuration in the Configuration Manager, as shown in Figure 15-29. To open the Configuration Manager, right-click the solution in the Solution Explorer and select Configuration Manager from the pop-up menu, or select the solution in the Solution Explorer and select Build ® Configuration Manager. The Config uration Manager dialog box allows you to specify which configuration should be used when building and which projects should be built.

Click To expand
Figure 15-29: Configuration Manager

If you use the Configuration Manager dialog box to select the projects that should be built every time you build the solution, you don't need to invoke the build process twice. This is especially helpful in the beginning when you're still working on your application as well as on your setup.[9] However, as you add more and more items to your projects and more projects to your solution, it will quickly add time to the build process. So, make sure you do this only when it's helpful and doesn't add minutes, tens of minutes, or even more time to the build process.

[9]Yes, this is a valid approach…as we've stressed in this book, you should start creating setup projects while creating the application.


Running Setup Packages

Now that you've built your setup solution, users can run it to install the application. In this section, we'll give you a few hints about running setup packages to perform standard and administrative installations. (This is how the User Interface Editor groups the installations, as described in the "User Interface Editor" section earlier in this chapter).

Running a Standard Installation

The standard installation is the one for the end user, who will run the setup on the actual target machine. This setup is run by executing the Setup.exe file or the Windows Installer Package (.msi).

This is a straightforward installation, displaying the dialog boxes you have chosen to display and accepting the input you've opted to collect.

Testing the Installation

When you need to test the setup package, you have two options:

  • Run the setup from Windows Explorer or your browser

  • Run the setup from within the VS .NET IDE

Using Windows Explorer or your browser makes sense when you're testing your setup after you have finalized the UI and made sure everything is included. You're then ready to install it on a clean target machine to see if it runs.

When you're developing your application and creating your setup, you'll want to run the setup from the VS. NET IDE. You can run the setup project by selecting it in the Solution Explorer and selecting Project ® Install, or by right- clicking and selecting Install from the pop-up menu. This way of invoking the setup works exactly as if you were running it outside the IDE, but it saves you a bit of time. However, it cannot replace the final testing on a clean target machine.

Uninstalling

Because the setup projects are using the Windows Installer, you can always uninstall an installed application or component by using the Add or Remove Programs Control Panel applet. Simply open the applet, find your application/component in the list of Currently installed programs, select it, and click the Remove button on the right. This will uninstall your application or component.

Running an Administrative Installation

An administrative installation is when you install to a network location. From that location, end users can then install the application—in other words, run the standard installation.

Starting the Installation

You can start the administrative installation by executing this command from the command line:

msiexec /a <SetupProjectName>.msi

When you run the administrative installation, it appears as if you're running the standard installation, with the exception of the word "Network" added to the banners of the various dialog boxes, as shown in Figure 15-30.

Click To expand
Figure 15-30: Welcome dialog box of Administrative Install

When the administrative installation is finished, a network Windows Installer image has been created at the specified location, including the files that must be distributed along with your application. This is in contrast to a standard instal lation, where all the files are part of the Windows Installer package. However, the "normal" standard installation and the one created by the administrative instal lation perform the same setup on the target machine.

Note

There is one difference between the "normal" standard installation and the standard installation created by the administrative installation: if you had the VS .NET Bootstrapper plug-in installed when you built the setup package, the standard installation created by the administrative installation doesn't copy the plug-in, so it can be started only by running the Windows Installer package (.msi).

Uninstalling

An administrative installation is not added to the list of Currently installed pro grams in the Add or Remove Programs Control Panel applet. So, how do you uninstall it? It's simple really, because all an administrative installation does is to create a Windows Installer image at the specified network location. Deleting the file(s) and possibly the folder in which you created the Windows Installer image is all it takes to uninstall the installation.


Using No-Touch Deployment

The .NET Framework comes with a new feature for deploying desktop applications over the Internet, called no-touch deployment, also known as auto deployment. It's to be used with stand-alone desktop applications, which generally means Windows forms, but also can include console applications.

Note

Web applications and Web services are invoked from a client, but they run on a server, which is why no-touch deployment is not possible for these types of projects.

The idea is to run your desktop application from a Web server, but how do you do that, unless it's a Web application? Well, you need an intermediary appli cation on your machine, a sort of a stub that downloads and executes the actual (remote) application. This stub doesn't need to be updated, because all it does is invoke the application located on and downloaded from a Web server. When you need to update your application, you simply update it on the Web server, and anyone using it will automatically get the updated version the next time he or she runs the application. This works in a manner similar to opening a Web application.

Setting Up the Remote Application

To demonstrate how to set up a remote application for no-touch deployment, we've created an example application, AutoDeploymentApplication, which you can find in the Chapter 15 folder of the accompanying sample code (available from the Downloads section of the Apress Web site, at http://www.apress.com).

The sample application is a Windows application with a single form con taining a button and a label. When the button is clicked, the label text is changed to contain the name of the application domain. This way, you can see how the application is invoked.

Tip

You can find a description of application domains at http:// msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconapplicationdomainsoverview.asp.

You need to upload the executable[10] for this application to a Web server with the .NET Framework installed and create a virtual directory. For test purposes, you can use the Web sharing functionality of your local development machine with Windows XP installed.

Once the remote application is set up on a Web server, you can invoke it from a client. If the assembly on the Web server is an executable, you can actually do it from a browser, by simply typing in the URL in the address field of the browser.

Note

You need Internet Explorer 5.01 or later installed, if you want to use no-touch deployment from your client.

In Exercise 15-8, you'll set up the sample remote application.

Exercise 15-8
Start example

  1. Browse to the Chapter 15 folder, right-click the AutoDeploymentApplication folder, and select Options from the pop-up menu.

  2. This brings up the folder properties dialog box, in which you select the Web Sharing tab, as shown in Figure 15-31.

    Click To expand
    Figure 15-31: Folder properties dialog box of Windows XP

  3. Select the Share this folder option, which brings up the Edit Alias dialog box, as shown in Figure 15-32.

    Click To expand
    Figure 15-32: Edit Alias dialog box

  4. In the Edit Alias dialog box, give the virtual directory[11] a name, or alias as it's called here. Give the alias any name you like, or simply keep the default name, which is the same as the physical folder for this simple example.

  5. Keep the default settings, which will suffice for our demonstration, and click OK twice to enable the Web sharing of the folder containing the executable.

  6. Execute the Web application by typing in this address in the browser address field: http://localhost/autodeploymentapplication/ autodeploymentapplication.exe. This brings up Form1 of the Windows application.

Click To expand

The label states that the application has been invoked from the localhost appli cation domain. In other words, it's executed in the same context as the browser.

End example

In the Chapter 15 folder of the accompanying sample code, you can also find the AutoDeploymentStub console application project, which invokes the AutoDeploymentApplication Windows application. For this purpose, you need some functionality from the System.Reflection namespace for loading the Form1 class from the executable assembly. It's fairly simple, as you can see from Listing 15-1.

Listing 15-1. No-Touch Deployment Stub
Start example
 1 Imports System.Windows.Forms
 2 Imports System.Reflection
 3
 4 Module Module1
 5    Sub Main()
 6       Dim remoteAssembly As [Assembly]
 7       Dim remoteObject As Object
 8       Dim remoteForm As Form
 9       Dim classType As Type
10
11       ' Load remote assembly using URL
12       remoteAssembly = [Assembly].LoadFrom( _
13          "http://localhost/AutoDeploymentApplication" & _
14          "/AutoDeploymentApplication.exe")
15       ' Retrieve the class type
16       classType = _
17          remoteAssembly.GetType("AutoDeploymentApplication.Form1")
18
19       ' Create instance of, type cast, and show the form
20      remoteObject = Activator.CreateInstance(classType)
21       remoteForm = CType(remoteObject, Form)
22       Application.Run(remoteForm)
23    End Sub
24 End Module
End example

In Listing 15-1, you can see the entire contents of the Module1.vb VB .NET code module. By default, the Main procedure is automatically executed when you run a console application. So, we've chosen to put our code in this procedure.

Note

The code in Listing 15-1 is very simple, and we have not included any exception handling.

The code works as follows:

  • Lines 1 and 2 import the namespaces we need for the application to execute the remote assembly: System.Reflection for the actual loading of the assembly and System.Windows.Forms for displaying the Windows form in the loaded assembly.

  • Lines 6 through 9 hold the variable declarations.

  • Lines 12 through 14 are where the loading of the remote assembly takes place using a URL. Note that the LoadFrom method of the Assembly class is overloaded and it can also take security options as a parameter, if needed for your particular setup.

  • Lines 16 through 17 retrieve the type of class using the GetType method of the Assembly class.

  • This type is used for creating an instance (Object) of the type on Line 20, and then the instance is type cast to a Windows Form object on Line 21.

  • Finally, we display the form on Line 22.

If you didn't follow the steps in Exercise 15-8 for setting up the remote appli cation, you might have a different address for the remote application, which means you need to change the URL on lines 13 and 14. In addition, you might need to change the namespace and class name specified on line 17.

When you execute the stub and click the button, you get this result:

Click To expand

The label states that the application has been invoked from the AutoDeploymentStub.exe application domain. In other words, it's executed in the same context as the local stub executable.

Clearing the Application Download Cache

When you execute the executable located on a remote server, or even on the local machine using a URL, the application executable is actually downloaded to the local machine and placed in the application download cache. The application download cache is an area on your disk (usually \Windows\assembly\Download) that is specifically used for caching assemblies that are executed via a URL. Each time you call the remote application, the .NET Framework checks the cache to see if a version exists, and if so, it automatically compares the version in the cache with the one on the server.

Note

Unlike normal .NET version checking, the auto deployment check is done using the name, date, and timestamp of the assemblies, rather than the assembly version, even if it's strong named. However, if you do give your assemblies a strong name, the actual name of the assembly will change when a new version is built, which also means that it will be downloaded, even if the date and timestamp are older on the assembly on the server compared to the one in the cache. If necessary, the newer version is downloaded from the server.

If you have a lot of applications that are auto-deployed, you need to clear the download cache now and then, because the download cache will hold a copy of each downloaded version of any assembly you download. You can see the content of the download cache in Windows Explorer, but you cannot manipulate the content of the download cache using Windows Explorer. Instead, you can use the .NET Global Assembly Cache Utility from the command line (Gacutil.exe) to clear the download cache, like this:

Gacutil /cdl
Note

You cannot manually install assemblies to the download cache. This is done automatically when you execute assemblies using a URL.

[10]A DLL assembly works just as well, when invoked from the stub. However, this example can be used only with EXE assemblies, not DLL ones.

[11] Virtual directory is the IIS term for the Web sharing Alias term. Do feel free to use IIS for setting up the virtual directory, if that suits you better. We just think it's easier this way.


Deploying to Multiple Target Machines

If you need to deploy an application to several target machines, you can use one of several methods:

  • No touch deployment: This technique allows you to deploy a remote application automatically, as explained in the previous section.

  • Active Directory deployment: If you need help and hints on how to use Active Directory and the Group Policy feature for deploying your solutions across a network, check this link: http://msdn.microsoft.com/library/default.asp?url=/library/enus/dv_vstechart/html/ vstchdeployingvsusingactivedirectory.asp. The article covers how to deploy VS .NET 2003, but you can use the same technique to deploy your own .NET solutions.

  • Microsoft Systems Management Server (SMS) deployment: If you need help and hints on how to use SMS for deploying your solutions across a network, check out this link: http://support.microsoft.com/default.aspx?scid=kb;en-us;327792. The article covers how to deploy VS .NET 2003, but you can use the same technique to deploy your own .NET solutions.

  • Administrative installation: This technique allows you to set up a network installation, as described in the "Running Setup Projects" section earlier in this chapter. This is a multiple-target deployment option, as well as an option of the Windows Installer.


Deploying New Releases and Patches

After your software has been deployed on a number of machines, you may need to upgrade or update it, which will require deployment of the patch or new release to the users. We looked at how you get information about defects and desired functionality from your users in the "Maintenance" section of Chapter 6, but once you've implemented the changes, how do you get the updated version to the users? Here, we'll cover how to deploy releases and patches to software that runs on the client (not Web applications or Web services).

Planned Releases

Planned releases are generally the easiest to deploy, because they involve deploying the complete software, which means the full setup package. Generally, this means that you upgrade your existing deployment project to include all the new assem blies and other files that must be deployed. This is basically what we've been covering throughout this chapter. However, in most cases, you want to remove existing versions of your software when installing a new one. To do this, set the RemovePreviousVersions property of the setup project to True. You must also make sure the UpgradeCode property is set to the same GUID as any deployed versions. This way, it can be uninstalled.

Note

Make sure you keep the UpgradeCode property value the same for all your versions, unless you specifically want the users to be able to have two versions of the software installed. This is sometimes desired, if you add new functionality to a new version, breaking functionality with previous versions, or you drop functionality that exists in previous versions.

Patches

There's no patch management functionality in the VB. NET setup and deployment tools. However, you do have a few choices, including these:

  • Deploy the full setup package including the patch files.

  • Deploy the patched file(s) as a hotfix package.

  • Invest in a third-party product.

    Note

    Whichever option you select when deploying patched files, make sure you back up the files you replace, or leave the existing shared assemblies, so the user can reverse/uninstall the patch.

Deploying the Full Setup Package

If you deploy only smaller applications, by means of a CD or DVD, deploying the full setup package including the patch files is a good option. It's a way to remove the existing version and leave only one version of your application installed on the user's machine.

However, if you don't want to deploy using a CD or DVD, and perhaps want to make the download available online, you will need some information about the users' capabilities when it comes to download capacity. It's true that many people have cable, xDSL, or similar fast connections, but you'll find some users get annoyed about having to download a full setup package, in order to fix a minor (but important) defect.[12] In this case, you might be better off deploying a hotfix package instead.

Deploying a Hotfix Package

Deploying a hotfix package has been rather popular over the last few years, and you can see that Microsoft takes this approach. You've probably seen the many Windows operating system hotfixes from Microsoft in between Service Pack (SP) releases. If they can do it, so can we, right? Yes and no. Yes, because it's widely accepted and it limits the size if the setup package to deploy. No, because it can be problematic to remove a hotfix once installed.[13] Although you can deploy the file patch as a separate application, you also need to associate the patch appli cation with the existing application. Here's what that means:

  • Deploy as separate application: Your patch will be installed on a machine as an application that can be removed from the Add or Remove Programs applet in the Control Panel. This is recommended because you can now remove the patch and roll back to the previous version of the patched file, in case it causes problems.

  • Associate with existing application: This means that whether you install the patched files as an application or just replace the existing version of the patched file, you need to make sure that the patch is removed if the application is uninstalled.

If possible, we recommend that you deploy your patch as a new application (but you can describe it as a hotfix package).

Investing in a Third-Party Product

If you're deploying small applications, and don't need any other functionality supplied by a third-party tool, there's no need to go down this road. We recommend that you deploy the full setup package including the patched files.

However, if you deploy large applications or need other functionality supplied by a third-party package, we recommend that you check out the number of third- party setup software packages available for Windows and VS .NET in particular. One package we recommend is Wise for VS .NET. You can find more information about Wise for VS .NET at http://www.wise.com/wfvsn.asp.

Start Sidebar
Missing Deployment Functionality

Although VS .NET offers many setup and deployment features, especially compared with previous versions, there are a number of features that are missing or could be improved.

  • Setup packages with optional parts: Currently, all VS .NET setup and deployment packages support only all-or-nothing installations, which is in contrast to Orca.[14] We think that the user should be able to choose whether to install optional parts of your setup package.

  • Easy way to create patches and updates: It's cumbersome to deploy patches to an existing desktop installation. We believe that it's necessary to have a simple way of creating a patch or an update to an existing installation, without needing to deploy the whole package again.

  • User management: The installation package should be able to query the user about which user account should be used to run the application being installed, including the creation of a new user.

  • Bootstrapping of external executables: Including third-party executables that must be run on the target machine as part of the setup is too cumbersome. We need an easy way of bootstrapping executables, without needing to modify the Microsoft Bootstrapper manually.

The list is by no means exhaustive, and we would like to hear from you about what you think could be improved with the deployment tools available.

End Sidebar

[12]You could be vague about the defects and fixes you're deploying to get over the hurdle of the users being annoyed about the size of the setup package, but this could backfire, because the users may feel that you're inflating the problem and the work needed to fix it.

[13]This may be improved with Windows Installer 3.0 and possibly the next version of VS .NET, code-named Whidbey.

[14]VS .NET provides an easy way to create a Windows Installer database. You can also do this manually using Orca.exe, available from the Platform SDK, http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/orca_exe.asp. However, we think that's a complete nightmare to use.


Summary

In this chapter, we looked at how you can use VS .NET for deploying your appli cations. We introduced the various VS. NET editors used with setup and deployment packages, and then worked through examples of deploying Windows and ASP.NET applications. Next, we covered deployment issues, such as those relating to the .NET Framework and security. Then we addressed customizing setup projects, versioning, and localization issues. Finally, we talked about building and running setup packages, no-touch deployment, and deploying updates.

In the next chapter, we'll get our feet wet. We'll be looking at creating an internal project, using the techniques described in the previous chapters in this book, including UML and MSF.


Part IV: Hands-On Projects

Chapter List

Chapter 16: Hands On: An Internal Project
Chapter 17: Hands On: An External Project


Chapter 16: Hands On: An Internal Project

Overview

This chapter will guide you through the processes of enterprise modeling, using the knowledge you've gained so far. In addition, we'll discuss some practical issues, such as which diagrams are best to create and to what degree they should be refined.

You will work through designing a simple VB .NET application for a fictional company named ITReady. ITReady is an enterprise company that wants a solution for tracking time used on projects. It will be an internal system, and only employees of the company will use the solution. The hands-on example in this chapter uses existing components from the customer's enterprise. You'll also see how we apply the principles of MSF to the entire project.

In this chapter, we will focus on the process and diagrams. You'll learn which diagrams to use and how to model the diagrams. In the next hands-on example in Chapter 17, where the components will be built from scratch, we'll focus more on technology and the code.

We suggest that you read this chapter from start to finish and follow the exer cises to create the diagrams. This will make this sample project as "real" as possible, and you will get the modeling practice. If you're uncertain about how to model a certain scenario, refer back to Chapter 4 or 5. We use VEA for all our modeling, although just about any UML modeling tool can be used.


About ITReady: The Background Story

ITReady is an IT company developing IT and marketing solutions for customers. Eight people are employed by ITReady; all are involved in the projects. ITReady needs a system that can keep track of the time spent on the various projects.

In this example, you have agreed with ITReady to develop the solution on time and materials, meaning that all your expenses and hours spent will be covered. This is the preferable situation and the least complicated one, because you can proceed with the project without delving into MSF estimates, devel opment strategy, and so on. In this hands-on example, we'll focus on the design process, rather than the MSF project process. We will, however, relate to MSF during the design process whenever appropriate. This also means that we won't consider making "current state" assessments describing how ITReady currently handles the task.

ITReady Infrastructure

ITReady has the following IT infrastructure:

  • Pentium IV-based workstations with 256MB RAM running Windows XP, for all employees

  • Pentium IV-based server with 512MB RAM running Windows Server 2003; functions as the Global Catalog and domain controller in an Active Directory setup, with all workstations as members of the domain; Microsoft SQL 2000 is also installed

  • Fast Ethernet (100MHz) network interface cards (NICs) on all computers

  • 2MB Internet connection through the xDSL router functioning as the gateway

All employees are created as users of the ITReady domain.

System Requirements

Here's a short description of the system requirements. These are the requirements the ITReady managing director presents to you. She wants you and your devel opment team to create the solution for the company.

  • Each employee must be able to register the hours he or she has spent on a specific project-related task.

  • It must be possible to add, delete, and change projects available, but only the administrator will be able to perform these tasks.

  • The employees must be able to add, delete, and change their personal time entries, but this applies to only those entries not yet validated and approved by the administrator.

  • Both the administrator and employees must be able to create reports. However, employees can create reports based only on their own personal time entries.

  • The administrator must validate and approve time entries submitted by the employees. Disapproved time entries must be marked Disapproved, and a notification must be sent to the employee.

  • ITReady has an existing COM component (ITREmail) that simultaneously sends and logs e-mail. If the proposed solution sends out e-mail messages, ITReady want you to use the ITREmail component.

Your first task is to capture the system requirements, so you know what to develop.


Capturing the System Requirements

Capturing the system requirements happens in the first MSF phase, which is the envisioning phase. In the envisioning phase, the product manager is responsible for collecting the high-level requirements. Figure 16-1 shows the MSF Process Model, including the externally visible milestones.

Click To expand
Figure 16-1: MSF Process Model
Note

Product manager is an MSF role. In the hands-on example in this chapter, let's assume that for now, you've been assigned this role. See Chapter 20 for details on MSF.

Identifying the Preliminary Solution Actors

Based on the system requirements information, you can identify the actors to the solution. The actors are those persons or things receiving information from or delivering information to the solution. Two actors can be identified: Employee and Administrator.

In Exercise 16-1, you'll add these two actors to a use case diagram.

Exercise 16-1
Start example

  1. Open VEA, if it's not already open.

  2. Create a new UML model.

  3. Create a new use case diagram.

  4. Drag two Actor shapes onto the use case diagram and name them Administrator and Employee. Your use case diagram now looks like Figure 16-2.

    Figure 16-2: Preliminary solution actors

End example

Identifying the Processes at a High Level

The next task is to identify the high-level functionality for the solution. This func tionality will translate into processes in the solution.

You'll identify the processes at a high level. It's early in the analysis phase, so the aim is just to get an idea of what you're about to develop. As you learned in Chapter 2, the processes will often be verbs in your requirements description or functional specification.[1] You can identify the verbs (possible processes) listed in Table 16-1 from the system requirements description.

Table 16-1: Verbs Identified from the System Requirements Description
Verb(s) | Description
Register | An employee can register the hours spent working on a project.
Add, delete, and edit | The administrator can add, delete, or edit projects.
Add, delete, and edit | The employee can add, delete, or edit personal time entries.
Create reports | Employees and administrators can create reports.
Approve | The administrator validates and approves time entries.
Send | The solution automatically sends a notification to employees about disapproved time entries.

In Exercise 16-2, you'll create the processes in a use case diagram based on the verbs in Table 16-1 and with the actors from Figure 16-2.

Exercise 16-2
Start example

  1. Open the use case diagram created in Exercise 16-1, if it's not already open.

  2. Add the verbs from Table 16-1 to the use case diagram as use cases, but translating the add, delete, and edit verbs into the unifying term maintain. Your use case diagram should now look like Figure 16-3.

    Click To expand
    Figure 16-3: Verb-based use case diagram with identified actors and processes

End example

Clarifying the System Requirements

With your preliminary use case diagram (Figure 16-3) in hand, you're ready to meet with the customer and ask the right questions. The "right questions" are those clarifying to you and the customer what you're about to develop and what the solution will actually do.

The first question you'll probably ask the ITReady managing director is if the high-level functionality is correctly described by your use cases. Let's say that the following questions are asked and answered (your Q&A list) at your meeting:

Question: Does a time entry always relate to a project?

Answer: Yes.

Question: Is it possible to relate to specific tasks within a project? Are the project tasks always similar among projects?

Answer: No, different projects will have different tasks.

Question: Would it be a good idea if the administrator can maintain tasks as well?

Answer: Yes, we need to be able to do that.

Question: Is the report generation similar for the administrator and the employee?

Answer: Yes.

Question: Are the report types available the same for the administrator and the employees?

Answer: No, the employee can generate a personal report only, while the administrator can generate both a personal report and a totals report.

Based on the answers to these questions, you can add another two processes, which you didn't find when identifying verbs: the Maintain Tasks process and a split of the Create Reports process into two processes—one for personal reports and one for totals reports.

Tip

A process is likely to be divided into two separate processes if the process is used by two different actors for different purposes.

In Exercise 16-3, you'll add the new processes to your use case diagram.

Exercise 16-3
Start example

  1. Open the UML model from Exercise 16-2, if it's not already open.

  2. Add the Maintain Tasks use case.

  3. Split the Create Reports use case into two use cases: Create Totals Report and Create Personal Report. Your use case diagram should now look like Figure 16-4.

    Click To expand
    Figure 16-4: Q&A-based use case diagram with identified actors and processes

End example

Adding Preliminary Relationships

If you and your customer can agree that the processes identified represent the solution functionality, the next step is to add relationships between the processes and the actors. Some of the relationships are obvious, but a few are not.

Using the Q&A list, you found out that both employees and the administrator can generate a personal report. You have two ways of modeling that:

  • Draw a communicates relationship between the Administrator actor and the Create Personal Report use case, and between the Employee actor and the Create Personal Report use case.

  • Draw a communicates relationship between the Employee actor and the Create Personal Report only.

Which method you choose depends on what you want the diagram to show. If the administrator can generate a personal report for any specific employee, you should draw a relationship from the administrator to the Create Personal Report process.

If the administrator can generate a personal report for his or her own per sonal time entries only (just like an ordinary employee can do), you shouldn't create a relationship between the administrator and the Create Personal Report process. The reason is that if the administrator generates the same result as an employee when creating a personal report, then the administrator is actually playing the role of an employee at that moment. In other words, if the (physical) administrator uses the solution to create a report of his own time entries, he is acting as an employee. In UML, you distinguish only between roles, not physical persons.

Tip

UML distinguishes between roles, not physical persons. If two actors use the same process and are acting the same role when using the process, you should draw only one relationship.

Another consideration is how to model the Send Disapproval Notification process, which is triggered by the solution, not by an actor. In this situation, the process is often used by another process, because all your processes as a unit form the solution. If this is the case, you draw a relationship between the used process and the process(es) that use it. In our example, the Approve and Validate Time Entries process uses the Send Disapproval Notification process. The Send Disapproval Notification process is not used every time the Approve and Validate Time Entries process is executed; it's used only if one or more of the time entries are disapproved. So, you draw an extends relationship between these two pro cesses, indicating that the Approve and Validate Time Entries process decides whether to use the functionality in the Send Disapproval Notification process. This is in contrast to the uses relationship, which indicates that the functionality is always used.

In Exercise 16-4, you'll add relationships to your use case diagram.

Exercise 16-4
Start example

  1. Open the UML model from Exercise 16-3, if it's not already open.

  2. Draw a communicates relationship between the Administrator actor and the following use cases: Approve and Validate Time Entries, Create Totals Report, Maintain Projects, and Maintain Tasks.

  3. Draw a communicates relationship between the Employee actor and the following use cases: Register Hours, Create Personal Report, and Maintain Time Entries.

  4. Draw an extends relationship between the Approve and Validate Time Entries and Send Disapproval Notification use cases. Your use case diagram should now look like Figure 16-5.

    Click To expand
    Figure 16-5: Use case diagram with relationships

End example

[1]Remember that the functional specification in MSF terminology is much more than describing requirements and features. This is discussed in Chapter 20.


Deciding Which UML Models to Create

You might wonder why we've started the modeling with a quick pass over the use case diagram. You might also wonder if we're going to start the other diagrams right away, or if the use case diagram in Figure 16-5 should be refined first. It's not easy to answer this question, because it depends on the complexity of your project. We'll try to provide you with an overview of how to start your UML modeling. However, keep in mind that these are just general guidelines, not required check lists. As you've already figured out, with UML, what you should do depends on the particular situation.

When you enter the "refinement" phase of your design, you're most likely in the planning phase of the MSF Process Model (see Figure 16-1). In the planning phase, your vision scope document has been signed off, and your project team is working on the project. In the planning phase, the program manager is respon sible for the project and is the primary driver of the project.

Which Diagrams Are Mandatory?

A few types of diagrams are more frequently created than others, and you could refer to them as "mandatory" diagrams (although, in theory, nothing is mandatory):

Use case diagram: You'll almost always want to start creating use case diagrams, because the use case diagrams provide you with a high-level perspective of the solution requirements. They are presented in such a way that your customers can understand them and participate in their creation.

Sequence diagram: The natural step after creating use case diagrams is to create sequence diagrams. Remember that your use cases/processes actually consist of a sequence of tasks that the processes perform. By creating sequence diagrams, you have the opportunity to analyze the processes and maybe find a way to optimize one or more of them. Second, you can identify candidate classes from your sequence diagrams, which is very helpful when creating class diagrams. Finally, sequence diagrams are excellent for having a dialogue with the customer, discussing whether the sequence diagrams reflect the requirements. You can even create a prototype based on your use cases.

Class diagram: Class diagrams are the heart of your UML modeling,[2] because they show exactly how the solution should be developed. Also, you can generate code from the class diagram.

Note

In VEA, class diagrams are called static structure diagrams. Most of the time, these are the same as class diagrams. However, VEA allows you to create other types of diagrams using the same elements. For example, you can create an object diagram, which is simply a diagram showing objects and how they relate, instead of showing classes as on class diagrams. Other UML tools tend to call this type of diagram a class diagram, focusing on classes, and we'll use that terminology here.

As you can see, three diagrams seem to be mandatory when modeling UML. We consider especially the use case diagram and class diagram as mandatory, and the sequence diagram as mandatory in most cases. However, it depends. Suppose you receive a component from a third-party vendor, and you want to model this component in UML, giving you some kind of documentation. In this case, you probably will not create a use case diagram and sequence diagram, but simply model the component in a class diagram and subsequently a component diagram.

In most projects starting from scratch, you'll want to create the use case diagram, the sequence diagram, and the class diagram. If you're new to UML, you can be sure that these three diagrams will be important.

When Should You Create Other Diagrams?

Along with the use case diagram, sequence diagram, and class diagram, you may need to create other types of UML diagrams to accommodate the needs of your project. In this section, we'll present some examples of typical situations you might face in your career as a software developer/analyst. For each situation, we've outlined the diagrams that are likely to be relevant. Again, keep in mind that there are no standards when it comes to UML. Consider this section as guidance only.

When moving from use case diagramming to creating the other UML diagrams, the developers become the primary drivers, because the considerations become more technically oriented. The project is still in the MSF planning phase, and it will remain in that phase until the project plan and functional specification are complete and signed off. After that, the project moves into the development phase (refer to Figure 16-1).

The Requirements Are Too Complex to Understand

In the sample project we're discussing in this chapter, it's easy to see the overall structure, and you could probably comprehend the requirements and start coding immediately. However, in many projects, it's not at all obvious what the solution is expected to do.

For example, suppose that you're developing a solution for real-time stock trading. Understanding the processes and business rules involved in such a solution is difficult, and you might not be able to create your high-perspective use case diagram (as in Figure 16-5) until you fully grasp the business and the processes involved. So, you need to create some diagrams to help you understand the business. One such diagram that can help is the activity diagram. You can use the activity diagram to create an overview of the business processes (recall from the discussion in Chapter 4 that activity diagrams relate to a use case, process, or class).

Other models that you might want to use before creating the high-level use case diagram include the following:

Current state assessment: If you are about to develop a solution that will replace an existing solution, you might learn a lot from the existing solution. Making a current state assessment can be very valuable. A current state assessment is a UML model. You should keep this UML model separate from your solution model.

Business model: In Chapters 2 and 4, you learned about business modeling. Business modeling is an excellent way to get to know the business. In business modeling, your actors will be business actors, and your use cases will be business use cases that describe the business, not (necessarily) your solution. The business model should be placed in the same model as your solution model, but you should place all your business diagrams and elements in a different package to separate them from your solution model.

You're Not in Control of Deployment

If you're not in control of the deployment, it can be very valuable to create a deployment diagram. This can help to ensure that your solution can be properly deployed. Of course, a deployment diagram also can be valuable when you (or your team) are deploying the solution, especially for documentation and recovery purposes. Usually, you will not create a deployment diagram for very simple and trivial solutions, where the deployment is straightforward. We cover deployment in Chapter 15.

One of Your Components Depends on a Third-Party Component

If one of your components is a third-party component, or your components are deployed in a complex way, it's a good idea to create a component diagram. This type of diagram shows the components, their dependencies, and their interfaces.

However, knowing when a solution's components are so complex that com ponent diagrams should be created is the real trick. If, for example, you have a very simple solution with only one component that does something trivial, you might not benefit from creating a component diagram. On the other hand, if you have hundreds of components in your solution, some of them dependent on others, you'll definitely benefit from creating a component diagram.

Tip

Create only the diagrams you can benefit from in the particular project.

Your Class Is Too Complex to Understand

In some solutions, you might have classes enforcing business rules that are so complex that it's hard to tell if the class behaves exactly as the business rule suggests. An example of a complex project like this is a real-time stock trading solution. In this case, it can be beneficial to create a statechart diagram. In a state- chart diagram, you can see the sequence of states an object goes through during its lifetime and the external events that affect the class.

Note

If you want to describe the internal flow, you should create activity diagrams, not statechart diagrams.

You might wonder why we haven't mentioned collaboration diagrams so far. Collaboration diagrams are similar to sequence diagrams and can be used in similar situations. The collaboration diagram tends to be used when you wish to focus on the organization of your objects, rather than on your procedural flow.

[2]Notice that we are looking through the developer's eyes here. From a user perspective, the use cases are the heart of the UML modeling.


Modeling the Use Case Diagram

In the "Capturing the System Requirements" section, you modeled a use case diagram, but that was merely for quickly gathering the high-level requirements. Now, it's time to start the "real" use case modeling and refine the use case diagram you already made.

When you start creating the use case diagram for real, it's important that you don't rely solely on the information from the sponsor (customer representative). You need to get firsthand information about the processes from those actually performing the processes.

If your users (those who will be using your solution) agree with you that the processes identified are what the solution should do, the next step is to find out what each process does (again, by asking those who perform the process). For each process, you need to document the sequence of tasks that form the process. It's a good idea to start with the most important processes, so that you'll discover any problems with the mandatory system processes at an early stage. Mandatory system processes are the processes that your solution can't function without. For example, the Register Hours process is a mandatory process in our example.

In addition, some of the not-so-obvious use cases might end up being removed from your solution. You don't want to bother with use cases that turn out to be redundant, do you? If you and your team are uncertain about which processes to start with, begin by creating an ordered list of your use cases, starting with the most important.

Considering Use Case Amounts and Details

Before we start creating the sequence descriptions for the use cases, let's address two common questions regarding use cases:

• How many use cases should normally be created for an ordinary solution?

• How detailed should the use cases be?

It's tempting just to answer, "It depends," because that is the truth. However, that answer doesn't seem to satisfy many of those asking. Here, we'll give you our point of view. Just remember that it's subjective, and others might have different opinions.

How Many Use Cases Should You Use?

If you have so many use cases that you can't fit them all into a single use case diagram, you have too many. If you have too many use cases, it's often the case that you're actually mixing two systems in the same model, which is generally not a good idea. For example, if your project for ITReady should integrate with an accounting system (which you're also going to develop), it's tempting to include those use cases in the model as well. But this is the wrong approach, because they are two different systems.

Figure 16-6 shows an example where the two use cases, Accounting System and Create Invoice, have been added to Figure 16-5, indicating that the accounting department uses the validated time entries to create invoices for the specific projects. This is not correct UML modeling!

Click To expand
Figure 16-6: Use case diagram mixing use cases from two different systems

First, the Accounting System use case isn't a use case in your solution; it's an actor. It's something that acts on your solution (receives information about vali dated time entries). The Create Invoice use case shouldn't be included in your model at all. It is not a use case in your solution. If you want to model the relationship with the Accounting System, the right way to do it is as shown in Figure 16-7.

Click To expand
Figure 16-7: Use case diagram showing relation to another system

When you model a relationship with another system, you might want to have the name and reading direction displayed for the communicates relationship between the actor representing the other system and the use case it relates to, as shown in Figure 16-7. Exercise 16-5 demonstrates how to do this.

Exercise 16-5
Start example

  1. Open the UML model from Exercise 16-4, if it is not already open.

  2. Add an actor named theAccountingSystem to the use case diagram.

  3. Draw a communicates relationship named Receives validated list between the Approve and Validate Time Entries use case and the theAccountingSystem actor.

  4. Right-click the Receives validated list communicates relationship and select Shape Display Options from the pop-up menu. This brings up the Shape Display Options dialog box. Select the Name option only, clearing the default selections for the First end name, Second end name, End multiplicities, and End navigability options, as shown in Figure 16-8. Then click OK.

    Click To expand
    Figure 16-8: Shape Display Options dialog box

  5. Once you've set the display options, you need to set the properties. Double-click the Receives validated list communicates relationship to bring up the UML Association Properties dialog box. Set the name to Receives validated list, and choose forward for the Name Reading Direction option, as shown in Figure 16-9. Then click OK. Your use case diagram now looks like Figure 16-7 (shown earlier).

    Click To expand
    Figure 16-9: UML Association Properties dialog box

End example

The conclusion to the question and this section is that you shouldn't model use cases that don't strictly belong to your primary solution.

How Detailed Should the Use Cases Be?

The question about how detailed the use cases should be is a little easier to answer than the previous question. A use case should be so detailed that it performs a single process only. This means that you should not have a use case that both maintains tasks and maintains projects (referring back to our ITReady example), because these are two different processes. Ask yourself, "Is it possible to maintain tasks without having to maintain projects?" If the answer is yes, you should create two processes. If the answer is no, you can create a single process.

Tip

If a use case contains one task that can be performed without needing to perform the rest, you should create two use cases.

We'll cover the details necessary for the use case content (the sequential description), in the next section.

Adding Use Case Content

The next task is to create the use case content, starting with the most important processes. The use case content is a sequential description of what the use case does.

In our solution for ITReady, we have the following use cases (see Figure 16-5 earlier in this chapter):

  • Maintain Projects

  • Maintain Tasks

  • Approve and Validate Time Entries

  • Send Disapproval Notification

  • Create Totals Report

  • Maintain Time Entries

  • Create Personal Report

  • Register Hours

You want to start working with the most important use cases, so you need to order them. Arranging your use cases in order of importance is also of great benefit for assessing development iterations, assessing risk, and planning a testing approach later. The most important use cases are those your solution can't function without. You can order your use cases for the ITReady example as follows:

  • Register Hours

  • Maintain Time Entries

  • Maintain Projects

  • Maintain Tasks

  • Approve and Validate Time Entries

  • Send Disapproval Notification

  • Create Totals Report

  • Create Personal Report

You can also describe in plain text what the use case is intended to do. A description in plain text has several purposes. First, the description is your way of capturing the information you've gathered during the initial meeting. This can be important information when preparing the user interviews. You might not be the one doing the interviews, so the description can provide particularly valuable information. Second, the description in plain text can be helpful for the developers to know exactly why the sequence is created the way it is.

In some cases, it makes sense to start describing in plain text what the use case is intended to do, and then as the next step, interview the users in order to describe the sequential process. To complete the use case description, you need to know exactly what your solution needs to do to perform the process.[3] The best way to get that knowledge is to interview the users.

The following sections describe the content for each use case, which is written as plain text in the Documentation text area in the UML Use Case Properties dialog box.

Register Hours (Use Case)

The Register Hours use case is the heart of your solution. Figure 16-10 shows the UML Use Case Properties dialog box with a description of what the use case does.

Click To expand
Figure 16-10: UML Use Case Properties dialog box with plain text documentation

In Figure 16-11, you can see the complete use case description. It includes the sequence of tasks the use case performs, along with a precondition and a postcondition.

Click To expand
Figure 16-11: UML Use Case Properties dialog box with the complete description

As you can see, the precondition is that the user is logged on as an employee. This means that the Register Hours use case can't be triggered if this precondition isn't fulfilled. This may indicate that you need a Logon use case in your solution, but at this point, you don't know that for sure. If, for example, your solution accepts Windows authentication, the solution knows the user without asking for a logon.

Even though you define a precondition, you don't need to specify a post condition. If you need a postcondition but don't know what it will be, you can set the postcondition to None and specify it later when refining the use case.

The use case description describes a single process, where each step makes sense only in the context of a use case; it can't be used on its own. So, for now, the use case is complete.

In Exercise 16-6, you'll add the content for the Register Hours use case.

Exercise 16-6
Start example

  1. Open the UML model from Exercise 16-5.

  2. Double-click the Register Hours use case to open the UML Use Case Properties dialog box.

  3. Add the following text in the Documentation text box:

    The employees can register the hours spent on a project specific task. They must be logged on, and they can register their own hours only up until and including the current date.

    Pre-Condition: The employee is logged on.

    1. Open Time Sheet window.

    2. Select empty time entry row.

    3. Enter the following information in the corresponding columns:

      Date, Task ID, Hours (centihours), Description.

    4. Click Save.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-11.

End example
Note

Centihour is a metric measurement that equals one-hundredth of an hour.

Maintain Time Entries (Use Case)

The next use case from your prioritized list is Maintain Time Entries. This use case is separate from the Register Hours use case, because it represents a different process, and you can perform one of the use cases without performing the other.

After your user interview, your use case documentation can look like Figure 16-12.

Click To expand
Figure 16-12: UML Use Case Properties dialog box with the complete Maintain Time Entries description

In Exercise 16-7, you'll add the content for the Maintain Time Entries use case.

Exercise 16-7
Start example

  1. In your UML model from Exercise 16-6, double-click the Maintain Time Entries use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    The employees can maintain their personal time entries. The time entries can be deleted or the information can be updated. Time entries marked as Approved can't be manipulated, and thus won't be shown.

    Pre-Condition: Employee is logged on.

    1. Select time entry.

    2. Click Delete or edit time entry information.

    3. Click Save.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-12.

End example

In this use case, you actually have two flows: the Delete entry flow and the Update entry flow. This is possible and allowed in use case documentation. However, you could choose to split the flow into two separate use cases. Why would you do that? Well, say you want to illustrate that it's possible to delete a record without needing to update a record (a trivial example, we know). Another reason is that you can then model another use case for deleting a record in your solution (and use your delete record use case). However, in this solution, you don't need to use the delete functionality elsewhere. We think it's sensible to keep the use case diagram the way it is, because having too many use cases tends to confuse the overall picture, and there's no benefit in splitting it.

Start Sidebar
Splitting a Use Case to Reuse Functionality

Although we won't follow this path in our example in this chapter, Figure 16-13 shows how the Maintain Time Entries use case might be split by adding two use cases.

Click To expand
Figure 16-13: Split Maintain Time Entries use case

Now, the diagram has two use cases for the Maintain Time Entries use case: one that contains the delete functionality and one that contains the update functionality. The advantage is that you can reuse either functionality elsewhere. For example, if you have a use case called Backup that backs up all time entries older than a year and deletes them from the solution, you could reuse the functionality in your Delete Time Entry use case. It would look like Figure 16-14.

Click To expand
Figure 16-14: A use case is easier to reuse if it contains a single process only.

You can't model what's shown in Figure 16-14 if you haven't split the use case, because then you would also have your update functionality included.

End Sidebar

Maintain Projects (Use Case)

The Maintain Projects use case is the first administrator use case to be completed. It is somewhat similar to the Maintain Time Entries use case, and its documen tation can look like Figure 16-15.

Click To expand
Figure 16-15: UML Use Case Properties dialog box with the complete Maintain Projects description

As you can see from the Documentation text field in Figure 16-15, the plain text description can be used for describing definitions, such as the ProjectID being numeric.

In Exercise 16-8, you'll add the content for the Maintain Projects use case.

Exercise 16-8
Start example

  1. In the UML model from Exercise 16-7, double-click the Maintain Projects use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    The Administrator can add, delete, or edit available projects. Projects are not employee related, meaning that all employees can register time entries on all projects. A project is identified by a numeric project ID, and a project definition consists of ProjectID and ProjectDescription.

    Pre-Condition: Administrator is logged on.

    1. Select project row (blank row for adding).

    2. Click Delete or edit the information.

    3. Click Save.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-15.

End example

Maintain Tasks (Use Case)

The Maintain Tasks use case is, in a way, dependent on the Maintain Projects use case, because projects must be created before you can add tasks to them. Would it then be correct to add a dependency relationship between them?

We don't think that's a valid approach, for two reasons. First, the Maintain Tasks use case really isn't dependent on the Maintain Projects use case. Rather, it's dependent on the list (DataSet instance?) of projects being available. Second, in UML, the dependency relationship means that the element with the depen dency also is affected by any functional changes to the element it depends on. The Maintain Tasks use case is not affected by changes to the functionality in the Maintain Projects use case; it's merely dependent on the projects being available. For example, the Maintain Projects use case might change its functionality, so it's necessary to create project descriptions in different languages. The Maintain Tasks use case will not be affected by this functionality change. All it cares about is whether the projects are available.

Start Sidebar
Adding a Dependency Relationship for External Systems

For our internal solution, adding a dependency relationship between Maintain Tasks and Maintain Projects is not a good idea. However, if the projects were created and maintained in an external system, you could place an actor representing this system and a dependency relationship to it. Figure 16-16 illustrates a dependency relationship between the Maintain Task and Maintain Projects use cases.

Click To expand
Figure 16-16: Dependency relationship between the Maintain Tasks and Maintain Projects use cases
End Sidebar

The documentation for the Maintain Tasks use case is shown in Figure 16-17.

Click To expand
Figure 16-17: UML Use Case Properties dialog box with the complete Maintain Tasks description

In Exercise 16-9, you'll add the content for the Maintain Tasks use case.

Exercise 16-9
Start example

  1. In the UML model from Exercise 16-8, double-click the Maintain Tasks use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    The Administrator can add, delete, or edit available tasks. Tasks can be project related, but only project related tasks are available for time registration. Tasks are not employee related, meaning all employees can register time on all tasks. A task is identified by a numeric task ID, and a task definition consists of TaskID and TaskDescription.

    Pre-Condition: Administrator is logged on.

    1. Select task row (blank row for adding).

    2. Click Delete or edit the information, including ProjectID if task isproject related.

    3. Click Save.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-17.

End example

Approve and Validate Time Entries (Use Case)

The next use case on your list is the Approve and Validate Time Entries use case. Figure 16-18 shows the use case description.

Click To expand
Figure 16-18: UML Use Case Properties dialog box with Approve and Validate Time Entries description

So far, the use case descriptions have been fairly simple. The Approve and Validate Time Entries use case is different, so you need to be a bit more specific. In Figure 16-18, you can see the sequence of tasks, but these are not detailed enough for the developers to start modeling the solution. You need to get more details. You can gather the details now, do that when you're modeling the sequence diagrams, or even wait until modeling the class diagram, but the earlier the better. When possible, you should make the use case descriptions as detailed as possible, as shown in Figure 16-19.

Click To expand
Figure 16-19: UML Use Case Properties dialog box with the detailed Approve and Validate Time Entries description

In Exercise 16-10, you'll add the content for the Approve and Validate Time Entries use case.

Exercise 16-10
Start example

  1. In the UML model from Exercise 16-9, double-click the Approve and Validate Time Entries use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    The Administrator can view the time entries for a specific employee and choose to approve or disapprove them. Disapproved time entries trigger a notification to the submitting employee.

    Pre-Condition: Administrator is logged on.

    1. Select employee.

    2. Select one or more not-yet-approved time entries.

    3. Click Approve or Disapprove.

    4. Click Save.

    5. Notification is sent to employee for disapproved time entries. (See Send Disapproval Notification use case)

    6. List of approved time entries is generated. It contains EmployeeID, ProjectID, TaskID, and Hours.

    Post-Condition: Generated list of approved time entries.

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-19.

End example

Send Disapproved Notification (Use Case)

In Figure 16-20, you can see the use case description of the Send Disapproved Notification use case that extends the Approve and Validate Time Entries use case.

Click To expand
Figure 16-20: UML Use Case Properties dialog box with the Send Disapproval Notification description

In Exercise 16-11, you'll add the content for the Send Disapproval Notifi cation use case.

Exercise 16-11
Start example

  1. In the UML model from Exercise 16-10, double-click the Send Disapproval Notification use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    This use case sends email notifications. The existing ITReady ITREmail COM component is preferred in the solution.

    Pre-Condition: Receives the following input parameters:

    Message (string)

    EmailTo (string)

    EmailFrom (string)

    Subject (string)

    1. Notification is logged in the Emails table.

    2. Email is sent.

    Post-Condition: Notification is logged and email is sent.

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-20.

End example

Create Totals Report (Use Case)

Create Totals is a fairly simple use case. Figure 16-21 shows its documentation.

Click To expand
Figure 16-21: UML Use Case Properties dialog box with the Create Totals Report description

In Exercise 16-12, you'll add the content for the Create Totals Report use case.

Exercise 16-12
Start example

  1. In the UML model from Exercise 16-11, double-click the Create Totals Report use case to open the UML Use Case Properties dialog box.

  2. Add the following text in the Documentation text box:

    Pre-Condition: Administrator is logged on.

    1. Select details (employee, project, and task).

    2. Select date range.

    3. Print or preview report.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-21.

End example

Create Personal Report (Use Case)

Okay, we think you've got the hang of it. Without further ado, the description of the fairly simple Create Personal Report use case is shown in Figure 16-22.

Click To expand
Figure 16-22: UML Use Case Properties dialog box with the Create Personal Report description

In Exercise 16-13, you'll add the content for the Create Personal Report use case.

Exercise 16-13
Start example

  1. In the UML model from Exercise 16-12, double-click the Create Personal Report use case to open the UML Use Case Properties dialog box.

  2. Since the description for this use case is so similar to the one for the Create Totals Report use case, you can copy and edit the description from that use case. Place the following text in the Documentation text box:

    Pre-Condition: Employee is logged on.

    1. Select details (project and task).

    2. Select date range.

    3. Print or preview report.

    Post-Condition: None

Your UML Use Case Properties dialog box should now look like the one shown in Figure 16-22.

End example

Getting User and Sponsor Acceptance

You've been through all the use cases now. Some of the use cases you've been able to describe in detail; others are less detailed. You've also seen that you should ignore all technology choices when creating use cases.

Tip

Never let your use cases be influenced by technology or technology choices. You should not let your use cases contain any connection with technology, unless you know of a technology aspect that, if ignored, would cripple the project.

Now, it's time to present your users and your sponsor with your work. You need to know that the solution you're developing as specified in the use case dia grams will be acceptable. This acceptance should be in writing.

The use case diagram will be refined as you get more information and knowledge of the solution you're developing.

In the next section, you'll start creating the sequence diagrams, which are based on the use case diagrams.

[3]Notice that it's what your solution should do, not what the people should do. If you're analyzing what the users do, you're creating a business model.


Creating Sequence Diagrams

In this section, you'll learn how to create the sequence diagrams in your solution. As with use case diagramming, you should start with the most important (or most difficult) sequence diagrams.

Here, we'll concentrate on a few sequence diagrams and create these in some detail. In your own projects, you should create sequence diagrams for all your use cases, except for trivial use cases for which a sequence diagram contributes no additional understanding.

Identifying Objects and the Events They Trigger

The purpose of creating the sequence diagram is to make it easier for the developers to understand what the use case does and to identify the objects and functional ities to develop. Sequence diagrams are always based on an interaction.

A sequence diagram consists of objects that trigger events on other objects in chronological order. You learned in Chapter 4 that objects are often nouns in your use case diagram. This is true and can certainly be helpful when identifying the objects. However, in most cases, identifying the objects is relatively easy. A great way to start is to identify the object that triggers the use case in the first place.

Register Hours (Sequence Diagram)

This first sequence diagram represents the heart of your solution: the registration of hours. It's obvious that the employee triggers this use case. So, you start by placing the employee on your sequence diagram, as shown in Figure 16-23.

Figure 16-23: Sequence diagram with an Employee object

However, just dragging an object lifeline onto the diagram isn't enough. You need to give the object lifeline a name and specify a classifier, as shown in Figure 16-24.

Click To expand
Figure 16-24: UML Classifier Role Properties dialog box with the Name and Classifier properties set

In Exercise 16-14, you'll start the Register Hours sequence diagram.

Exercise 16-14
Start example

  1. Open the UML model from Exercise 16-13, if it is not already open.

  2. Create a new sequence diagram named Register Hours.

  3. Add an object lifeline named Employee to the diagram, and set the classifier to the Employee actor.

Your sequence diagram should now look like the one shown in Figure 16-23.

End example

Then ask yourself, "What does the employee do when registering hours?" According to the Register Hours use case, the employee opens the time sheet window. So, the time sheet must be an object, and the employee triggers the Open event on this object. You can model this as shown in the sequence diagram in Figure 16-25.

Click To expand
Figure 16-25: Time Sheet object added to the sequence diagram

In Figure 16-25, you can see that we've added the Time Sheet object lifeline, two Activation shapes, and the Open Message shape. You can also see that we've added a class named TimeSheet to the Model Explorer. What you can't see from Figure 16-25 is that we have set the classifier for the Time Sheet object lifeline to this class. Actually, you can see this if you look closely, because the Open Message shape now appears as an operation on the TimeSheet class. (Yes, it's guesswork, but given the very simple sequence diagram, we think it's obvious.)

In Exercise 16-15, you'll add the rest of the tasks for the Register Hours use case.

Exercise 16-15
Start example

  1. Add an object lifeline named Time Sheet to the Register Hours sequence diagram, and set the classifier to a new class named TimeSheet (created from the UML Classifier Role Properties dialog box).

  2. Add Activation shapes to the two object lifelines.

  3. Add a message named Open between the Employee and the Time Sheet objects. The message must invoke an operation named Open on the Time Sheet object.

    Your sequence diagram should now look like the one shown in Figure 16-25.

  4. Add two messages named Add and Save to the Time Sheet object on the Register Hours sequence diagram. The messages must invoke operations with the same names (Add and Save, respectively) on the Time Sheet object itself.

Your sequence diagram should now look like the one shown in Figure 16-26.

Figure 16-26: Sequence diagram with all use case tasks

Note

If the diagram is to be 100% correct, which isn't the case at this point, the Open message, not the Add message, should be the first message on the Time Sheet activation. This is because sequence diagrams are time-based, as explained in Chapter 4, and obviously the Open message must be triggered before the Add message.

End example

The Add message/operation is the Select empty time entry row task from the use case, and the Save message/operation is (surprise, surprise) the Save task. Your sequence diagram now looks just like the use case sequence, but in a graphical way. However, this isn't sufficient for you and your developers to develop the required functionality. So, the next step is to transform the sequence diagram into something more like a pseudo-solution.

Next, you need to consider whether the employee must log on or whether the employee is automatically recognized by the solution. You know that all of the workstations are running Windows XP, and they're authenticated by a Windows Server 2003. It's an internal solution only, so it makes sense to take advantage of Windows authentication. This way, you don't need to maintain logon information in the solution. If you want to further refine the sequence diagram, you can specify that the Open and Save methods need information about who is logged on, so the time entry will be saved with the correct employee ID.

In Exercise 16-16, you'll add parameters to the Open and Save methods in your sequence diagram.

Exercise 16-16
Start example

Add a parameter named employeeID of data type string (VB) to the Open and Save messages on the Register Hours sequence diagram. To add the parameters (named arguments in VEA), double-click the message. This brings up the UML Message Properties dialog box, in which you select the Arguments category and simply type your parameters in the Arguments list. The data types are selected on the Type list for each parameter.

Note

We've chosen string as the data type, because this way we can handle any kind of employee ID, such as user name, user ID, and so on. Based on the content in the remaining sections of this chapter, you might find it more relevant to use a different data type, and subsequently change the data type.

Your sequence diagram should now look like the one shown in Figure 16-27.

Click To expand
Figure 16-27: Sequence diagram reflecting the use case and the login information

End example

The sequence diagram in Figure 16-27 is basically correct. However, by adding more details to your sequence diagram, you will make it easier to create the class diagram.

Let's say that you and your developers have discussed how the use case will be implemented in a software solution (still without mentioning any specific technology). You decide to refine the sequence diagram as follows:

  • Add a Start Page object to represent a start page (for example, an ASP.NET Web page) or an opening form.

  • From that start page, you choose to add time entries, which is indicated by a Select Add Time Entries message. This message is related to an operation on the next new object, the Time Sheet Form object. It might be a menu item, a button, or hyperlink at implementation time.

  • Add the Time Sheet Form object, which represents the form where the employees can type in their time entries.

  • Finally, the Time Sheet object receives the Add message when the form sends a message that a new time entry should be added, and it receives a Save message when the time entries added should be saved.

This is much better information for the developers. In Exercise 16-17, you'll add details to the Register Hours sequence diagram.

Exercise 16-17
Start example

  1. Add an object lifeline named Start Page to the Register Hours sequence diagram. Set the classifier to a new class named StartPage (you can create it from the UML Classifier Role Properties dialog box).

    Note

    Although it's possible to name the classes with spaces, we're thinking about the development process here. Because we apply the naming conventions discussed in Chapter 1, we remove the spaces.

  2. Add an object lifeline named Time Sheet Form to the Register Hours sequence diagram. Set the classifier to a new class named TimeSheetForm.

  3. Add an Activation shape to the Start Page and Time Sheet Form objects.

  4. Add an Activation shape to the Employee and Time Sheet objects, so they each have two activations.

  5. Connect the existing Open message to the first activation on the Employee object and the only activation on the Start Page object. Create a new operation with the same name with a parameter named employeeID of data type string (VB). Delete the Open operation on the TimeSheet class.

  6. Create a new message named Select Add Time Entries between the activations on the Start Page and Time Sheet Form objects. Create a new operation with the same name.

  7. Delete the existing Add and Save messages.

  8. Create a new message named Add between the activations on the Start Page and Time Sheet Form objects. Select the operation with the same name for the message.

  9. Create a new message named Save between the last activation on the Employee object and the activation on the Time Sheet objects. Select the operation with the same name for the message.

    Note

    When you create more than one Activation shape of the same length on a sequence diagram, it's quicker to copy an existing one, where both ends have been connected to connection points on an object lifeline. This is because the length of the activation must match the space between two connection points on an object lifeline.

Your sequence diagram should now look like the one shown in Figure 16-28.

Click To expand
Figure 16-28: Sequence diagram being made more IT-specific

End example

In Figure 16-28, you can also see that the Employee actor has two activations. This is because when an employee adds time entries, this sequence of tasks is separated from the task sequence when the employee decides to save the time entries. This shows that the employee can add time entries without saving the time entries.

Maintain Time Entries (Sequence Diagram)

The natural step to take next is to model the sequence diagram for the Maintain Time Entries use case, because it's closely related to the Register Hours use case. The two use cases are similar in the way they are triggered, which is shown in Figure 16-29. However, different choices are made on the start page.

Click To expand
Figure 16-29: The Maintain Time Entries sequence diagram

In Exercise 16-18, you'll create the Maintain Time Entries sequence diagram.

Exercise 16-18
Start example

  1. In the UML model from Exercise 16-17, create a new sequence diagram named Maintain Time Entries.

  2. Add an object lifeline named Employee to the diagram, and set the classifier to the Employee actor.

  3. Add an object lifeline named Start Page to the diagram, and set the classifier to the StartPage class.

  4. Add an object lifeline named Time Sheet Form to the diagram, and set the classifier to the TimeSheetForm class.

  5. Add activations to the Employee, Start Page, and Time Sheet Form objects.

  6. Create a new message named Open between the activations on the Employee and Start Page objects. Select the operation with the same name for the message.

  7. Create a new message named Select Maintain Time Entries between the activations on the Start Page and Time Sheet Form objects. Create and select a new operation with the same name as the message.

Your sequence diagram should now look like the one shown in Figure 16-29.

End example
Start Sidebar
Modeling Two Use Cases in a Single Sequence Diagram

The Maintain Time Entries sequence diagram looks like the Register Hours sequence diagram. So, can't you just implement the Maintain Time Entries sequence in the Register Hours sequence diagram? You certainly can, and whether you want to depend on two factors:

  • If the sequence diagrams are very complex and large, you're better off splitting them into smaller and simpler sequence diagrams.

  • If the sequence diagrams you consider merging represent two different and unrelated functionalities, they shouldn't be modeled in the same diagram.

The two use cases modeled in the same sequence diagram would look something like Figure 16-30.

Click To expand
Figure 16-30: Task sequence from two use cases in same sequence diagram

As you can see from Figure 16-30, it seems okay to model the task sequence from both use cases in the same sequence diagram. However, for simplicity, we'll keep each use case in its own sequence diagram in this example.

End Sidebar

In the Maintain Time Entries sequence diagram, the user can maintain his or her personal time entries. To allow this, the form needs to be loaded with the time entries, so you need to add a Get Time Entries message. This message should point from the Time Sheet Form object to the Time Sheet object, because the Time Sheet object delivers the information to the Time Sheet Form object.

In Exercise 16-19, you'll add the Get Time Entries message to the Maintain Time Entries sequence diagram and also add sequence numbering to clarify the diagram.

Exercise 16-19
Start example

  1. In the Maintain Time Entries sequence diagram, add an object lifeline named Time Sheet to the diagram, and set the classifier to the TimeSheet class.

  2. Add an activation to the Time Sheet object.

  3. Create a new message named Get Time Entries between the activations on the Time Sheet Form and Time Sheet objects. Create and select a new operation named GetTimeEntries for the message.

  4. Add a parameter named employeeID to the GetTimeEntries operation of data type string (VB).

  5. Create a new message named Add between the activations on the Employee and Time Sheet objects. Select the operation with the same name for the message.

  6. Add a return message named Time Entries to the activations on the Time Sheet and Time Sheet Form objects.

  7. Add sequence numbering to the messages (specified in the Sequence Expression text field of the UML Message Properties dialog box, which opens when you double-click a message), Use the format 1.x (where x is a sequentially increasing number), starting with 1.1 and incrementing by 0.1: 1.2, 1.3, and so on. Add the sequence numbering in this order: Open, Select Maintain Time Entries, Get Time Entries, and Add.

Your sequence diagram should now look like the one shown in Figure 16-31.

Click To expand
Figure 16-31: Sequence diagram for the Maintain Time Entries use case

End example

Approve and Validate Time Entries (Sequence Diagram)

The next and final sequence diagram in this hands-on example is for the Approve and Validate Time Entries use case. Figure 16-32 shows the complete sequence diagram for the use case.

Click To expand
Figure 16-32: Complete sequence diagram for the Approve and Validate Time Entries use case

Here is an explanation of each sequence step:

  • The administrator opens the start page. This can be a form containing the menu navigation.

  • The administrator selects Approve Time Entries. If the logged-on user isn't an administrator, this option isn't available.

  • The time sheet form must provide the administrator with the choice of which employee's time entries to see. To do that, the form needs to get a list of employees.

  • The time sheet loads and displays the time entries for the selected employee.

  • The administrator sets the status on the time sheet form. The administrator can set the status to two different values: Approved or Disapproved.

  • The Save button saves the settings.

  • A notification regarding any disapproved time entries is sent to the employee.

In Exercise 16-20, you'll create the Approve and Validate Time Entries sequence diagram.

Exercise 16-20
Start example

  1. In the UML model from Exercise 16-19, create a new sequence diagram named Approve and Validate Time Entries. (Well, because of the object name length limit, you can enter only Approve and Validate Time Entri.)

  2. Add an object lifeline named Administrator to the diagram, and set the classifier to the Administrator actor.

  3. Add an object lifeline named Start Page to the diagram, and set the classifier to the StartPage class.

  4. Add an object lifeline named CEmployee to the diagram, and set the classifier to a new CEmployee class. We use the C prefix for the Employee object and class because of the existing Employee actor. You can't have objects with the same name within the same namespace.

  5. Add an object lifeline named Time Sheet Form to the diagram, and set the classifier to the TimeSheetForm class.

  6. Add an object lifeline named Time Sheet to the diagram, and set the classifier to the TimeSheet class.

  7. Add an object lifeline named Employee to the diagram, and set the classifier to the Employee actor.

  8. Add activations to the Administrator, Start Page, Time Sheet Form, CEmployee, Time Sheet, and Employee objects. Add an extra activation to the Time Sheet Form object.

  9. Create a new message named Open between the activations on the Administrator and Start Page objects. Select the operation with the same name for the message, and give the message sequence number 1.1.

  10. Create a new message named Select Approve Time Entries between the activation on the Start Page object and the first activation on the Time Sheet Form object. Create and select a new operation with the same name as the message, and give the message sequence number 1.2.

  11. Create a new message named GetList between the activations on the Time Sheet Form and CEmployee objects. Create and select a new operation with the same name as the message, and give the message sequence number 1.3.

  12. Create a new return message named Employee List between the activations on the CEmployee and Time Sheet Form objects.

  13. Create a new message named Get Time Entries between the activations on the Time Sheet Form and Time Sheet objects. Select the GetTimeEntries operation for the message, and give the message sequence number 1.4.

  14. Create a new return message named Time Entries between the activations on the Time Sheet and Time Sheet Form objects.

  15. Create a new message named Set Status between the activation on the Administrator object and last activation on the Time Sheet Form object. Create and select a new operation named SetStatus for the message, and give the message sequence number 1.5.

  16. Create a new message named Save Status between the last activation on the Time Sheet Form object and activation on the Time Sheet object. Create and select a new operation named SaveStatus for the message, and give the message sequence number 1.6.

  17. Create a new message named Send Notification between the activations on the Time Sheet Form and Time Sheet objects. Create and select a new operation named SendNotification for the message, and give the message sequence number 1.7.

Your sequence diagram should now look like the one shown in Figure 16-32.

End example

Getting User and Developer Acceptance

The Approve and Validate Time Entries sequence diagram is a bit more compli cated than the previous two. You can also see that the sequence diagram adds some functionality necessary for the solution that isn't available in the use case description. For example, the sequence diagram asks for a list of employees (sequence number 1.3) and receives a list of employees. This is exactly what sequence diagramming is all about.

You model the sequence diagram so that you can get acceptance from both the users and the developers that this is how the solution should be. It's much cheaper to change the functionality or the way the solution will be built at this stage, before any code is created.

Keep in mind that the sequence diagrams and use case diagrams are not set in concrete (yet). They might change or be refined as you get more detailed infor mation and knowledge about the solution you're about to develop.


Building the Class Diagrams

The class diagram is important because it tells the developers what and how to develop. The developers are the primary drivers when creating a class diagram. The users are rarely involved, because they've already accepted the functionality described in the use case and sequence diagrams.

As noted earlier in this chapter, in VEA, class diagrams are called static structure diagrams, because you can create diagrams other than class diagrams using the same elements. For example, you can create an object diagram or a database diagram. This is not a Visio-ism, but true UML. This means that you can model things other than physical classes in your diagram. For example, you can also model your Windows forms or your ASP.NET Web pages in your diagram. A Windows form or an ASP.NET page (Web form) are also classes, so you can model these as classes with the form and ASP.NET stereotypes, respectively.[4] "Normal" classes will be created as .cs (C#), or .vb (VB .NET) files in your VS .NET solution.

In building class diagrams for your .NET solutions, you will want to model .NET Framework data types. However, VEA has knowledge only of the programming language-specific data types for C#, C++, IDL,[5] and VB. This means that none of the .NET Framework-specific data types, such as DataSet and Guid, are readily available. To model the .NET Framework data types, you'll need to create new data types in VEA. Before we start creating our class diagram, we'll first look at how to create new data types.

Creating New Data Types

You create a new data types in a package/folder in the Model Explorer. Right-click the package in the Model Explorer in which you want to create the data type, and then select New ® Datatype from the pop-up menu. This brings up the UML Datatype Properties dialog box, as shown in Figure 16-33. Name your data type by specifying a name in the Name text field.

Click To expand
Figure 16-33: UML Datatype Properties dialog box

If you want to reference one or more of the .NET Framework data types, and so need to create them in your UML model, you can do this in two ways, as described in the following sections.

Using the VB Data Types Package

In our case, we use VB as the programming language, so you can use the VB Data Types folder as the package for your data types. If this folder isn't shown in the Model Explorer, you can show it by opening the UML Options dialog box (select UML ® Options) and selecting the UML Document tab.

If you use one of the existing data type packages, such as the VB Data Types one, an error message similar to this will be displayed in the Code pane of the Output window:

Code will not be generated for data types and interfaces specified in predefined packages.

This isn't as bad as it looks, because the code will be generated. Say you define the DataSet data type and assign it to one or more attributes or operation parameters in a class. Although the error message is displayed, the attributes and operation parameters will be generated with the requested data type. So, if you have the addedTimeEntries parameter of the Save operation of the TimeSheet class (see Exercise 16-22 later in this chapter), and specify that the data type should be VB::DataSet, the generated line of code will look like this: ByVal addedTimeEntries As DataSet This is okay, if you make sure that your project references and the class imports/uses the System.Data namespace, which is the default for most of the built-in project types. Alternatively, you can give the data type the full name, including the namespace in which it's located, such as System.Data.DataSet. If you do it like that, the generated line of code will look like this:

ByVal addedTimeEntries As System.Data.DataSet

This way, you just need to make sure that your project references the System.Data namespace.

However, if you want to get rid of the error message when generating the code, there's another way to be able to reference the data types.

Creating Your Own Package

You can create your own package in the UML subsystem, which is usually named UML System 1. This is done by right-clicking the subsystem in the Model Explorer and selecting Packages from the pop-up menu. Then you simply add a new package to the list of packages in the UML Packages dialog box. When you click OK in the UML Packages dialog box, any package you created will appear in the Model Explorer, and you can add your data types to this package.

Note

Any packages and/or data types created in your UML model are model-specific, meaning they will not be loaded with any new UML model.

When you refer to the data type when declaring an attribute or parameter, you need to remember that it's prefixed with the name of the package followed by two colons. For example, if you name your package System.Data and you name your data type DataSet, you need to select System.Data::DataSet when referring to the new data type.

When you create .NET Framework data types in your UML model, it's a good idea to use the namespaces as package names for the data types. This way, you know which namespaces to reference in your project and which namespaces to import/use in your classes.

Modeling Classes

Now, you'll build the class diagram based on the sequence diagrams you made in the previous Exercises. When modeling class diagrams, you should generally keep all of the classes in a package, or namespace as it will be once the code is generated. If you have only a few classes in different namespaces, you might also want to model them all in a single class diagram.

We believe that you should not have more than one class diagram, unless a single class diagram would be too complex to read. In our example, it makes little difference, because we've used the same classes—StartPage, TimeSheet, TimeSheetForm, and so on—in all of the sequence diagrams. This means that we can't split the class diagrams into separate diagrams, one for each use case diagram, as we did with the sequence diagrams.

Having said that, we have tried to divide the class diagram information into the same type of sections as we did with the use case and sequence diagrams. However, as you'll see from the following sections, it's merely a matter of how we look at the corresponding sequence diagrams. Keep in mind that until we finish modeling the final class, based on the last sequence diagram, some of the figures in the coming sections might show operations that are "ahead" of the describing text.

Note

If you have functionality in a class that is enabled or disabled based on the role of the logged on user, you need role checks in your code. This way, an employee can't invoke functionality that is for administrators only, such as Approve Time Entries. There is no direct way of modeling this, but it can be added as documentation text to a class. You can add the documentation on the class level, or as documentation to the individual attributes or operations. See the "Time Sheet Project Questions and Answers" section later in this chapter for more information.

Register Hours (Class Diagram)

In the Register Hours sequence diagram (see Figure 16-28), the objects are candidate objects in your solution. We still call them objects, because some will be classes, some will be forms, and so on. So, from the sequence diagram you have the following objects:

  • Start Page

  • Time Sheet Form

  • Time Sheet

We created these objects as classes while creating the sequence diagram and used them as classifiers for the object lifelines. We also created the operations as messages while creating the sequence diagrams, and these are often methods in your class diagram. As a rule of thumb, all sequence messages becomes methods of classes. However, you might refine the number of messages, and even delete some messages and objects.

When modeling your class diagram, you should start with the most important class, and then model the other classes. We think the TimeSheet class is the most important one, so we model that one first, followed by the TimeSheetForm class. Figure 16-34 shows the class diagram after modeling these two classes. We've created a form stereotype for the TimeSheetForm class and connected the TimeSheetForm and TimeSheet classes.

Figure 16-34: Register Hours class diagram with the most important classes

In Exercise 16-21, you'll start the Register Hours class diagram.

Exercise 16-21
Start example

  1. Open the UML model from Exercise 16-20, if it's not already open.

  2. Create a new static structure diagram.

  3. Drag the TimeSheet and TimeSheetForm classes from the Model Explorer onto the static structure diagram.

  4. Create a new stereotype named form of base class Class, and assign it to the TimeSheetForm class.

  5. Create a binary association between the TimeSheet and TimeSheetForm classes; don't display the end names. Set the multiplicity to 0..* for the TimeSheet class and 0..1 for the TimeSheetForm class.

Your static structure diagram should now look like the one shown in Figure 16-34.

End example

While creating the class diagram, keep asking yourself the question, "What additional information do the developers need in order to develop the code cor responding to the class diagram?" In our case, the developers might ask for the following information (keep in mind we are focusing on the content of Register Hours sequence diagram for now):

Question: Is the TimeSheetForm class/form placed on a parent form like an ASP.NET page or Windows form (custom control?), or is it a stand- alone form?

Answer: The TimeSheetForm class is a stand-alone form in the system; that is, it has no parent form.

Question: What kind of operation is the Select Add Time Entries operation of the TimeSheetForm class/form?

Answer: It's simply a button, menu item, or hyperlink on the form.

Question: Which parameter(s) do the Select Add Time Entries, Select Maintain Time Entries, and Select Approve Time Entries operations take?

Answer: None.

Question: What kind of operation is the Add operation on the

TimeSheet class?

Answer: Adding time entries happens on a data-bound grid on the form; the TimeSheet class only needs to save the time entries entered on the form. So, it's not really an operation, meaning it invokes built-in functionality of the grid component to be used.

Question: Which parameter(s) does the Add operation take?

Answer: None.

Question: What kind of operation is the Save operation of the TimeSheet class?

Answer: The Save operation saves the time entries entered in the grid on the form.

Question: Which parameter(s) does the Save operation take?

Answer: It takes the container of the data-bound grid as input, which could be a relational DataSet object. The DataSet contains any number of entries, each with the following information: Employee ID, Task ID, Centihours, Description, and Date.

Question: Where are time entries in the TimeSheet class stored? Are they stored in a database table?

Answer: Yes, they're saved in the database.

Question: Why isn't a time entry saved when adding it to the TimeSheet class? Why do you need the Save operation?

Answer: Adding time entries happens on the form. The added entries should not be saved until the Save operation is called.

The developers need answers to all of these questions, and probably more, in order to be able to write the code. The answers basically come from within the project team, but in some cases, it's necessary to ask the users some additional questions. In UML, you don't answer the questions in writing; instead, the answers are modeled on the diagram.

Note

After reading the answers, especially the storage-related one, you might wonder how to model the database structure. Before continuing with the class diagram you might benefit from reading the "Modeling the Database" section at the end of this chapter, which describes how the database structure (data model) is modeled the UML way and what alternatives you have.

From the new information, you can see that a DataSet object is used for saving the added time entries. Figure 16-35 shows the modified class diagram, where the Save operation of the TimeSheet class now takes a second parameter, addedTimeEntries.

Figure 16-35: Save operation of the TimeSheet class with a second parameter

You now have the input for the Save operation, but you can model more than that. You can also show database classes on your class diagram, as shown in Figure 16-36.

Click To expand
Figure 16-36: Class diagram with a database table and relation

In Exercise 16-22, you'll refine your class diagram to reflect the new information.

Exercise 16-22
Start example

  1. In the UML model from Exercise 16-21, create two new packages named System and System.Data in the UML subsystem.

  2. Create a new data type named Guid in the System package. (See the "Creating New Data Types" section earlier in this chapter.)

  3. Create a new data type named DataSet in the System.Data package.

  4. Add a second parameter named addedTimeEntries of data type DataSet to the Save operation of the TimeSheet class.

  5. Add a new class named TimeEntries to the diagram.

  6. Create a new stereotype named table of base class Class, and assign it to the TimeEntries class.

  7. Add the following attributes to the TimeEntries class (the VB data type is shown in parentheses):

    ID (Guid)

    EmployeeID (Guid)

    TaskID (Guid)

    Hours (Integer)

    Description (String)

    EntryDate (Date)

    Status (Integer)

  8. Create a binary association between the TimeSheet and TimeEntries classes; don't display the end names. Set the multiplicity to 0..* for both ends.

Your static structure diagram should now look like the one shown in Figure 16-36.

End example

Here, you can see how the answers given to the questions asked earlier in this section have influenced the class diagram in its current state:

  • TimeSheetForm is a stand-alone form. If TimeSheetForm is placed on a parent form like an ASP.NET Web page, the diagram could look like Figure 16-37.

    Click To expand
    Figure 16-37: Class diagram with TimeSheetForm placed on an ASP.NET page

  • The Select Add Time Entries operation is simply a command button. This is not modeled at this stage.

  • The Add operation isn't an operation; it's just illustrating that the employee performs this manual action. So, the Add operation isn't created.

  • The Save operation saves the date entered in the form to the TimeEntries database table.

  • The Save operation takes the DataSet from the grid as input. The DataSet contains EmployeeID, TaskID, Hours, Description, and EntryDate. The value of the Status column of each time entry saved is automatically set to 0, which means not reviewed.

You can generate code for the class diagram in Figure 16-36 (Exercise 16-22) by selecting UML®Code ® Generate. This opens the Generate dialog box, in which you can select the classes for which to generate the skeleton code, as shown in Figure 16-38.

Click To expand
Figure 16-38: Generate dialog box

As you can see from Figure 16-38, we've selected all of the classes in the Top Package package for code generation, but none of those in the System or System.Data packages. Why is that? Well, the classes in the System and System.Data packages are our .NET Framework data types, and we're just faking these in order to avoid errors during code generation. In other words, these data types already exist in the .NET Framework, so we only need to reference the appropriate namespaces (System and System.Data) in our project, and not generate the skeleton code for the data types or classes as they really are.

In Figure 16-39, you can see the generated code for the TimeSheet class, after clicking OK in the Generate dialog box.

Click To expand
Figure 16-39: Code generated for the TimeSheet class

Maintain Time Entries (Class Diagram)

The next sequence diagram to model in our class diagram is Maintain Time Entries. Well, it's nearly done, because of the way we created the sequence diagrams, but you can refer back to the sequence diagram (Figure 16-31).

In Figure 16-36, shown earlier in this chapter, the class diagram shows you need to get a list of all the time entries for a specific user (employee) in order to maintain these (edit, delete, and update). To do this list, you have the GetTimeEntries operation/method on the TimeSheet class returning a list of time entries for a specific employee. The Save operation/method, which is also used by the Register Hours use case, updates the database.

Approve and Validate Time Entries (Class Diagram)

The final sequence diagram to model in our class diagram is Approve and Val idate Time Entries. You can see the sequence diagram in Figure 16-32 shown earlier in this chapter. The class diagram in Figure 16-36 is modified so it looks like Figure 16-40.

Click To expand
Figure 16-40: Class diagram with the CEmployee class

The sequence diagram information in Figure 16-32 is mapped to the class diagram in Figure 16-40 as follows:

  • According to the sequence diagram, you need to get a list of all employees in order to select which time entries you want to approve and validate. This suggests that you need an Employee class (named CEmployee, because there is already an Employee object, an actor, in the UML model) with the GetList method, which returns a list of all employees.

  • You need to save the status for time entry. You can't use the existing Save method, because you need to update the status field only, and then you need to send an email notification when status is set to disapproved. This is the SaveStatus method.

  • The SaveStatus method sends the notifications, but it does that using the SendNotification method.

In Exercise 16-23, you'll complete the class model.

Exercise 16-23
Start example

  1. In the UML model from Exercise 16-22, add the CEmployee class to the static structure diagram.

  2. Change the GetList operation of the CEmployee class to return a variable of data type DataSet.

  3. Change the SaveStatus operation of the TimeSheet class to accept an input parameter named reviewedTimeEntries of data type DataSet.

  4. Change the GetTimeEntries operation of the TimeSheet class to accept an input parameter named reviewedTimeEntries of data type DataSet.

  5. Add an operation named SendNotification to the TimeSheet. Add the following input parameters to the operation (VB data type in parentheses): emailTo (String), emailFrom (String), and message (String).

  6. Create a binary association between the TimeSheetForm and CEmployee classes; don't display the end names or multiplicity.

Your static structure diagram should now look like the one shown in Figure 16-40.

End example

You can now generate code for the TimeSheet and CEmployee classes. Figure 16-41 shows the code generated for the TimeSheet class, after performing Exercise 16-23.

Click To expand
Figure 16-41: Generated code for the TimeSheet class

The code generated for the CEmployee class is shown in Figure 16-42.

Click To expand
Figure 16-42: Generated code for the CEmployee class

The next step is for the developers to start developing the solution. It's important that the UML model is updated when you choose to develop things differently than modeled, which nearly always happens. Additionally, you need to update the UML model when you get additional knowledge about how the functionality will be implemented. For example, in the final class diagram, you've added return types and parameters to the classes. You can now apply these to the sequence diagram as well.

This completes our UML modeling for the time sheet project in this chapter. Are you wondering about some aspects of this example? In the next section, we'll address some questions you might have about the modeling.

[4]If you want to go with strict OOP terminology, you can model your forms as interfaces.

[5]IDL is short for Interface Definition Language, and it can be used instead of a specific programming language. This is useful if you're uncertain of which programming language you'll use eventually.


Time Sheet Project Questions and Answers

Some of the details of the example may need clarification. In this section, we've provided this clarification in question-and-answer format.

Question: How do the developers know that only the administrator can select Approve Time Entries from the menu or main form?

Answer: The developers must look at the sequence diagrams to know that. It's a good idea to write this information in the Documentation text box of the sequence diagram message and the class diagram methods.

Question: On the Approve and Validate Time Entries sequence diagram (Figure 16-32), the Send Notification message points toward the Employee actor. Shouldn't there be a method on the actor then?

Answer: Well, at the time the sequence diagram was created, it was correct, because the flow was toward the actor. A better and more correct way to draw this is shown in Figure 16-43, where the TimeSheet object calls the SendNotification operation on itself, and the Employee actor just receives the e-mail.

Click To expand
Figure 16-43: Approve and Validate Time Entries sequence diagram with new notification modeling

Question: Wasn't the SendNotification operation supposed to use an existing COM component?

Answer: Yes, that was the intention. To model this, use this procedure:

  1. Draw the ITREmail class representing the ITREmail component on the class diagram and delete the SendNotification operation from the TimeSheet class, as shown in Figure 16-44.[6]

    Click To expand
    Figure 16-44: Class diagram showing how to use the ITREmail class

  2. Create an ITReadyMessage component with the COM stereotype on a component diagram, as shown in Figure 16-45.

    Figure 16-45: Component diagram with the ITReadyMessage COM component

  3. Specify that the ITREmail class is implemented in the ITReadyMessage component, as shown in Figure 16-46. Double-click the ITReadyMessage component to open the UML Component Properties dialog box.

    Click To expand
    Figure 16-46: UML Component Properties dialog box

  4. You can add a description to the SaveStatus operation that indicates it needs to send out an e-mail message using the ITREmail class.

[6]You could argue that the ITREmail COM component should be modeled as an object on the diagram shown in Figure 16-44, but we feel the COM component is an integrated part, and thus consider it as a kind of method.


Modeling the Database

This section describes several ways to model the database for your solution. We'll cover the UML approach to database modeling, the Visio approach, and other alternatives.

Modeling the Database the UML Way

In UML database modeling is fairly simple. Table 16-2 shows how to model the database elements in UML.

Table 16-2: Database Element UML Mapping
Database Element | UML
Database diagram | Class diagram
Table | Class (with stereotype <<table>>)
Field | Attribute
Constraint | Operation
Keys | Constraint->Operation
Schema | Package
Entire database | Component (or package)
Relation | Relation

Figure 16-47 illustrates how the data model for the ITReady solution could look modeled in UML.

Click To expand
Figure 16-47: Data model for the ITReady solution modeled in UML

A huge advantage of modeling your database using UML is that you'll have all your modeling (use case diagrams, class diagrams, deployment diagrams, database diagrams, and so on) in the same model. This provides the best overview for your solution. You're also able to relate all the different elements to each other; for example, relate a class or component to a table. Additionally, you'll have the usual UML advantages such as being independent of language, understood by the majority of developers, and so on.

Unfortunately, Visio currently can't reverse-engineer or forward-engineer databases to and from UML.

Modeling the Database the Visio Way

This might seem odd, but the Visio tool suggests that you model databases using the database model diagram, rather than UML. This is because Visio isn't a UML tool; Visio is a modeling tool that now supports UML. The database model diagram is a template just like the UML model diagram is a template. To create a database model diagram, select File® New® Database ® Database Model Diagram.

Modeling databases with the database model diagram template provides you with all relational database modeling facilities. In Figure 16-48, you can see the ITReady solution data model modeled with the database model diagram template.

Click To expand
Figure 16-48: Data model for the ITReady solution modeled using the database model diagram template

Using the database model diagram, you can reverse-engineer and forward- engineer the database model to and from any database for which an ODBC driver is installed, including Microsoft SQL Server. You can even let the Generate Wizard generate the physical database for you and generate a SQL script. We cover how to do this in Exercise 1-15 of Chapter 1.

The advantage of using the database model diagram is that you can forward- engineer and reverse-engineer your model. Unfortunately, it's not UML, but you can copy your database model diagram to a UML model. However, that will make it read-only, and reverse and forward engineering will not be possible.

Using Database Modeling Alternatives

One alternative to using UML for your database modeling is to model your database in another database modeling tool. However, we don't think modeling the database model in another modeling tool is a good idea, because you then have one more tool to learn and synchronization between the tools is often dif ficult (if not impossible).

Another alternative is to model the database directly in the database. For example, you could create a database diagram in SQL Server, or even better, in the Visual Database Tools integrated into the VS .NET IDE in the Professional and Enterprise editions. However, it's easier to ensure consistent naming of data if you use Visio for UML and database modeling, because you have the one tool. Also, you can use any database supported by Visio,[7] not just SQL Server.

[7]Visio uses ODBC drivers, so any database that has an ODBC driver can be modeled and generated directly from Visio.


Summary

In this chapter, you've learned how to develop a UML model, beginning from system requirements modeling through use case diagrams, sequence diagrams, and the class diagram.

You've also seen various drawing techniques:

  • Forms can be modeled as classes or interfaces.

  • Tables can be modeled as classes.

  • COM components can be modeled as components with classes.

  • Access limitations to methods can be documented in plain text.

  • Database models can be modeled as class diagram or by using the Visio database model diagram template.

The purpose of this chapter was to give you an overview of how to start modeling and to use the techniques you've learned. The focus was on the process and the drawing techniques. In the next chapter, we'll focus on the technical part of modeling and discuss how to model code specifics.


Chapter 17: Hands On: An External Project

Overview

The hands-on example in this chapter will be built from scratch, without using existing components from the customer's enterprise. This is contrast to the example in Chapter 16, which did integrate existing components from the customer's enterprise.

In Chapter 16, the focus was mainly on the process and how to technically model the requirements and architecture. In this chapter, the focus is on the physical architecture, meaning we'll concentrate on how to model the final architecture and generate the code. We'll select one use case and go into detail about it, instead of viewing all the use cases from a high-level perspective. The model (selected diagram) will be refined, so it can act as documentation as well.


About Coffee Inc.: The Background Story

Coffee Inc., a holding company, produces high-quality accessories for the coffee table (mugs, pots, and so on). The managing directors want an IT solution that can service its sales companies in various countries.

In the current situation, the sales companies suffer from late information regarding product specifications and other information. Another problem is that the sales companies occasionally need to get inventory information and pictures for marketing purposes, and this is a very time-consuming process. The information in this section will be your problem statement in the vision scope document (see Chapter 20 for details).

Your job is to design a solution that achieves the following:

  • Enables each sales company to quickly access information about product specifications and inventory information.

  • Enables each sales company to upload and download pictures for marketing purposes from a picture database.

  • Makes it possible for the holding company to control access to the system. All sales companies may see everything in the system, but they can update only the content of the picture database. Other users, such as customers, can see only the product specifications.


Gathering the Requirements

The first step is to gather all the requirements. Based on the information in the previous section, you can create a high-level use case diagram. Because this is a learn-by-doing chapter, we'll kick off with Exercises right from the start. So, dive into Exercise 17-1 to create the use case diagrams needed to model the requirements.

Exercise 17-1
Start example

  1. Open VEA and create a new UML model diagram.

  2. Drag three actors onto the blank diagram, and name them Sales Company, Product Database, and Picture Database.

  3. Drag five use cases onto the diagram. Name them as follows: Logon (for the holding company to control access to the system), View Product Specifications (for all system users, including customers), View Inventory (for the holding company and the sales companies), Upload Picture (for the holding company and the sales companies), and Download Picture (for the holding company and the sales companies).

  4. Add communicates relationships between the Sales Company actor and the five use cases. Don't display the end names or end multiplicity.

  5. Add communicates relationships between the Product Database actor and the View Product Specifications and View Inventory use cases. Don't display the end names or end multiplicity, but do display the navigability towards the use cases.

  6. Add a communicates relationship between the Picture Database actor and the Upload Picture use case. Don't display the end names or end multiplicity, but do display the navigability towards the actor.

  7. Add a communicates relationship between the Picture Database actor and the Download Picture use case. Don't display the end names or end multiplicity, but do display the navigability towards the use case.

Your use case diagram should look like the one shown in Figure 17-1.

Click To expand
Figure 17-1: High-level use case diagram for the Sales Company, Product Database, and Picture Database actors

Now, you will create another diagram for the user administrator and user roles.

  1. Create a new use case diagram.

  2. Drag two actors onto the blank diagram, and name them User and Administrator.

  3. Drag the existing Product Database actor onto the diagram.

  4. Drag the existing View Product Specifications use case, and add a new use case named Maintain Users onto the diagram. Notice how the communicates relationship is automatically added between the View Product Specifications use case and the Product Database actor. This is because you modeled this in the other diagram.

  5. Add a communicates relationship between the User actor and the View Product Specifications use case.

  6. Add a communicates relationship between the Administrator actor and the Maintain Users use case.

  7. Remove the end names and end multiplicities from all of the associations.

Your use case diagram should look like the one shown in Figure 17-2.

Click To expand
Figure 17-2: High-level use case diagram for the User, Administrator, and Product Database actors

End example

The two use case diagrams created in Exercise 17-1 don't hold many surprises. You've added the external actors Product Database and Picture Database to indicate that the information isn't incorporated in the system, but the system interacts with the external systems (databases). For the relationships between the external actors and the use cases, you've specified the navigation direction, to indicate if the external actor delivers or receives information. This is what you need to move on to creating the sequence diagrams, as described in the next section.


Creating the Sequence Diagram

Now that you've gathered the requirements and modeled the use cases, it's time to create the sequence diagrams. In this example, you're creating only one sequence diagram—the one for the most important use case. Since we're focusing on the project seen from the architecture perspective in this chapter, the Upload Picture use case is the most important one.

Starting the Sequence Diagram

The Upload Picture sequence diagram is particularly interesting because it uses a third-party component for picture uploading and resizing. It will also require you to model collections, implement polymorphism, and so on. Exercise 17-2 shows you how to model this sequence diagram.

Note

We're producing VB .NET code in this chapter, but feel free to substitute with C# if you prefer to use that language.
Exercise 17-2
Start example

  1. Open the UML model you created in Exercise 17-1.

  2. Create a new sequence diagram named Upload Picture.

  3. Drag an object lifeline named Sales Company onto the blank diagram. Set the Sales Company actor as the classifier.

  4. Drag an object lifeline named Upload Form onto the diagram. Set the classifier to a new class named UploadForm with the Form stereotype.

  5. Drag an object lifeline named Upload onto the diagram. Set the classifier to a new class named Upload.

  6. Add two Activation shapes to the Upload Form lifeline and one to the Upload lifeline.

  7. Add a message named Open between the Sales Company lifeline and the first activation on the Upload Form lifeline. This message has sequence 1.1, which should be shown on the diagram. The message invokes the Open operation on the UploadForm class.

  8. Add a monogamous message named LocateFile to the first activation on the Upload Form lifeline. This message has sequence 1.2, and it invokes a new operation named LocateFile on the UploadForm class.

  9. Add a monogamous message named SetPictureType to the first activation on the Upload Form lifeline. This message has sequence 1.3. The message invokes a new operation named SetPictureType.

  10. Add a monogamous message named SetProduct to the first activation on the Upload Form lifeline. This message has sequence 1.4. The message invokes a new operation named SetProduct.

  11. Add a message named Upload between the first activation on the Upload Form lifeline and the activation on the Upload lifeline. This message has sequence 1.5. The message invokes a new operation named Upload on the Upload class, and the operation takes one parameter named filePath of data type string.

    Note

    If you're using C#, you cannot have a method of the same name as the class in which it's declared, because this is reserved for the constructor and finalizer methods. In step 11, you'll need to use another name, such as UploadFile.

  12. Add a monogamous message named ResizePicture to the activation on the Upload lifeline. This message has sequence 1.6. The message invokes a new operation named ResizePicture.

  13. Add a message named Save between the Sales Company actor and the second activation on the Upload Form lifeline. This message has sequence 2.1. The message invokes a new operation named Save on the UploadForm class.

Your sequence diagram should look like the one shown in Figure 17-3.

Click To expand
Figure 17-3: Upload Picture sequence diagram

End example

The sequence diagram is created as seen from the user's perspective. Here is an explanation of the sequence expressions from the sequence diagram:

1.1 | The user (sales company) opens the Upload Picture form.
1.2 | The user browses for the file to be uploaded.
1.3 | The user selects a picture type (Product picture, Add picture, or Store picture).
1.4 | The picture is related to a specific product.
1.5 | The file is uploaded.
1.6 | The picture is resized to a specific width.

2.1

The picture information is saved in the system.

You can use the sequence diagram to create the class diagram, as you learned in Chapter 16. However, sometimes it can be difficult to get an overview of the classes needed and the database structure just by looking at the sequence diagram.

Making the Sequence Diagram More Physical

If you think you need more detailed information in order to create the class diagram, you can make the sequence diagram more physical. Basically, you incorporate parameters, data types, and so on into your sequence diagram, as shown in Figure 17-4.

Click To expand
Figure 17-4: Upload Picture sequence diagram made more physical
Note

Is making a sequence diagram more physical okay according to the UML standard? Well, there are arguments for and against doing this. We think you should make your sequence diagrams more physical if it helps you in your design phase. Just remember that you should not be technical. In other words, it's alright to specify that you need information from a specific table, but it's not okay to specify that the table must exist in a SQL Server or an Oracle database.

In Exercise 17-3, you'll make the Upload Picture sequence diagram more physical, so it will be easier for you and the developers to identify the classes and the database structure.

Exercise 17-3
Start example

  1. In the UML model from Exercise 17-2, create a new sequence diagram named Upload Picture (Physical).

  2. Copy the entire content of the Upload Picture sequence diagram created in Exercise 17-2 across to the blank diagram.

  3. Drag an object lifeline named PictureTypes onto the diagram and place it between the Upload Form and Upload lifelines. Set the classifier to a new class named PictureTypes. The class should be of stereotype Table.

  4. Drag an object lifeline named Products onto the diagram and place it between the PictureTypes and Upload lifelines. Set the classifier to a new class named Products. The class should be of stereotype Table.

  5. Drag an object lifeline named Pictures onto the diagram and place it to the right of Upload lifeline. Set the classifier to a new class named Pictures. The class should be of stereotype Table.

  6. Change the sequence expression from 1.3 to 1.4 for the SetPictureType return message.

  7. Add an Activation shape to the PictureTypes lifeline.

  8. Add a message named GetList between the first activation on the Upload Form lifeline and the activation on the PictureTypes lifeline. This message has sequence 1.3. The message invokes the GetList operation on the PictureTypes class.

  9. Add a return message named Picture Types List between the activation on the PictureTypes lifeline and the first activation on the Upload Form lifeline.

  10. Add an Activation shape to the Products lifeline.

  11. Change the sequence expression from 1.4 to 1.6 for the SetProduct return message.

  12. Add a message named GetList between the first activation on the Upload Form lifeline and the activation on the Products lifeline. This message has sequence 1.5. The message invokes the GetList operation on the Products class.

  13. Add a return message named Products List between the activation on the Products lifeline and the first activation on the Upload Form lifeline.

  14. Change the sequence expression from 1.5 to 1.7 for the Upload message between the activations on the Upload Form and Upload lifelines.

  15. Change the sequence expression from 1.6 to 1.8 for the ResizePicture return message.

  16. Add an Activation shape to the Pictures lifeline.

  17. Add a message named SavePicture between the second activation on the Upload Form lifeline and the activation on the Pictures lifeline. This message has sequence 2.2. The message invokes the SavePicture operation on the Pictures class.

Your diagram should now look like the one shown in Figure 17-4.

End example

The physical sequence diagram in Figure 17-4 is different from the ordinary sequence diagram in Figure 17-3. The sequence expressions have changed.

Here's an explanation of the sequence diagram in Figure 17-4:

1.1 | The (sales company) user opens the Upload Picture form.
1.2 | The user browses for the file to be uploaded.
1.3 | In order to select a picture type (in step 1.4), the system needs to get a list of all possible picture types and present this list for the user. To do this, the GetList method gets a list of picture types from the PictureTypes table.
1.4 | The user selects a picture type (Product picture, Add picture, or Store picture).
1.5 | In order to select a product and relate it to the picture (in step 1.6), the system needs to get a list of all possible products and present this list to the user. To do this, the GetList method gets a list of products from the Products table.
1.6 | The picture is related to a specific product (the product is selected from a list, which is fetched from the database in step 1.7).
1.7 | The file is uploaded.
1.8 | The picture is resized to a specific width.
2.1 | The picture information is saved in the system.
2.2 | The actual picture information is saved in the Pictures table.

Now, you have two versions of the sequence diagram. You can discuss one version (Figure 17-3) with the customer and users, without confusing them with the tables and parameters. The other version (Figure 17-4) is for you to discuss internally in your project team.

It's useful to discuss the sequence diagram from a technical perspective (Figure 17-4) before building the code, because it's more time-consuming to correct code than to correct the model. It's also beneficial to view the sequence diagram from a technical perspective, even before you build the corresponding class diagram, because you can discuss the overall design concept before spending time on creating the class diagram. For example, based on the sequence diagram in Figure 17-4, you and your project team can discuss whether the interaction with the database should be as suggested in the diagram and if the correspon dence is correct.

A disadvantage of having two sequence diagrams is that you need to keep both of them up-to-date!


Creating the Class Diagram

Now, you're ready to convert the sequence diagram into a class diagram. We'll keep the class diagram as a true class diagram and show the database structure in a separate diagram. The reason is that the database tables are not really a part of this solution; this solution merely interacts with the databases, which are (external) actors to this solution.

Starting the Class Diagram

Once you have a sequence diagram that covers the sequence of tasks to be carried out on the various objects, you can create the corresponding class diagram. The first-cut class diagram might look like Figure 17-5.

Click To expand
Figure 17-5: Incomplete Upload Picture class diagram

In Exercise 17-4, you'll start building the Upload Picture class diagram. We'll use new models for this Exercise to avoid having classes and actors with the same names.

Note

Although it is possible to have UML elements such as classes and actors with the same name but in different models, this is not possible for diagrams.
Exercise 17-4
Start example

  1. Create a new UML model named Class in the same Visio document as the one you used for the UML model in Exercise 17-3. To create a new model, right-click the top node of the Model Explorer (which is usually named UML System 1), select Models from the pop-up menu, and click New in the UML Models dialog box.

  2. Rename the existing model (Static Model) to Use Case and Sequence.

  3. Rename the Top Package package in the two models to CoffeeInc (the customer name). Remember that this package will also be the namespace used when generating your .NET code.

  4. Rename the existing static structure diagram in the model from Static Structure-1 to Upload Picture-c.

  5. Drag the Upload class from the Use Case and Sequence model onto the Upload Picture-c diagram.

  6. Drag the UploadForm class from the Use Case and Sequence model onto the Upload Picture-c diagram.

  7. Create a new class named SalesCompanyUser on the Upload Picture-c diagram. This class should not be inheritable, so select the IsLeaf option in the UML Class Properties dialog box.

  8. Create a new class named User on the Upload Picture-c diagram.

  9. Create an association named Upload Picture between the SalesCompanyUser and UploadForm classes. Set the reading direction to backward, and make sure the name is displayed with the reading direction. The multiplicities should be set to 1 and 0..*, and displayed for the association. Don't display the end names.

  10. Create an association named Upload between the UploadForm and Upload classes. Make sure the name is displayed. The multiplicities should be set to 1 and 1, and displayed for the association. Don't display the end names.

  11. Create a generalization between the SalesCompanyUser and User classes.

Your static structure diagram should now look like the one shown in Figure 17-5.

End example

Creating a Database Class Diagram

Here, we'll show you an example of how the tables in the Picture database are modeled in UML. Figure 17-6 shows the Picture database diagram. However, keep in mind that you generally won't model external database structures in your model, because you'll then end up having redundant documentation. The "Modeling a Database" section in Chapter 1 gives you an overview of how to model your database using the Visio database model diagram, and Chapter 16 describes various database modeling techniques.

Click To expand
Figure 17-6: Incomplete Picture database diagram

In Exercise 17-5, you'll create the Picture database diagram.

Exercise 17-5
Start example

  1. Create a new UML model named Database, and rename the Top Package package to CoffeeInc.

  2. Rename the existing static structure diagram in the model from Static Structure-1 to Picture.

  3. Create a new class named Pictures with the Table stereotype.

  4. Create the following table fields/columns (attributes) in the class (we use IDL data types for these): ID object(idl), Path wstring(idl), Description wstring(idl), and PictureType object(idl).

    Note

    Notice how we use the IDL object data type for the ID column. This is to indicate that we want to use Guids as the primary key. The PictureType is the foreign key for looking up the PictureType ID in the PictureTypes class/table.

  5. Create a new class named PictureTypes with the Table stereotype.

  6. Create the following table fields/columns (attributes) in the class: ID object(idl) and PictureType wstring(idl).

  7. Create an association between the PictureTypes and Pictures classes. The multiplicities should be set to 1 and 0..*, and displayed for the association. Don't display the end names.

Your static structure/database diagram should look like the one shown in Figure 17-6.

End example

Don't feel tempted to simply translate all your classes in your class diagram to tables in your database diagram,[1] because you'll end up with too many tables and a database that isn't normalized. Instead, find out what database structure you need by looking at your sequence diagrams and class diagrams, and then build the (normalized) database.

Note

Keep in mind that, in general, the database should be modeled around the data alone, and the application should be built around that. Obviously, modeling a database as well as modeling an application isn't achieved in one step; it takes several steps of modifications and refinements. It's a good idea to involve someone with a good understanding of database modeling when you look at the data structure.

In the Upload Picture-c class diagram, there's a generalization relationship between the SalesCompanyUser and the User classes. Databases don't support gen eralization, so we need to make a mapping between the Upload Picture-c class diagram and the Picture database diagram. We have decided to create just one table containing all of the records, as shown in Figure 17-7.

Figure 17-7: One table containing all User records
Start Sidebar
Reflecting Inheritance in a Database

Generalization (inheritance) is best reflected in the database as a single table (see Figure 17-7). If the number of attributes is limited, you probably will not add more subclasses, and not all fields will be filled out for every record. For example, if the record contains data for an ordinary user, the HomePage and SalesCompany fields will be empty.

Inheritance is best reflected in the database by a separate table for each subclass, with the fields from the parent class added to each subclass table, in the following cases:

  • When the number of attributes is huge

  • If more subclasses are likely to be added in the future and sequence across all users is not important

  • If user access of subclass attributes is infrequent

Figure 17-8 shows an example of using a separate table for each subclass.

End Sidebar
Click To expand
Figure 17-8: One table for each User subclass, containing all records for that specific User subclass

Refining the Class Diagram

Before generating code from the Upload Picture-c class diagram (Figure 17-5, created in Exercise 17-4), you need to refine it so that it's closer to the physical implementation. Here's what you need to do:

  • Identify extra classes needed (not identifiable from the sequence diagram).

  • Specify data types for all attributes.

  • Specify input and output parameters for all operations.

  • Specify data types for all parameters.

  • Decide the operation kind (method, property, and so on).

  • Decide if the class is instantiated as a .NET class (COM classes are not instantiated the same way as .NET classes), and determine the necessary operations needed, such as constructors, finalizers, disposal routines, and so on. In addition, classes with the form stereotype are special classes that inherit from a specific .NET class, such as a Windows form or Web form class.

Adding Classes

The first refinement is to add the extra classes needed and specify the attributes with the correct data types. The extra classes are those that are necessary for your solution to work properly, but could not be identified by looking at your sequence diagram.

In Figure 17-9, you can see that we've added the LegalRight class to the class diagram and modified the User and SalesCompanyUser classes. The solution must have a User class to handle the user functionality for the logged-on user. The SalesCompanyUser class is a subclass of the User class. Each sales company owns some legal rights (like patents). The LegalRight class will be a collection of legal rights for a specific sales company.

Click To expand
Figure 17-9: Updated Upload Picture-c class diagram

In Exercise 17-6, you'll update the Picture-c class diagram to add class attributes and a new class.

Exercise 17-6
Start example

  1. Open the Upload Picture-c class diagram in the VEA document from Exercise 17-4.

  2. Add the following private attributes to the User class (the VB data type is shown in parentheses):

    m_iD (Guid)

    m_name (String)

    m_address (String)

    m_city (String)

    m_zipCode (String)

  3. See the "Creating New Data Types" section in Chapter 16 for more information about creating new .NET data types, such as the Guid data type for the m_iD attribute.

  4. Add the following private attributes to the SalesCompanyUser class (the VB data type is in parentheses):

    m_iD (Guid)
m_homePage (String)

  5. Add a new class named LegalRight to the diagram with the following private attributes:

    m_iD (Guid)
m_description (String)
m_internationalID (String)

  6. Create an association named Owns between the SalesCompanyUser and LegalRight classes. Set the reading direction to backward, and make sure the name is displayed with the reading direction. The multiplicities should be set to 0..* and 0..*, and displayed for the association. Don't display the end names.

Your diagram should now look like the one shown in Figure 17-9.

End example

Setting Parameters for Operations

The next step is to specify the input and output parameters for the operations, as well as look at class types. Figure 17-10 shows the class diagram with parameters and data types set for each parameter.

Click To expand
Figure 17-10: Upload Picture-c class diagram with parameters and data types set for operations and inheritance set for classes

In Exercise 17-7, you'll continue updating the Picture-c class diagram.

Exercise 17-7
Start example

  1. As you can see from Figure 17-9, the Upload and UploadForm classes are placed in the Use Case and Sequence model. This isn't really a problem in our case, but it does look better to have them in the Class model. Drag them from the Use Case and Sequence model in the Model Explorer to the Class model. The Upload Picture-c class diagram is automatically updated (see Figure 17-10).

  2. Add the following parameters to the ResizePicture operation of the Upload class:

    picture (input, String)

    scalePercentage (input, Integer)

  3. Add the following parameters to the Save operation of the UploadForm class:

    name (input, String)
description (input, String)
productID (input, Guid)
uploadDate (input, Date)

  4. Add a new class named System.Windows.Forms.Form to the diagram, and set the stereotype to Type.

  5. Create a generalization (inherits) relationship between the UploadForm and System.Windows.Forms.Form classes. You can choose to specify the Inherits stereotype, but it's not required, because it's the default stereotype.

Your diagram should now look like the one shown in Figure 17-10.

End example

The UploadForm class will be implemented as a Windows form, which is why you created the System.Windows.Forms.Form class and inherited from it. The generated code will then specify the base class for the UploadForm class as the System.Windows.Forms.Form class.

Tip

Although no UI is added to the code when generated, VS .NET will automatically create the correspondent resource file (.resx) for the form when the class file is opened or added to a project.

Setting Operation Types and Adding Operations

Next, you need to set the operation types for the identified operations and add operations for the User, SalesUser, LegalRight, and Upload classes.

For the UploadForm class, all form operations are procedures, which means they have no return value (no operation type). The Upload class is a COM+ com ponent, in which all operations should be procedures with no attributes, because they should be stateless.

The operations needed by the classes that you haven't been able to identify from your sequence diagram will generally be those needed by the class from a technical perspective, like constructor and destructor/finalizer operations. Table 17-1 shows the extra operations needed. Keep in mind that some of the operation names in the table, such as Finalize, are VB .NET-specific.

Note

You can find more information about the Finalize and Dispose methods of a class in this article: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/ cpconFinalizeDispose.asp.

Table 17-1: Extra Operations Added to the Class Diagram
Class Name | Operation Name | Comment
User | New | The User class will be instantiated for each user in the system. The New operation is a constructor for the class.
User | Finalize | The Finalize operation is an operation containing any code to be executed when the class is garbage-collected.
User | Dispose | The Dispose operation is used for cleaning up (un)managed resources used by the class, and destroying the class instance.
User | CheckLogon | This operation checks if the user is logged on. It returns True or False. It takes userID as an input parameter. Although not specified, the logon information could be saved to and read from a database. You could choose to implement this as a property instead of an operation.
User | GetInfo | This operation returns user information in a DataSet. This operation must be overridable in derived classes. You can also choose to implement each piece of user information as individual read-only properties. You can do this in addition to or instead of the GetInfo operation.
User | Delete | This operation deletes a user. We had some arguments about the implement ation of this operation—should it be a static and/or an instance operation? We've chosen an instance operation, meaning you need to instantiate the user you want to delete. This action will also destroy the User class instance. However, you might want to make it static and pass a user ID as input parameter.
User | Add | This operation adds a user. It takes name, address, city, and zipCode as input parameters and returns the user ID as an output parameter. This must be a Shared/static operation, because you should be able to call it without instan tiating a user class. Instead of returning the user ID, this operation could return a User class instance with the user infor mation for the new user. We've chosen to return the user ID.
User | Update | This operation updates information for a specific user. It takes name, address, city, and zipCode as input parameters.
SalesCompanyUser | New | The SalesCompanyUser class will be instantiated for each sales company user in the system. The New operation is a constructor for the class.
SalesCompanyUser | GetInfo | This operation returns user information. This operation overrides and accesses the GetInfo operation in the parent User class and returns the user information specified by the base class, as well as the extra information specified by this class.
SalesCompanyUser | Add | This operation adds a user. It takes name, address, city, zipCode, and homePage as input parameters and returns the user ID as an output parameter. This must be a static operation.
SalesCompanyUser | Update | This operation updates information for a specific user. It takes name, address, city, zipCode, and homePage as input parameters.
LegalRight | New | The New operation is a constructor for the class.
LegalRight | Add | This operation adds a legal right. It takes description and internationalID as input parameters and returns the legal right ID as an output parameter.
LegalRight | Update | This operation updates information for a specific legal right. It takes description and internationalID as input parameters.
Upload | Objectcontrol_Activate | This operation is required for the COM+ component. It's similar to the New oper ation. This operation must be private according to the COM+ specification.
Upload | Objectcontrol_Deactivate | This operation is required for the COM+ component. It's similar to the Dispose operation. This operation must be private according to the COM+ specification.
Upload | Objectcontrol_CanBePooled | This operation is required for the COM+ component. It must be private according to the COM+ specification.
Note

The COM+ operations required for the Upload component can be implemented by inheriting from the System.EnterpriseServices.ServicedComponent class.

In Exercise 17-8, you'll complete the Upload Picture-c class diagram.

Exercise 17-8
Start example

  1. Open the Upload Picture-c class diagram in the VEA document from Exercise 17-7.

  2. Create a private variable named m_disposed of data type Boolean.

  3. Add the New operation as a public constructor to the User class.

  4. Add the Finalize operation as a protected finalizer/destructor to the User class. This operation overrides the parent finalizer/destructor. Add the following VB code to the method:

    Dispose(False)
MyBase.Finalize()

  5. The code makes sure that the class instance cleans up the resources once, and only once. In addition, the Finalize operation on the base class is called as it should be. You can add the code from the UML Operation Properties dialog box. Just select the Method category, select the Has Method option, select Code from the Language list, and type the code in the Method body text field.

  6. Create a new interface named IDisposable and attach it to the User class. Add a public method named Dispose to the interface. The operation will automatically be implemented when generating code, because the interface is attached to the class.

  7. Add a private Dispose operation to the User class, overloading the Dispose method implemented on the IDisposable interface. This operation takes an input parameter named disposing of type Boolean. Add the following VB code to the method, as shown in Figure 17-11:

    Click To expand
    Figure 17-11: Method category of the UML Operations Properties dialog box

    ' Has Dispose already been called?
If Not m_disposed Then
   ' Dispose all resources used
   If disposing Then
      ' Dispose managed resources
   End If

   ' Dispose unmanaged resources
End If

m_disposed = True

  8. Add the CheckLogon operation to the User class. It should return True or False, depending on whether the user contained in the current User class instance is logged on.

  9. Add the GetInfo operation to the User class. It returns a System.DataSet and it must be overridable. See the "Creating New Data Types" section in Chapter 16 for more information about creating new .NET data types like System.DataSet.

  10. Add the Delete operation to the User class. This operation doesn't return a value.

  11. Add the static Add operation to the User class. It returns a Guid and accepts the following input parameters:

    name (String)

    address (String)

    city (String)

    zipCode (String)

  12. Add the Update operation to the User class. This operation doesn't return a value, but requires the following input parameters:

    name (String)

    address (String)

    city (String)

    zipCode (String)

  13. Add the New operation as a constructor to the SalesCompanyUser class.

  14. Add the GetInfo operation to the SalesCompanyUser class. This operation overrides and accesses the parent operation of the same name. It returns a System.DataSet.

  15. Add the static Add operation to the SalesCompanyUser class. It returns a Guid and accepts the following input parameters:

    name (String)

    address (String)

    city (String)

    zipCode (String)

    homepage (String)

  16. Add the Update operation to the SalesCompanyUser class. This operation doesn't return a value, but requires the following input parameters:

    name (String)

    address (String)

    city (String)

    zipCode (String)

    homepage (String)

  17. Add the New operation as a constructor to the LegalRight class.

  18. Add the Add operation to the LegalRight class. It returns a Guid and accepts the following input parameters:

    description (String)

    internationalID (String)

  19. Add the Update operation to the LegalRight class. This operation doesn't return a value, but requires the following input parameters:

    description (String)

    internationalID (String)

  20. Add a new class named System.EnterpriseServices.ServicedComponent to the diagram, and set the stereotype to Type.

  21. Create a generalization (inherits) relationship between the Upload and System.EnterpriseServices.ServicedComponent classes. You can choose to specify the Inherits stereotype, but it's not required, because it's the default stereotype.

Your diagram should now look like the one shown in Figure 17-12.

Click To expand
Figure 17-12: Complete Upload Picture-c class diagram

End example

The Upload class will be implemented as a ServicedComponent class, which is why you created the System.EnterpriseServices.ServicedComponent class and inherited from it.

Reviewing OOP Techniques

In our modeling, we've used the OOP techniques of overriding and overloading.

Overriding occurs between operations on a base and derived class where the operation name and parameter types are identical. In VEA UML, you need to mark the operation in the base class as IsPolymorphic in the UML Operation Properties dialog box.

Overloading occurs between methods on the same class (in derived and/or base class) that have an identical name but different parameter types. The col lection of data types of the parameters is called the method signature. The method signature makes a method different from another method with the same name. Method overloading even allows you to access both of the methods in your class. Because the method signature is unique, .NET knows which method to invoke by looking at the passed-in parameters. You don't need to do anything special to overload an operation in VEA UML; it happens automatically.

Note

When your overloads exist in a derived class and the original method in the base class, it seems VEA has a problem adding the Overloads keyword (VB .NET) to the method signature, which it really should. C# doesn't use a keyword for overloading, so it's not a problem here. We'll address this problem in the "Generating the Code Again" section later in this chapter.

[1]Believe us, we've seen developers new to OOP doing this several times.


Generating the Code for the Upload Classes

Before creating the remaining sequence and class diagrams, you can generate the code for the classes you just created. Doing this before creating the remaining sequence and class diagrams is not really what UML suggests, because you need to optimize the sequence and class diagrams, and maybe remove some of the classes you just created. However, we encourage you to generate the code now, despite the drawbacks, because you get the advantage of having the VS .NET project created. You can easily delete or regenerate the code later. So, let's generate the code for the class diagram.

To generate the code from the class diagram, choose UML® Code ® Generate. In the Generate dialog box, all of the classes, except the System.Windows.Forms.Form class, are selected, as shown in Figure 17-13. There's no need to generate this class, because it's simply a trick to generate the correct code—that the UploadForm class inherits from this .NET class. We don't need to generate the IDisposable interface either, because it is also used for the same trick.

Click To expand
Figure 17-13: Generate dialog box with classes selected

If you double-click the generated CoffeeInc.sln solution file, VS .NET opens, as shown in Figure 17-14.

Click To expand
Figure 17-14: Generated CoffeeInc.sln solution opened in VS .NET

Generating the User Class Code

In Listing 17-1, you can see the code generated for the User class.

Listing 17-1: User Class Generated Code
Start example
 1 Public Class User
 2   Implements IDisposable
 3
 4   Private m_iD As Guid
 5
 6   Private m_name As String
 7
 8   Private m_address As String
 9
10   Private m_city As String
11
12   Private m_zipCode As String
13
14   Private m_disposed As Boolean
15
16   Public Sub Dispose() Implements IDisposable.Dispose
17
18   End Sub
19
20   Public Sub New()
21
22   End Sub
23
24   Public Function CheckLogon() As Boolean
25
26   End Function
27
28   Public Overridable Function GetInfo() As DataSet
29
30   End Function
31
32   Public Sub Delete()
33
34   End Sub
35
36   Public Shared Function Add(ByVal name As String, _
37          ByVal address As String, _
38          ByVal city As String, _
39          ByVal zipCode As String) As Guid
40
41   End Function
42
43   Public Sub Update(ByVal name As String, _
44       ByVal address As String, _
45       ByVal city As String, _
46       ByVal zipCode As String)
47
48   End Sub
49
50   Protected Overrides Sub Finalize()
51    Dispose(False)
52    MyBase.Finalize()
53   End Sub
54
55   Protected Sub Dispose(ByVal disposing As Boolean)
56      ' Has Dispose already been called?
57      If Not m_disposed Then
58         ' Dispose all resources used
59         If disposing Then
60            ' Dispose managed resources
61         End If
62
63         ' Dispose unmanaged resources
64      End If
65
66     m_disposed = True
67   End Sub
68
69 End Class
End example

As you can see from the listing, the IDisposable interface is implemented, and all of the methods it specifies, which is just the Dispose method, are automat ically created for you on lines 16 through 18. Everything else is as we specified in the Exercises.

Generating the SalesCompanyUser Class Code

Listing 17-2 shows the code generated for the SalesCompanyUser class.

Listing 17-2: SalesCompanyUser Class Generated Code
Start example
 1 Public NotInheritable Class SalesCompanyUser
 2    Inherits User
 3    Private m_iD As Guid
 4
 5    Private m_homePage As String
 6
 7    Public Sub New()
 8
 9    End Sub
10
11    Public Shadows Function GetInfo() As DataSet
12
13    End Function
14
15    Public Shared Function Add(ByVal name As String, _
16           ByVal address As String, _
17           ByVal city As String, _
18           ByVal zipCode As String, _
19           ByVal homepage As String) As Guid
20
21    End Function
22
23    Public Sub Update(ByVal name As String, _
24       ByVal address As String, _
25       ByVal city As String, _
26       ByVal zipCode As String, _
27       ByVal homepage As String)
28
29    End Sub
30
31 End Class
End example

Notice the following in Listing 17-2:

  • VEA has included the NotInheritable VB .NET keyword on line 1 to indicate that other classes can't be derived from this class. The C# equivalent is sealed.

  • VEA has generated the code so that class is derived from the User class using the Inherits keyword on line 2.

  • The GetInfo method shadows the function by the same name in the base class using the Shadows keyword. This is wrong; we want to override the GetInfo method in the base class, not shadow it.

In the next sections, we'll explain why using Shadows is a problem and how to model polymorphism correctly.

Understanding Method Overriding and Shadowing/Hiding

Knowing the difference between the method overriding and shadowing/hiding is important to having your methods and operations behave correctly. Your methods can be implemented using both, but there's a difference between the two.

Overriding a method means that an overridable method (marked Overridable/MustOverride in VB .NET or virtual/abstract in C#) implemented in a base class (Class1) is overridden in a derived class (Class2). Specifically, it means that Class2 has a method of the same name and signature as a method marked overridable in Class1. An overridden method is not accessible in any class that inherits Class2. Overriding is indicated using the Overrides keyword in the method signature in VB .NET and override in C#.

Shadowing a method[2] means that a method implemented in a base class (Class1) is shadowed in a derived class (Class2)—the base class method is hidden. Specifically, it means that Class2 has a method of the same name as a method in Class1. A shadowed method is accessible in any class that inherits Class2, although only by casting the subclass to Class1. Shadowing is indicated using the Shadows keyword in the method signature in VB .NET. In C#, it's done using the new keyword.

Note

You can't override or shadow the default constructor.

Whether you override a method or shadow it depends on the context. You might want to access both versions of a method, but generally when modeling polymorphism, you'll want the child class to polymorphically substitute the base class methods by overriding.

One situation where you'll see shadowing used is when inheriting from a third-party classes, where the vendors have marked certain methods as not over ridable, because they don't want you to overwrite the behavior.

Modeling Polymorphism Correctly

Polymorphism—the ability to have different behavior for the same operation/method—is one of the strongest object-oriented building mechanisms. Polymorphism is tightly related to inheritance. For example, if you wanted the GetInfo function to act somewhat differently in derived classes, you could create a class derived from a base class, and then extend the methods you need to behave differently from the behavior specified in the base class.

In this chapter, we modeled polymorphism by having the same operation placed in both the base class and the child class. You can see this in the Upload Picture-c class diagram (Figure 17-12), where the GetInfo operation exists in both the User and SalesCompanyUser classes. However, as you saw from the generated code in Listing 17-2, this way of modeling polymorphism resulted in an operation in the child class with the Shadows keyword instead of the desired Overrides keyword.

As we stated in the previous section, true polymorphism requires the use of the Overrides keyword in VB .NET (this keyword is not needed in C#). In Exercise 17-9, you'll make VEA generate the polymorphic operations in the child classes using the Overrides keyword.

Exercise 17-9
Start example

  1. Open the Upload Picture-c class diagram in the VEA document from Exercise 17-8.

  2. Open the UML Class Properties dialog box for SalesCompanyUser, select the Operations category, and delete the GetInfo operation.

  3. Click the Methods button.

  4. In the UML Method Properties dialog box, select the GetInfo operation on the User class in the Operation name list, as shown in Figure 17-15. Select the Has Method option, and choose Code from the Language list. In the Method body text field, you can write the code to be generated for the polymorphic operation, such as a call to the overridden operation in the base class (MyBase.GetInfo) and the code that extends the overridden operation. The Has Method option tells VEA that you want to override the inherited operation.

    Click To expand
    Figure 17-15: Selecting the Has Method option for the GetInfo operation

    Caution

    If you try to inherit and override an illegal operation, such as an operation marked as a destructor, VEA tends to mess up the generated code.

  5. Click OK twice to close the UML Method Properties and UML Class Properties dialog boxes.

End example

Now, the SalesCompanyUser class in the Model Explorer no longer contains the GetInfo operation, but it is modeled as part of the SalesCompanyUser class on the class diagram. If you open the UML Class Properties dialog box and select the Operations category, you'll see that the GetInfo operation isn't there.

Regenerating the Code

After following Exercise 17-9, regenerate the code (by selecting UML ® Code®Generate). In the Generate dialog box, keep the settings from the previous code generation, and then select the classes for which you want to generate code. You need to generate code only for the class you've changed: the SalesCompanyUser class.

When generating the code, you're asked if you want to add the generated files to the existing project, because the project already exists. Answer Yes to this question. Now, you can open the VS .NET project and look at the regenerated code, which is shown in Listing 17-3.

Note

If you have the VS .NET project open in the VS .NET IDE while generating the code files from within VEA, VS. NET brings up a dialog box asking you if you would like to reload the file(s) that you're generating, because they have been modified.
Listing 17-3: Modified SalesCompanyUser Class
Start example
 1 Public NotInheritable Class SalesCompanyUser
 2    Inherits User
 3    Private m_iD As Guid
 4
 5    Private m_homePage As String
 6
 7    Public Overrides Function GetInfo() As DataSet
 8
 9    End Function
10
11    Public Sub New()
12
13    End Sub
14
15    Public Shared Function Add(ByVal name As String, _
16           ByVal address As String, _
17           ByVal city As String, _
18           ByVal zipCode As String, _
19           ByVal homepage As String) As Guid
20
21    End Function
22
23    Public Sub Update(ByVal name As String, _
24        ByVal address As String, _
25        ByVal city As String, _
26        ByVal zipCode As String, _
27        ByVal homepage As String)
28
29    End Sub
30
31 End Class
End example

As you can see from line 7 of Listing 17-3, the Shadows keyword has now been replaced with the Overrides keyword. However, if you try to compile/build the project in VS .NET, you'll get a compilation error, because of the Add and Update methods that haven't been declared using the Overloads keyword. As we mentioned previously when discussing overloading, this is a problem with VEA. You'll need to add the Overloads keyword to the generated code yourself. This means that the method signatures for the Add and Update methods should look like this:

Public Overloads Shared Function Add(…) As Guid
Public Overloads Sub Update(…)

Generating the LegalRight Class Code

You've generated the code for the User and SalesCompanyUser classes. Listing 17-4 shows you the code for the LegalRight class.

Listing 17-4: LegalRight Class
Start example
 1 Public Class LegalRight
 2
 3    Private m_iD As Guid
 4
 5    Private m_description As String
 6
 7    Private m_internationalID As String
 8
 9    Public Sub New()
10
11    End Sub
12
13    Public Function Add(ByVal description As String, _
14          ByVal internationalID As String) As Guid
15
16    End Function
17
18    Public Sub Update(ByVal description As String, _
19        ByVal internationalID As String)
20
21    End Sub
22
23 End Class
End example

There is nothing new in Listing 17-4 when discussing UML modeling and .NET code generation; the code is fairly straightforward. However, in the Upload Picture-c class diagram (see Figure 17-12), you have made a relationship between the SalesCompanyUser and the LegalRight classes, indicating that the SalesCompanyUser class can access a collection of LegalRight classes, but we haven't seen that in the generated code yet. If you want to generate code that accesses collections, you must specify this in the relationship properties, which is what the next section covers.

[2]Member variables can also be shadowed.


Modeling Collections and Reflecting It in Code

As discussed in the previous section, the SalesCompanyUser class can have more than one instance of LegalRight "attached." This is indicated by the 0..* cardi nality of the Owns association in Figure 17-12 (named multiplicity in VEA). In Exercise 17-10, you'll specify that a class is related to a collection of instances of another class.

Exercise 17-10
Start example

  1. Open the Upload Picture-c class diagram in the VEA document from Exercise 17-8.

  2. Double-click the Owns association, which brings up the UML Association Properties dialog box, as shown in Figure 17-16.

    Click To expand
    Figure 17-16: UML Association Properties dialog box

  3. Select the IsNavigable option for End30. This specifies that the SalesCompanyUser class is able to navigate to the LegalRight class and create a collection of LegalRight classes.

  4. With End29 selected, click the Properties button, which brings up the UML Association End Properties dialog box, as shown in Figure 17-17.

    Click To expand
    Figure 17-17: UML Association End Properties dialog box

  5. Name the end m_legalRights. This name is used by the code-generation engine to associate to the collection. You can optionally select the IsOrdered option to sort your class your collection, but in our case, that's not desirable. Click OK to close the UML Association End Properties dialog box, and click OK again to close the UML Association Properties dialog box.

  6. Regenerate the code for the SalesCompanyUser class. (There are no changes to the LegalRight class.) The following line of code has been added to the SalesCompanyUser class:

    Private m_legalRights As System.Collections.ArrayList
End example

If you followed Exercise 17-10, you saw that a collection named m_legalRights was added to the SalesCompanyUser class. By default, the ArrayList data type is used for unordered collections when the code is generated, but why is that so? The default data types are set through VEA's preferences. If you open VEA's Pref erences dialog box by selecting UML ® Code ® Preferences, and select the Relationships category, you will see the default data types for the ordered, unor dered, and qualified lists, as shown in Figure 17-18.

Click To expand
Figure 17-18: Preferences dialog box showing the default data types for lists


Creating and Using the COM+ Component

Quite often, you will need to integrate existing COM(+) components into your .NET solution. To demonstrate how to do this, we created the Upload class as a COM+ component.

We've already covered how to inherit from the System.EnterpriseServices.ServicedComponent class in Exercise 17-8, but you also need to add a reference to the System.EnterpriseServices namespace in your project. To do this, right-click the References node in the Solution Explorer of the VS .NET IDE, select Add Reference from the pop-up menu, and select the namespace on the .NET tab of the Add Reference dialog box. Click Select to add the namespace, and then click OK to close the dialog box.

Table 17-1 specified that the COM+ component must expose three methods from the Objectcontrol interface: Activate, CanBePooled, and Deactivate. However, this isn't necessary when you inherit from the System.EnterpriseServices.ServicedComponent. Listing 17-5 shows the code generated for the Upload class.

Listing 17-5: Upload Class
Start example
 1 Public Class Upload
 2    Inherits System.EnterpriseServices.ServicedComponent
 3    Public Sub Upload(ByVal filePath As String)
 4
 5    End Sub
 6
 7    Public Sub ResizePicture(ByVal picture As String, _
 8            ByVal scalePercentage As Integer)
 9
10    End Sub
11
12 End Class
End example

One thing missing from Listing 17-5 (besides your custom code, that is) is a static Main method, which should look like this:

 Public Shared Sub Main()
 End Sub

Now, the code is finished, but you need to make it available as a COM+ com ponent in Component Services. So, how do you do that? Here are the steps:

  • Compile the class to an assembly with a strong name

  • Create a new COM+ application containing the assembly

These steps are described in the following sections.

Compiling an Assembly with a Strong Name

When compiling an assembly with a strong name, you need to create a public/private key pair saved in a key file. This is done using the strong name command-line utility, sn.exe:

sn.exe –k upload.snk

When using .NET command-line utilities, make sure you open a VS .NET 2003 Command Prompt by selecting Start ® Microsoft VS .NET 2003 ® Visual Studio .NET Tools® Visual Studio .NET 2003 Command Prompt. This will ensure that you have the path specified for most of the .NET command-line utilities, such as sn.exe. Alternatively, you can update the PATH environment variable to include the path (usually \Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin) to the VS .NET command-line tools. See the "Visual SourceSafe Administration" section of Chapter 11 for more information about updating the PATH variable.

Now that you have the key pair file, it needs to be "linked" to the class file, but this is done when compiling/building the class into a component assembly. Again, you'll use a command-line tool, the Visual Basic compiler (vbc.exe) from the folder where your project is located (\EDWVSNETUMLMSF\ Chapter 17\CoffeeInc in this example):

vbc.exe /t:library /keyfile:upload.snk /r:System.EnterpriseServices.dll Upload.vb

This will produce a strong named (/keyfile switch) DLL assembly (/t switch), with a reference to the System.EnterpriseServices namespace (/r switch).

Creating a New COM Application

Now that you have the COM+ component, you can place it in Component Services. In Component Services, you need to create a new COM+ application, which is done like this:

  1. Select Start ® Administrative Tools® Component Services to access the Component Services UI.

  2. Right-click the COM+ Applications node under the My Computer node, and select New ® Application from the pop-up menu, which opens the COM+ Application Install Wizard.

  3. Click Next on the first page of the wizard.

  4. Click the Create an empty application button on the Install or Create a New Application page of the wizard.

  5. Type the name Upload in the Enter a name for the new application text field of the Create Empty Application page.

  6. Select the Library application option in the Activation Type group, and then click Next.

  7. Click Finish to close the wizard.

  8. Expand the new application node in the COM+ Applications node.

  9. Right-click the Components node and select New ® Component from the pop-up menu, which opens the COM+ Component Install Wizard.

  10. Click Next on the first page of the wizard.

  11. Click the Install new component(s) button on the Import or install a component page of the wizard.

  12. Browse to and select the component assembly created with the vbc.exe command-line compiler earlier (Upload.dll), and then click Open.

  13. Click Next, and then click Finish to close the wizard. Your component should now be placed in Component Services, as shown in Figure 17-19.

    Click To expand
    Figure 17-19: Component Services with the new component

We've just made you go through the registration process the hard way, because we wanted you to see the Component Services application. However, there's a much easier way of doing this: use the command-line .NET Services Installation utility, regsvcs.exe.[3] To perform the same registration you've just done using the UI, simply type in this command from the command line:

Regsvcs.exe Upload.dll

Open Component Services to see if your component has been registered after using the .NET Services Installation utility.

Note

We've chosen not to place the strong-named assembly in the GAC, but in most cases, this is desirable and even necessary when registering as a COM+ application. See your documentation for more information.

Adding a Reference to the COM Component

Your component has now been placed in Component Services, and it's accessible to any application that can use COM components. However, what about your own solution? Well, you need to add a reference to it from the solution. As you know, .NET expects all types to be defined as metadata in an assembly. This goes for COM components as well, so you'll need to generate metadata for your COM component. However, VS .NET can do this for you automatically, when you add a reference to a COM component.

In the VS .NET IDE, right-click the References node in the Solution Explorer and select Add Reference from the pop-up menu. In the Add Reference dialog box, select the COM tab, select the component, and click Select to add the ref erence. Click OK to close the dialog box. VS.NET will import the type library automatically, create the wrapper assembly, and include it into your project. Now, you can use the component from code in your project.

Note

See your Windows documentation for more information about COM+ and Component Services.

Although the procedures given for adding a reference to a COM+ component from your solution are correct, they don't work for this particular component. You'll see this message instead:

Click To expand

This message makes sense, but what do you do? You simply add a reference to the assembly (.dll) as you would normally do, and that solves the problem.

[3]There are a number of switches for regsvcs.exe. You can type in the name of the utility at the command line to see the various switches.


Summary

In this chapter, we focused on the code, including how to generate the correct code. We started out gathering all the requirements for a project. Then we con centrated on a single use case and its corresponding sequence diagram in order to drill down into its details. The use case covered the main development aspects:

  • Converting a sequence diagram into a class diagram

  • Refining a class diagram

  • Creating .NET data types

  • Preventing class inheritance

  • Modeling and implementing polymorphism

  • Modeling collections

  • Creating COM+ code

You saw how to model a .NET class in any .NET namespace from which you can inherit your own classes. You also learned how to model polymorphism in two ways: overriding and shadowing operations in derived classes. In creating classes, you learned that the association ends control the creation of collections. Finally, you saw how to generate COM+ code and add a reference to a COM+ component in VS .NET.

In the next chapter, you will learn about IBM Rational XDE and its facilities. This will enable you to compare VEA to IBM Rational XDE.


Part V: Modeling Tools

Chapter List

Chapter 18: IBM Rational XDE
Chapter 19: Comparing Microsoft and IBM Rational UML Tools and Development Frameworks


Chapter 18: IBM Rational XDE

Overview

In this chapter we'll introduce you to IBM Rational XDE (XDE). The version we cover is IBM Rational XDE Developer 2003 for .NET, because this edition is aimed toward .NET developers and contains code generation for .NET.

First we'll provide a short introduction to the XDE VS .NET integration. Then we'll move on to discuss modeling and diagramming with XDE, and how UML models can be migrated between IBM Rational Rose (Rose) and XDE, and XDE and VEA. Finally, we briefly discuss code templates and design patterns.

Most of the material in this chapter is based on information we've provided elsewhere in this book, such as the UML information in Chapters 3, 4, 5, and 7. You should have at least a basic understanding of UML before you read this chapter, as we won't explain UML in any detail here.


XDE VS .NET IDE Integration

XDE is the latest UML tool from IBM Rational, with the previous one being the award-winning Rose. Rose is a stand-alone application, whereas XDE is merely an add-in to the VS .NET IDE. Because XDE merges into the .NET IDE, it can't be used without VS .NET. Recently, IBM Rational made some changes to their modeling products, which saw the inclusion of Rose in the various XDE packages. Subse quently, the product name was changed to IBM Rational Rose XDE. In this chapter we cover only the XDE part of the product, the VS .NET add-in.

Note

When referring to IBM Rational Rose in this chapter, we specifically refer to previous versions of the product, not the one included with the new IBM Rational Rose XDE line of products.

XDE adds a number of features to the VS .NET IDE, such as new UML Toolbox tabs, the Model Explorer, and the Pattern Explorer. In Table 18-1, you can see most of the XDE features available from the VS .NET IDE.

Table 18-1: XDE VS .NET IDE Features
Feature/VS .NET IDE Element | Description
Toolbox | New UML tool tabs appear in the Toolbox (see Figure 18-1).
Solution Explorer | The Solution Explorer shows the XDE files added to the project(s) of the solution, just like any other project items.
Model Explorer | The Model Explorer displays all the models and elements in the same fashion as the Solution Explorer. By default, the Model Explorer is a tab in the Solution Explorer window. If it isn't shown, you can display it by selecting View ®Other Windows ® Model Explorer or by pressing Ctrl+Shift+X.
Pattern Explorer | The Pattern Explorer displays all elements that are used by a specific pattern (we explain patterns later in this chapter). By default, the Pattern Explorer is a tab in the Solution Explorer window. If it isn't shown, you can display it by selecting View ®Other Windows ® Pattern Explorer.
Properties window | The Properties window can show properties for selected elements, such as patterns in the Pattern Explorer or models, model elements in the Model Explorer, or code elements.
Task window | Model validation errors and warnings are displayed in this window, in line with code syntax and compilation errors.
Output window | This window shows a log of creation or modification of model file, model element, and so on.
Programming language– specific modeling toolbox and context menus | Depending on the programming language of the project, programming language–specific Toolbox tabs and context menus are displayed when an XDE model is open in the IDE.
Model Documentation window | This window displays documentation for the selected element. This is similar to the Documentation window in VEA.
Click To expand
Figure 18-1: XDE Toolbox tabs

Figure 18-1 shows the XDE Toolbox tabs, one of the many features XDE adds to the VS .NET IDE.


Modeling with XDE

You have three ways to start modeling using XDE. First, you can begin modeling in XDE without an existing (related) VS .NET project. You'll begin this way if you're working on a new project and you haven't done any coding yet, which is ideally how you should start. To do so, follow these steps:

  1. Open VS .NET and select File ® New® Project or press Ctrl+Shift+N to open the New Project dialog box.

  2. Select the Empty Project template in the Rational XDE Modeling Projects category and click OK.

When you start with an empty XDE project, there are no UML models in your project; you must add them manually.

The second way to start modeling with XDE is to reverse-engineer an existing solution into an XDE model. You can start documenting an existing solution by opening it and reverse-engineering the code into UML. Keep in mind, though, that only the classes are reverse-engineered—no UML models are created. You'll have to create the UML models yourself. To reverse-engineer a solution into UML, right-click the solution in the Solution Explorer and select Reverse Engineer from the context menu. The UML model files (.mdx) are added to the project(s) in the solution and shown in the Solution Explorer. You can see the UML model in the Model Explorer.

Finally, you can create a new UML model as a solution item in an existing VS .NET solution. If you have an existing solution, you can add a new XDE UML model to your solution. To do so, follow these steps:

  1. Right-click the solution or a project within the solution in the Solution Explorer, and select Add ® Add New Item from the pop-up menu to open the Add New Item dialog box.

  2. Select Rational XDE from the Categories list and choose the Blank Model template.

  3. Type in a name for the UML model in the Name text field and click OK.


Diagramming with XDE

Once your model is open in the VS .NET IDE, you're ready to start diagramming. By default, every project contains a Main diagram sheet, on which you can start diagramming right away. If you create a new model without having an existing solution, a new solution is created automatically and the new model file is created in the Miscellaneous Items folder. If you create a new model in an existing solution, the new model file is created in the Solution Items folder.

The Main diagram is by default a free-form diagram, meaning you can start modeling any kind of diagram on the Main diagram sheet. This is similar to VEA, in which you can also create non-UML diagrams, although not in a UML model (non-UML diagrams must be created in a separate model). In XDE, the free-form diagram is, as its name suggests, available for modeling anything, including non- UML elements.

If you want to add a new diagram to your UML model, follow these steps:

  1. Open the Model Explorer.

  2. Right-click the model to which you want to add a new UML diagram.

  3. Select Add Diagram ® <Diagram Type> from the pop-up menu.

The modeling technique is similar to what you've learned using VEA in previous chapters. In fact, that's the purpose and strength of UML, so we won't describe this technique again using XDE syntax. One thing you should notice is that the UML version XDE supports is different from the UML version VEA supports. We discuss this further in Chapter 19, so don't worry about it for now.

In the next few sections we'll describe some of the differences between VEA and XDE that will affect the way you work with diagrams and models.

Setting Properties

As mentioned earlier, one of the ways XDE takes advantage of the VS .NET IDE is through the Properties window. This means that you'll use the Properties window whenever you want to set some properties for any model element, just like any other code or UI element.

Figure 18-2 shows the Books and Categories classes from the Duwamish DataAccess project placed on a class diagram with an association relationship between them.

Click To expand
Figure 18-2: Related Books and Categories classes from Duwamish DataAccess project in a class diagram
Note

We've reverse-engineered the Duwamish 7.0 VB sample application that comes with VS .NET. We located the application in the \Program Files\Microsoft Visual Studio .NET 2003\Enterprise Samples\Duwamish 7.0 VB folder, opened the duwamish.sln solution file, right-clicked the solution in the Solution Explorer, and selected Reverse Engineer from the pop-up menu.

If you want to set any properties for this relationship, you right-click the relation and select Properties from the pop-up menu, or press F4. As you can see in Figure 18-2, the Properties window shows the association relationship properties.

Creating Sequence Diagrams

We promised not to bore you with more guidance on UML diagramming, but we have to tell you a bit about sequence diagram modeling, because the sequence diagram behavior in XDE is different from the sequence diagram behavior in VEA.

XDE sequence diagrams must be owned by an interaction, which in turn must be owned by either a collaboration or a collaboration instance. This makes sense in that a sequence must come from something that owns that sequence. It means that you can't create ad hoc sequence diagrams without knowing about the objects participating in the sequence. Explorative, conceptual sequence dia grams at the analysis level just aren't possible anymore. In our opinion, this is a major inconvenience, because we like creating sequence diagrams early in the modeling phase as an analysis tool and then refining them later on.

As you learned in Chapter 4, there are two types of interaction diagrams: sequence diagrams and collaboration diagrams. Collaboration diagrams aren't supported by this release of XDE, although collaborations are. As a result, the following can happen when you add a sequence diagram to your model:

  • If you add a sequence diagram to an empty interaction or interaction instance, an empty diagram is created.

  • If you add a sequence diagram to an interaction or interaction instance that contains model elements (objects or classifier roles), a new sequence diagram is created, and it populates the shapes representing the model elements.

  • If you add a sequence diagram to a model, an empty sequence diagram is created as well as a new collaboration instance and interaction instance, because a sequence diagram must be owned by a collaboration or interaction.

Synchronizing Your Code and Model

XDE has, unlike VEA, built-in round-trip engineering. This means that your code and model stay in sync with each other as you make changes to either. This is called synchronization. XDE can synchronize your Visual C# or VB .NET source code with its UML model.

You can take advantage of the synchronization functionality after you've made changes to your code or model. To synchronize your code and model, simply right-click the solution in the Solution Explorer and select Synchronize from the pop-up menu.

If you want to keep your model up to date with your code, you should con sider enabling the Automatic Synchronization feature by following these steps:

  1. Select Tools ®Options.

  2. Choose Rational XDE ® Round-Trip Engineering ® Synchronization Settings.

  3. Select the Automatic Synchronization option, as shown in Figure 18-3. By default, manual synchronization is selected (rather, the Automatic Synchronization option isn't selected by default).

    Click To expand
    Figure 18-3: Automatic Synchronization feature in the Options dialog box

    Tip

    You can navigate between your UML elements and your related code by right-clicking an element in the Model Explorer and selecting Browse Code from the pop-up menu. Likewise, you can right-click a declaration in a source code file and select Browse Model from the pop-up menu.
    Note

    Synchronization conflicts (when the code and model can't be merged), errors, and warnings that require user actions are shown in the Task List window.

In Figure 18-3, you can see how you can enable automatic synchronization between your UML model and code. Although you can enable or disable auto matic synchronization for your entire model, you can still control how individual elements react on synchronization. Figure 18-4 shows the Categories class of the Duwamish DataAccess project's Synchronization policy property and settings.

Figure 18-4: Synchronization policy property for the Categories class

Table 18-2 contains a short description of each possible value for the Synchronization policy property.

Table 18-2: Synchronization Settings for an Element
Value | Description
Synchronize | Bidirectional synchronization is enabled for the model element.
Disabled | The model element doesn't take part in synchronization, and no changes will be reflected in the code or model.
Accept code changes | Code changes are accepted for the model element; the code element won't be changed.
Accept model changes | Model changes are accepted for the code ele ment; the model element won't be changed.
Start Sidebar
Viewing Your Code and UML Simultaneously

If you split the view in VS .NET, you can see your code and UML at the same time, as shown in Figure 18-5. To do this, open both the diagram and the code module. Then right-click the tab of one of the opened documents and select New Horizontal Tab Group from the pop-up menu. You can remove the split by right-clicking the tab of the window with the two documents open and selecting Move to Previous Tab Group from the pop-up menu.

Click To expand
Figure 18-5: See your code and UML at the same time by splitting the view in VS .NET.
End Sidebar


Migrating Models

Migration is always an issue when a new version of a product is introduced, and XDE is no exception. In the next two sections we'll explain how easy it is to migrate UML models from Rose to XDE, and how painful it is to migrate from any non- IBM Rational UML model to XDE.

Migrating from Rose to XDE

Even though XDE and Rose are completely different products, we think it's fair to say that XDE is an evolution of Rose. Because of this, many XDE users will come from the Rose platform. IBM Rational is aware of this and has made it easy to migrate existing Rose models to XDE.

To migrate a Rose model to XDE, all you have to do is open the model in VS .NET and it is automatically converted. Figure 18-6 shows a simple Rose model that consists of the following:

Click To expand
Figure 18-6: Simple Rose model

  • Use Case View package

  • Main use case diagram

  • Customer actor

  • Place Order use case

  • Association between the Customer and the Place Order use case

  • Logical View package

  • Collaboration Diagram

  • Order object

  • Invoice object

  • Object link between the Order and Invoice objects

  • Account object

  • Object link between the Account and Invoice objects

  • Component View package

  • Deployment View package

To convert this simple Rose UML model (.mdl), open the file in VS .NET by selecting File ® Open ® File, and choose the Rose model file. XDE then automat ically converts the model to XDE and adds the model to your solution. Figure 18-7 shows the result.

Figure 18-7: Rose model converted to XDE

As you can see, all your elements, including packages, are converted nicely to XDE. You can also see that your collaboration diagram isn't converted, however. As we mentioned earlier, XDE doesn't support collaboration diagrams, but it does support collaborations. That's why the collaboration elements are converted, but the collaboration diagram no longer exists.

You should be aware of the following points when you convert Rose models to XDE:

  • Collaboration diagrams aren't converted; only the collaboration diagram elements are converted.

  • Rose supports path maps, but XDE doesn't. Path maps are a feature of Rose that enable you to create an entry to represent a mapping between a virtual path and a physical path. This way, you can work with models across workspaces and archives by manipulating the physical directory, which is associated with a user-defined symbol (a virtual path). You can open the Rational Rose Pathmap Editor from the Start menu or select Rational Software ® Rational Rose Pathmap Editor. Figure 18-8 shows the Rational Rose Pathmap Editor.

    Click To expand
    Figure 18-8: IBM Rational Rose Pathmap Editor

Migrating from XDE to VEA

It isn't possible to open an XDE model in VEA. You can develop your own converter by writing a script that uses the two object models to generate a VEA model on the basis of an XDE model, but we don't think it's worth the hassle. You should consider the two products as unable to integrate with each other.


Code Templates

Wouldn't it be nice if you could specify code snippets that are automatically applied to your classes when forward-engineered? Well, this is exactly what code templates in XDE enable you to do. This functionality works in many ways like the templates in VEA, where you also have the option to add code to your classes (and other elements). The code templates in XDE, however, are a bit more sophisticated.

The XDE code templates consist of a text block, and you can type in the code you want to be generated for the element in any supported language. XDE code templates have the following features:

  • Code templates are related to a model element through a code template binding.

  • Code templates can have parameters. The parameters can be of the type string or ModelElement. On the basis of your parameters you can, for example, add different code or scriptlets.

  • Code template bodies can include the following: Java classes, COM classes, JavaScript (scripted templates or external script files), and .NET classes.

  • JavaScript-scripted templates (scriptlets) are enclosed by <% and %>, no matter which scripting language you use. The scriptlets can access parameters as well as the XDE object model and the object from which the template is related. For example, you can use the scriptlet <%=InputClass%> to insert the name of the class. The default scripting language is JavaScript, which currently is the only scripting language supported.

  • Code templates bound to only one model element and stored in the model are called internal code templates.

  • Code templates bound to more than one model element and stored in an external XML file are called external code templates. External code templates are stored in the code template folder by default, but you can store them anywhere. Because external code templates are XML files (the format is defined by the code template DTD), you can edit them outside the VS .NET IDE using any XML editor.

  • When code is generated, any changes to the code within the code template expanded region are replaced. An expanded region is enclosed by // characters.

Suppose that in your organization you always want the methods of your classes to contain the following code:

// This code is created by OurCompany, IT Department
// Copyright © OurCompany
// Revised History:

Instead of typing this information into every single method, you can create a code template that does it for you, as follows:

  1. Select Tools ® Code Templates® Create File to bring up the New Code Template dialog box, as shown in Figure 18-9.

    Click To expand
    Figure 18-9: Step 1 of creating a code template file with a scriptlet

  2. Type ClassGeneral (or any other name you want to give to this scriptlet) into the Name text field of the New Code Template dialog box, and insert the following text into the Description text field: This code template adds general information to the classes... Click Next.

  3. Select Scripted Template from the Body Kind list, as shown in Figure 18-10. Insert the following text into the Body text field and click Finish:

    Click To expand
    Figure 18-10: Step 2 of creating a code template file with a scriptlet

    // This code is created by OurCompany, IT Department
// Copyright © OurCompany
// Revised History

  4. Save the code template as an XML file using the Save As dialog box.

The code template XML file contains the following lines of code (one or more lines have been wrapped for display purposes):

<?xml version="1.0" encoding="UTF-8"?>
<codetemplate>
   <name>ClassGeneral</name>
   <description>This code template adds general information to the classes...
   </description>
   <userData />
   <apiMode>RXE</apiMode>
   <bodyKind>Scriptlet</bodyKind>
   <language>JavaScript</language>
   <body>
      <![CDATA[

         // This code is created by OurCompany, IT Department
         // Copyright © OurCompany
         // Revised History:
      ]]>
   </body>
   <parameterList/>
</codetemplate>

To bind your UML elements on a diagram to a code template, right-click the element and select Code Template ® Bind. The Bind Code Template dialog box appears, in which you can create a new code template or simply browse for an existing one. Click the Bind button to finish binding the UML model to a code template. You can add multiple code templates to an element, and the code gen eration will apply them in reverse order.


Design Patterns

Design patterns are a way for your design to benefit through reuse. The topic of design patterns is beyond the scope of this book, but we'll provide a brief intro duction to them here.

You use a design pattern when you want to use a tried and tested solution for a common problem. For example, suppose you want at most just one instance of your class. This is a common problem for which there is a tried and true solution: the Singleton pattern. Many other patterns are available that address other com monly occurring problems.

In XDE, along with the existing built-in patterns, you can create your own patterns from existing code or models, and that way have a pattern for how similar problems should be modeled. Creating custom patterns is an excellent way of addressing reoccurring problems that are specific to your organization. Creating a design pattern in XDE is a fairly simple process. The real challenge lies in having the knowledge and experience to flesh out a reoccurring problem (pattern) and transform it into a design that can be reused.

Patterns are modeled in XDE as parameterized collaborations, which is a group of classes that work together in a particular way and whose names are mapped to the names in your problem space. XDE design patterns are also within the scope of UML.


Learning More About XDE

The best way to learn more about XDE is to experiment with it yourself. You can download a trial edition of XDE and try it free of charge for 30 days. You can download the trial from this address: http://www14.software. ibm.com/webapp/download/preconfig.jsp?id=2003-09-18+15%3A02%3A18.447448R&cat=swdev&fam=&s=c&S_TACT= TrialsAndBetas&S_CMP=. After you install the trial, a great way to examine XDE's look and feel is to read your way through the XDE help, which is integrated into the VS .NET help.

You can find more information about XDE and Rational in general at these addresses:

  • Rational developerWorks site: http://www-136.ibm.com/developerworks/rational/

  • Rational Developer Network: http://www.rational.net (free trial membership available at http://www-106.ibm.com/developerworks/rational/library/1053.html)


Summary

This chapter introduced you to XDE. You learned about the XDE VS .NET IDE integration, and modeling and diagramming with XDE. You also explored code templates and design patterns, as well as how to migrate models between Rose, XDE, and VEA.

The most significant difference between XDE and VEA is that XDE merges totally into the VS .NET IDE, so you don't have to switch between two products when browsing your code and model. Modeling UML in XDE is similar to modeling UML in VEA, thanks to the OMG standardization. However, you can't create collaboration diagrams in XDE, only collaborations, and your sequence diagrams must be owned by an interaction.

XDE is a huge product compared to VEA, and it provides you with much more functionality than VEA. For example, in XDE you can round-trip engineer your code and model, and several developers can work simultaneously on the same model.

We didn't focus on hardware requirements for XDE in this chapter because the fact that you're developing enterprise solutions generally indicates that hardware isn't a limitation for you. However, if you need to see what demands XDE places on your hardware, visit this URL: http://www3.software.ibm.com/ibmdl/pub/software/ rational/web/datasheets/version6/xde.pdf .

In the next chapter you'll see a comparison of XDE and VEA, which we hope will help you determine which product suits your needs (and wallet) best.


Chapter 19: Comparing Microsoft and IBM Rational UML Tools and Development Frameworks

Overview

Shoule you choose to use Microsoft VEA or IBM Rational XDE? That seems to be the big question for many developers, analysts, architects, and project managers, and the online newsgroups are filled with pros and cons for each product. It's difficult—if not impossible—to give an objective, bulletproof answer to this question, because as with most IT decisions, it depends. It depends on your usage, knowledge, budget, development language, operating procedures, and so on. It seems as though the choice is also affected by personal preference and emotions.

Note

Though in this book we focus on using VEA, our goal is to provide you with information that will help you decide whether to use VEA, XDE, or another third-party product.

VEA and XDE are two very different products and they're difficult to compare, even though they're both UML software products. In this chapter, we'll outline some of the differences between VEA and XDE that can be important when deciding on the tool you'll use for modeling software. We'll compare VEA and XDE in terms of integration, object model, .NET language support, reporting, team development, UML version support, cost, and manufacturer support. In general, we feel that the difference between VEA and XDE comes down to this: VEA is development by snapshots in larger chunks, whereas XDE is development by continuous nibbles.

Later in the chapter, we'll present a brief comparison of the Microsoft Solu tions Framework (MSF) and the IBM Rational Unified Process (RUP). These two frameworks contain guidelines used for managing software development projects. You can find detailed information on MSF in Chapter 20.


Integration

One of the most important issues for many developers is how their UML tool inte grates with their existing development environment. This can determine how much help the tool provides, specifically in the areas of ease of use, intuitiveness, and hard value, such as code generation.

In this section, we'll first cover the code generation types supported by VEA and XDE, and then we'll move on to compare how VEA and XDE integrate with the VS .NET IDE.

Supported Code-Generation Types

You've already seen how VEA can automatically generate code from your static structure diagrams (class diagrams). You've also learned that there are different kinds of code generation, and you've examined the concepts of forward engineering and reverse engineering. This section pulls together what you've learned so far about these concepts in a comparison of VEA and XDE.

Here are the different kinds of code generation VEA supports:

  • Forward engineering: You use forward engineering when you generate code from your static structure diagrams. You can only generate classes with specific stereotypes, namespaces, and interfaces. (See Chapter 5 for more information.)

  • Reverse engineering: You use reverse engineering for generating a UML model in VEA based on a Visual Studio project. You can reverse-engineer a single project from a solution or the entire solution. Classes, interfaces, packages, forms, and namespaces are reverse-engineered and placed in the Model Explorer, but no diagrams are automatically created. In Figure 19-1, you can see a Windows form from a C# project that was reverse-engineered into a UML model in VEA. The form/class was then placed on a static structure diagram.

    Figure 19-1: Reverse-engineered C# form in VEA

VEA doesn't support round-trip engineering. In VEA, you have to apply your code changes manually to the UML model or reverse-engineer your code into a new UML model and thus lose all your documentation, use case diagrams, and so on. Any existing element that isn't reverse-engineered during the process is lost.

Here are the different kinds of code generation XDE supports:

  • Forward engineering: With forward engineering, you can generate code from your classes and their relations.

  • Reverse engineering: You can reverse-engineer classes and their relationships. You can also reverse-engineer forms, as shown in Figure 19-2. The class element notation of the reverse-engineered form in Figure 19-2 is done in the same way as you've learned to model forms in VEA.

    Figure 19-2: Reverse engineered C# form in XDE

  • Round-trip engineering: You can use round-trip engineering to update your UML model when changes have been made to your code, after you've successfully reverse-engineered the original code or forward-engineered the original UML model. This closes the loop in the development process. First, you reverse-engineer your code or forward-engineer your UML model to get the UML model or code skeleton. After that, you make changes to your code, perhaps including one or more new classes, or procedures, or attributes, or you make changes to the generated code. You then obviously want these changes to be reflected in your UML model, and this is where round-trip engineering comes in. Your UML model is updated (synchronized) with the changes made to your code, so the code and model are synchronized.

So, based on the supported code generation types, which product should you choose? Well, XDE offers the best choice, as it supports round-trip engineering. However, if you can live without this feature, both VEA and XDE offer the same forward- and reverse-engineering features.

Visual Studio .NET IDE Integation

When you're working professionally with VS .NET, it's important that your modeling tool of choice is tightly integrated with the development environment because this saves you the hassle of working in two different environments, one for coding and one for modeling. Both VEA and XDE are tightly integrated with VS .NET.

VEA is part of VSEA, and in Figure 19-3, you can see how the Reverse Engineer feature is available from the VS .NET IDE. XDE is more tightly integrated than VEA. VEA is a separate product, whereas XDE is effectively an add-in.

Click To expand
Figure 19-3: VEA Reverse Engineer feature in the VS .NET IDE

Besides the menu item shown in Figure 19-3, VEA provides a VS .NET IDE integrated toolbar. You can use the Toolbar tab of the Customize dialog box (Tools ®Customize) to show or hide the Visio UML toolbar. The Visio UML toolbar has only a single button, the Reverse Engineer button, as shown in Figure 19-4.

Figure 19-4: Visio UML Reverse Engineer button

VEA reverse-engineered models are added to the project and can be placed under source control like any other project item (see Chapter 11 for a detailed explanation of source control and Visual SourceSafe in particular). In Figure 19-5, you can see the reverse-engineered UML model, which is automatically placed in the Solution Items folder in the Solution Explorer (in fact, you can see both a VEA and an XDE model in the Solution Items folder, because we've reverse-engineered the solution into both VEA and XDE UML models).

Click To expand
Figure 19-5: VEA reverse-engineered model placed in the Solution Explorer

Unlike VEA, XDE and VS .NET are not two independent products, meaning that XDE operates as an add-in rather than as a stand-alone product. XDE adds the following items to the VS .NET IDE:

  • Toolbars, including Rational XDE Appearance, Rational XDE Compare/ Merge, Rational XDE Modeling, and Rational XDE Round-Trip Engineering.

  • The Model Explorer, as shown in Figure 19-6. The Model Explorer contains all the model elements and snaps into VS .NET as a tab in the Solution Explorer.

    Figure 19-6: Rational XDE Model Explorer

  • The Model Documentation window, as shown in Figure 19-7. The Model Documentation window snaps into the Tools window, which is normally placed at bottom of the IDE, as a tab. It contains the code properties, an integrated help system (including dynamic help), and the model properties.

    Click To expand
    Figure 19-7: Rational XDE Model Documentation window

With the exception of the toolbars and the Model Explorer, XDE makes use of existing items in the IDE, such as the Properties and Dynamic Help windows.


Object Model

Both VEA and XDE provide you with libraries for external automation. External automation means that the type library (object model) is available for you in external tools. For example, you can make a reference in VB 6.0 to the type library and access the models for editing, showing, saving, and so on. This is a powerful feature because you're in control of your model, and you can access your model from external environments.

The Microsoft Visual Basic for Applications (VBA) project of a Visio document automatically references the Visio type library. If you want to use the type library from an external development environment, you'll have to reference that type library. If you reference the Microsoft Visio 2002 type library in VB 6.0 (reference the \Program Files\Microsoft Office\Visio10\vislib.dll file), you can access the Visio type library and (for example) write the following VB 6.0 code:

Dim MyVisioApp As Visio.Application

You can find the Visio object model at these addresses:

  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/modcore/html/ degrfMicrosoftVisioObjectModel.asp

  • http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devref/object.asp

The XDE type library is like the Visio type library, in that's it's also available for external development environments. For example, from VB 6.0 (or any other COM-enabled development tool) you can create a reference to the Rational XDE RTE 2.0 type library in the form of the \Program Files\Rational\XDE\addins\ vs7rte\vsnet\rte.dll file and write the following VB 6.0 code:

Dim MyRose As RoseApp
MyRose.ModelExplorer


.NET Language Support

Both VEA and XDE support more than one .NET programming language. However, they do differ in their programming language support. Whereas VEA supports C#, C++, and VB .NET equally well, XDE supports the C# and VB .NET programming languages, as well as ASP.NET. Despite the support for VB .NET and ASP.NET, IBM Rational's primary target audience for years has been C and Java developers (according to the IBM Rational representatives we've spoken with).


Reporting

Reporting is helpful for documentation purposes and for distributing documen tation to external parties, such as your customers. In Chapter 12, you saw that VEA's reports are somewhat limited. Here are the UML reports you can create with VEA:

  • UML Activity Report

  • UML Component Report

  • UML Deployment Report

  • UML Statechart Report

  • UML Static Structure Report

In contrast with VEA, XDE provides a more mature reporting facility and offers the same modification capabilities as VEA. Here are the report types offered by XDE:

  • Summary Classifier Report

  • Summary Classifier and Diagram Report

  • Detailed Class Report

  • Detailed Use Case Report


Team Development

When you were introduced to VEA in Chapter 12, you learned that VEA isn't a true team development tool. For example, it's very hard for more than one person to work on the model at the same time, and Visio doesn't provide any features to make concurrent use possible. We showed you some tips for how to work with Visio in a team in spite of this limitation.

XDE, on the other hand, provides the opportunity for team members to work on different areas of the same model at the same time. In XDE this is made pos sible through storage units, which offer a way for you to split your model into several physical files. For example, you can have a model containing just a class diagram and a deployment diagram. If you place the two diagrams and all their related elements in two distinct files, one developer can work on the class diagram (the class diagram file) while another developer can work on the deployment diagram (the deployment diagram file).

Storage units under source control (e.g., Visual SourceSafe, which is described in Chapter 11) are called controlled units, because the access (i.e., editable access) is controlled by the source control tool.

In XDE you can store the following elements in distinct files, which are storage units or controlled units depending on whether the files are under source control:

  • ActivityGraph (.agx)

  • Actor (.acx)

  • Class (.clx)

  • Collaboration (.cbx)

  • CollaborationInstance (.cix)

  • Component (.cmx)

  • ComponentInstance (.cnx)

  • Diagram (.dgx)

  • Enumeration (.enx)

  • Exception (.exx)

  • Facade (.fcx)

  • Interaction (.inx)

  • InteractionInstance (.iix)

  • Interface (.ifx)

  • Node (.ndx)

  • NodeInstance (.nix)

  • Object (.obx)

  • Package (.pkx)

  • Signal (.sgx)

  • StateMachine (.smx)

  • Subsystem (.ssx)

  • UseCase (.ucx)

  • Model (.mdx)

As you can see, the storage units are very low level. You can even add single elements (e.g., an Actor element) to a storage unit (in its own file). This makes your model able to support multiple users, and you can lock parts of your model by adding parts (certain storage units) to a source control project.

XDE supports storage units for the following project types:

  • C# projects

  • A Solution Items project (i.e., a blank solution)

  • VB .NET projects

  • A Miscellaneous Files project

Both XDE and Visio are directly integrated with Microsoft Visual SourceSafe.


UML Version Support

UML is currently at version 1.4, and version 2.0 is about to be released. It's antic ipated that UML version 2.0 will be the "official" new version, and it's expected to be complete in 2004 (please visit http://www.omg.org for up-to-date information on version 2.0's status).

In VEA the models and the code generation engine support UML version 1.2. In XDE the code generation engine supports UML version 1.3. Actually, this dif ference doesn't matter and shouldn't be a factor when you're choosing a UML tool. The differences between UML version 1.2 and 1.3 are minor.

The biggest change from UML 1.2 to UML 1.3 was a reformulation of use case relationships. For example, you learned in Chapter 4 that three kinds of relationships exist in use case diagrams: communicates, uses, and extends. In UML 1.4, the relationships in use case diagrams are slightly different. The new relationships are as follows:

  • Association: This relationship is equivalent to the communicates relationship from UML version 1.2.

  • Extend: This relationship is equal to the extends relationship from UML version 1.2.

  • Generalization: This relationship is new and represents a generalization. In Chapter 4 you used the extends relationship to model this behavior. The generalization concept is explained in Chapter 4 as well.

  • Include: This relationship is equal to the uses relationship from UML version 1.2.

The most important addition in UML 1.4 was the guidelines for writing profiles. UML profiles are packages dedicated to group UML extensions; they don't add any new fundamental concepts. You can create profiles for certain areas such as "Software Development Processes" and have this profile include all the elements and stereotypes necessary for this type of model.

UML version 2.0 is expected to include a major update to the UML specifi cation and promises to streamline the kernel language, increase customizability, and improve support for component-based development methods. UML version 2.0 will most likely incorporate changes in the following areas:

  • UML infrastructure: The internal structure will be reorganized to improve support for extensibility.

  • Object Constraint Language (OCL): OCL is a declarative text language for writing constraints that's used in the UML specification to express the rules for well-formed models. It needs a metamodel of its own (in UML) and additional features to support recent changes to UML.

  • UML superstructure: These are the changes visible to the user. New concepts include architectural structure modeling, component-based development, and adjustments to some of the UML relationships. Some new notation will probably be added as well.

  • Diagram exchange format: The original UML specification defined a meta- model for the semantic model but not for diagram layout. If exchange of diagrams among tools from different vendors is to be possible, a specification is needed.

    Note

    For more information on UML version 2.0 and UML specifications in general, visit the OMG site at http://www.omg.org.


Cost

An issue that you'll definitely need to take into consideration when choosing a UML product is cost. IBM Rational's products have traditionally been quite expensive. Here are the prices for XDE and VSEA, which includes VEA:

  • IBM Rational Rose XDE Developer: US $3,595

  • Visual Studio .NET Enterprise Architect (full package including VEA): US $2,500

    Note

    All prices listed here are according to http://www.objectsbydesign.com/tools/umltools_byPrice.html, are accurate as of March 2004, and are subject to change.

Small organizations or organizations primarily focusing on small, inexpensive projects will likely find it difficult to pay for a couple of IBM Rational XDE licenses. In other organizations where it's common to let the client pay for the licenses, most clients will probably choose the less expensive option, VEA.

We're not implying that price should solely determine which product you choose to use, but we believe in lot of cases that price will be an important issue. Microsoft developers aren't used to paying high license prices (as Oracle and SAP developers are accustomed to doing), so many Microsoft-oriented software companies new to UML might get "sticker shock" from IBM Rational's relatively higher prices.


Manufacturer Support

We can't disregard the fact that VEA, being a Microsoft product, has an advantage in this area. Microsoft has the possibility of being in the lead in VS .NET integration, because the company is in charge of VS .NET as well. Furthermore, there's a ten dency for the products Microsoft produces, over time, to end up with a large market share. (To clarify, this is not the same as saying Microsoft products are always the best products.) With this in mind, it may be a good idea to place your bet on Microsoft, as the company might be the long-term winner (at least among Microsoft developers).

Another advantage VEA has in this area is that Visio terminology, syntax, and notation will probably be built into other Microsoft products (as has been done with Microsoft BizTalk, which actually uses Visio for drawing and modeling). This makes it easy to capitalize on your investment in learning Visio.

IBM Rational's UML products have been on the market for a long time, and they've consistently been updated to comply with the latest UML versions. Both XDE and Rose are products that are here to stay in one form or another, and the fact that they're cross-platform and target programming languages other than Microsoft- endorsed languages (Java, for example) can make them an obvious choice.


Comparing MSF to RUP

Though neither MSF nor RUP is directly included with the two products (VEA and XDE) mentioned in this chapter, we've chosen to include a comparison of the two frameworks in this section because it's an interesting topic that many developers ask questions about. We'll look at the two frameworks and their rele vance to VEA and XDE wherever appropriate, but keep in mind that this information really shouldn't influence your choice of UML software modeling product.

MSF is a Microsoft-developed project management framework (see http://www.microsoft.com/technet/itsolutions/techguide/msf/default.mspx). RUP is MSF's IBM Rational–developed counterpart (see http://www-136.ibm.com/developerworks/rational/products/rup). The two processes (frameworks) have a lot in common, and that's one reason that it doesn't matter whether you use MSF or RUP in conjunction with VEA or XDE.

Note

We describe MSF in further detail in Chapter 20.

One of the most significant differences between the two frameworks relates to overall size. RUP is a much more comprehensive framework than MSF. RUP contains many guidelines, documents, checklists, white papers, and so on. This has been the basis for most of the criticisms of RUP. Critics often point out the following:

  • RUP is harder to learn and adopt in the organization than MSF.

  • RUP is difficult to down-scale because of the number of checklists and guidelines.

  • RUP is in general more time-consuming than MSF, because of the many guidelines, checklists, and so on.

However, just as you can add to MSF, you can also tailor RUP to suit smaller- scale development (see http://www-106.ibm.com/ developerworks/rational/library/354.html for more information).

MSF, on the other hand, is criticized for not being complete for very large projects, because of the lack of many of the guidelines present in other project management methodologies (e.g., guidelines relating to how to plan and manage communication, test, change requests, and so on). Microsoft's answer to the critics is that MSF is a framework, and you should just add these things to MSF when appropriate. In addition, adding too many must-dos to the framework would make it too time-consuming for small projects. Microsoft's aim with MSF was to provide a framework to aid solution providers of distributed systems, as it was recognized that projects usually fail for nontechnical reasons. Microsoft felt that being too prescriptive could interfere with the iterative process, and if a company already has perfectly good standards for change control and so forth, then the company can simply plug these into the MSF framework, with its more generalized nature compared to the stricter traditional methodologies.

We think there's some truth to both criticisms: RUP might be too heavyweight for small organizations and small projects (less than 1,000 hours), and MSF is missing some guidelines for developing very large projects (more than 3,000 hours). Table 19-1 presents a comparison of MSF and RUP.

Table 19-1: MSF and RUP Comparison
Attribute | MSF | RUP
Iterative approach | Yes | Yes
Number of phases | 5 | 4
Initial phase | Envisioning | Inception
Analysis phase | Planning | Elaboration
Development phase | Developing | Construction
Stabilizing phase | Stabilizing | Transition
Deployment phase | Deployment | Transition
Workflow: Business modeling guide | No | Yes
Workflow: Requirements guide | Yes (not detailed) | Yes (detailed)
Workflow: Analysis and design guide | Yes (not detailed) | Yes (detailed)
Workflow: Implementation guide | No | Yes
Workflow: Test guide | No | Yes
Workflow: Deployment guide | No | Yes
Workflow: Change management guide | No | Yes
Workflow: Project management guide | Yes (not detailed) | Yes (detailed)
Workflow: Environment guide | No | Yes
Interview guide | No | Yes
UML usage guide | No | Yes
UML integration | Supported | Built into guides
Risk management | Yes (detailed) | Yes (detailed)
Milestone driven | Yes | Yes
Language independence | Yes | Yes
Trade-off matrix for development strategy choice | Yes | No
Physical product | No, you can only buy courses and books. | Yes, RUP is a product with a collection of white papers, guides, templates, and so on.
Number of team roles | 6 | 5 main roles (31 subroles)
Project manager split into two roles | Yes | No
Scalable | Yes | Yes
Plug-ins to .NET | No | Yes
Web site creation | No | Yes
Price | N/A (courses and books only) | US $695 per license
Customer support | No | Available (1 year included in license price)
Number of templates | None predefined, but approximately 5 to 6 suggested templates | 42 predefined

Our main message here is that both frameworks are excellent for Web and Windows development, with their iterative approaches and business orientation, and, of course, both frameworks support UML. Both Microsoft and IBM Rational like to use their own terminology—for example stabilizing in MSF versus transition in RUP—to make them distinctive, but as you can see from Table 19-1, the life cycle of both frameworks is quite similar.

We'd like to emphasize that RUP is a much larger framework than MSF. In our experience, RUP can be tough to scale to small, fast-changing, Internet-based projects, but we still feel the one you ultimately choose is a matter of personal preference. Many Visual Studio developers aren't used to developing projects using a framework, and for them it will be easier to start off using MSF or at least a defined process.


Summary

In this chapter, we outlined the pros and cons for VEA and XDE. Basically, both products are fine UML tools and sufficient for enterprise development. We've been very cautious not to judge which product is the best (though we are focusing on VEA in this book). You'll have to judge for yourself. Here's a brief summary of the comparisons we made in this chapter:

  • Integration: XDE has the best VS .NET IDE integration, as it's completely integrated with the VS .NET IDE. Unlike VEA, XDE can round-trip–engineer your models, which is a huge advantage.

  • Object model: Both products offer an object model than can be accessed through a COM API.

  • .NET language support: VEA offers better .NET language support, but when it comes to C# and VB .NET, the support is the same.

  • Reporting: Reporting in VEA is poor. XDE is by far the best product in this area.

  • Team development: VEA isn't a team development tool; XDE does support team development.

  • UML version support: VEA currently supports UML version 1.2, and XDE supports UML version 1.3. This really shouldn't influence your decision, though, in our opinion.

  • Cost: VEA is a less expensive product than XDE. That said, XDE gives you ten times more functionality, so the price issue is difficult to compare, though it will certainly be a factor for many decision makers.

  • Manufacturer support: XDE will be around in the coming years. We have our doubts, however, about Visio as a UML modeling tool. While we don't know anything for sure, it seems plausible that Microsoft might have other plans in upcoming versions of VS .NET.

Something else you might take into consideration is that VEA seems to be a bit easier to learn and work with than XDE as far as product complexity goes (in other words, you most likely won't need a VEA local expert, but you might need an XDE local expert). Also, if your organization makes extensive use of use cases, look very carefully at XDE, as it offers considerably more in this area than VEA, such as better support for stereotypes.

Will Microsoft extend VEA to be the preferred UML tool for .NET developers? Will the next VEA version be even better than its IBM Rational counterpart? Will VEA be market leader because of its relatively low cost? We don't know, and we won't even try to guess. We do, however, believe that both products have a future, and that the best choice for you depends on your personal preferences and needs. We will mention that the next version of VS .NET, code named "Whidbey," includes a new modeling framework/platform that's modeling language inde pendent. It's a bit like VS .NET, which is programming language independent, and this means that the framework or platform can be expanded upon using add-ins from third-party ISVs. We gather that Microsoft will continue to support UML in Visio, but the UML modeling capabilities in Whidbey will be much more "complete" and have better integration with the IDE.

In next chapter, we'll dig deeper into MSF, we'll introduce you to the framework's structure, and we'll present some guidelines for how to use the framework professionally.


Part VI: MSF

Chapter List

Chapter 20: Microsoft Solutions Framework 3.0
Appendix: Useful Links and References
Index


Chapter 20: Microsoft Solutions Framework 3.0

Deliver IT Enterprise solutions on schedule, of the right quality, with the right features, and within budget? You can do it!

It's possible to challenge and beat the well-known software paradox that states today's software projects demand faster development with fewer resources and increased functionality requirements. To deal with this demand in a fast changing world, Microsoft has developed a framework for project and solution man agement called the Microsoft Solutions Framework (MSF), and you can find more information about it from Microsoft here:

  • http://www.microsoft.com/technet/itsolutions/techguide/msf/default.mspx

In this chapter, we'll introduce you to MSF. We'll also guide you through the various concepts included in MSF and describe how to use them. This will all be coupled to enterprise development and UML.


About the Microsoft Solutions Framework

MSF is a framework, not a methodology. This is very important to understand, because the whole idea behind MSF builds on this fact. The way Microsoft regards software solution development, and the way we look at it, is that successful projects don't happen through a set of checklists and required tasks. In fact, it's very dan gerous to believe success is secured just because some rules and guidelines are followed. The reasons are, of course, that no two projects are identical in the way they're constructed and that we all live in an ever-changing world. Your way of working must reflect that; if you have a successful project and you do exactly the same things in the next project, you're not guaranteed success.

Note

According to Microsoft philosophy, templates and guidelines don't guarantee project success and should therefore not be developed as must-be-followed items. In fact, templates should be regarded as providing inspiration rather than being mandatory.
Start Sidebar
Project Team vs. Project Process

Many project leads and project managers tend to focus on having the best developers in their team; but without having a good process going for you and your team, your project is more likely to fail than one with a team that starts with members with lesser skills, but has a good process going for them. The process can catch issues such as identifying any developer(s) with a lack of skills, which may then prompt the project or team lead to look for another developer.

We're not saying that you shouldn't look for the best members for your project team, because you should. However, this shouldn't happen in place of creating a good process. A good process, by our definition (and many others), is an instantiation of the MSF Process Model, which means you have your own interpretation of the Process Model suited to your business needs. This will easily catch issues that may occur during a project.

End Sidebar

You should consider MSF a toolbox. You have all the tools to select from when facing a job. Some tools will fit the specific job better than others, but you're not required to use certain tools. You might have some experience and guidelines for what tools to use when, but the choice is yours and yours alone. If you're hanging up a picture on the wall, you'll probably choose to use a nail and a hammer. You could also choose to use a screw and a screwdriver. Which one is the best choice depends on the specific job. If it's a very heavy picture, the screw and screwdriver might be the better choice, but you aren't required to choose the screwdriver. This is exactly the philosophy behind MSF.

Start Sidebar
Missing "Tools"

One question that is often heard when teaching or discussing the "MSF toolbox" is "What if you look at your toolbox, and discover that you don't currently have a tool suited to address a certain requirement or issue?"

Well, the answer to that is "A good process will catch this (risk assessment), and because of the process in place, you can find the tool (risk mitigation) best suited for the job, and come up with alternatives, if there is an issue searching for that tool (contingency)."

We'll be covering this in later sections in this chapter, but we feel it's appropriate to point out at this early stage, to give you an early impression of what MSF is all about.

End Sidebar
Note

According to Microsoft philosophy, you should consider MSF as a toolbox full of tools you can choose from. Think of the tools and guidelines as something you should remember to consider, rather than mandatory to implement.

We really like the philosophy, because it makes it easier to scale a project and use the right tools. This is the opposite of what methodologies do. Methodologies have a set of mandatory guidelines and templates you must follow. After following the guidelines and templates, the project process is a success. We say, "It's not so", and why would it be, if you think about it?

As the name suggests, MSF is made by Microsoft, but this "product" isn't a product for sale or some fancy marketing stunt. In fact, MSF isn't a product at all. Otherwise, it would include templates and mandatory checklists—which would violate the framework philosophy. The development of MSF has taken over 20 years, and consists of all the best practices[1] collected by Microsoft from Microsoft consultants, Microsoft product team developers, and its customers: what really works in a software development process and what doesn't work. Microsoft has continuously collected these best practices and put them all together in what is known today as MSF. We'll get back to the concept of best practices later.

The Best of Both Worlds

Two dominant ways of approaching project processes are

  • The Waterfall Model approach

  • The Rapid Application Development (RAD) approach

In the Waterfall Model shown in Figure 20-1, you step through the phases in chronological order without going back to a phase once it's completed. This approach has the advantage that you always know which phase the project is in and the project team knows exactly what to do in each phase. However, the Waterfall Model has been criticized in that nothing in modern enterprise devel opment can be carried out in separate phases, because the outside world and the requirements are changing too fast. In other words, you can't from day one identify all requirements and design issues, and then develop the solution in a 9-month project process without being able to change the initial design and requirements.

Click To expand
Figure 20-1: The Waterfall Model method
Note

We realize that this approach is somewhat seductive to project managers, because it appears to give a high degree of control. However, in practice a lot of post-implementation rework may be the result.

On the other hand, this is possible in the RAD model, shown in Figure 20-2. In this model, you can go back to design and analysis as many times as necessary during the project process, iterating until you reach the required result. RAD uses milestones as a very strong element. With milestones, the project team has a tool for communicating exactly what the project status is at any time. However, the RAD model has been criticized for the fact that the process isn't controlled, simply because the project team doesn't know which phase the process is in at any given time. This may lead to reduced maintainability and scope creep.

Click To expand
Figure 20-2: The Rapid Application Development method

MSF takes the best aspects of both models and incorporates them into MSF. The phases are taken from the Waterfall Model and the milestones and the iter ative approach are taken from the RAD model. This makes MSF a solid and flexible framework.

Project Failure: Most Projects Are a Failure

A provocative headline for this section, don't you think? Nevertheless, this is very often the truth. Not that the solutions built don't work at all. What we mean is that most projects can't be considered successful if you look at all the success indicators such as budget, schedule, quality, error level, user satisfaction, stake- holder satisfaction, business goals, and vision. In fact, surveys have proven that about 25% of all software projects fail, 25 % succeed, and 50% are challenged.[2] That's not an impressive statistic, is it. So, why is it like this? Well, first you must look at the paradox as we described briefly earlier in this chapter. The project teams face demanding sponsors, customers, and users, insisting on solutions developed faster, with richer functionality, and with limited resources used. All this, in an ever-changing world! Now, this is only half the truth. We as software developers also have to take a look at ourselves and the way projects are most often managed. Actually, project failure is rarely because of technical problems or lousy programmers (do you know any, BTW?). Much too often projects are created without planning and design, and without managing the communications required and risks involved. This is exactly how you can leverage MSF. MSF answers to these challenges are the following:

  • A framework approach instead of a methodology

  • Focusing on processes and the business instead of technology

  • Separation of goal and functionality

  • Separation of business and technology

We've discussed the first point about the framework approach, so let's look at the others now.

Focusing on Processes Instead of Technology

What is more important—building a state-of-the-art solution that doesn't meet the business needs, or building a less fancy solution that meets the business needs? If you can answer this question (if you choose the first option, please don't tell anyone . . .), you can also understand why it's important to separate the processes from technology. What's important is to create a solution that satisfies the cus tomer, satisfies all of the stakeholders, and solves the business goals—nothing more, and nothing less. Actually, it's quite simple. Focus on the processes in the solution. Meet the business goals, and select the right technology. If you choose a technology and force the technology onto the processes, you'll end up with a solution whereby the processes have been manipulated in favor of the technology. This is a design flaw (see more about design flaws in Chapter 2).

Note

According to Microsoft philosophy, you should focus on the processes and the technology separately. You'll end up with design flaws if you focus on both as a single unit, because processes are manipulated to fit a specific technology.

Separating Goal and Functionality

"What functionality do you want us to code?" How often have you heard developers saying that to customers and users? Quite a few times we would think. Even worse, a managing director from the customer company shows up at the first project meeting with a list of features you must develop. This isn't the way to do enterprise development, not at all. You should never mix the goals with the functionality.Who says the features on the list are the features needed to meet the business goals? Who says the features on the list are the optimal features? You don't, because you don't know the business goals, or you've only extracted the business goals from the feature list; but you're the one dealing with a project failure, if the solution doesn't solve the business goals or if it's not usable for the users. Maybe the list isn't even complete. Maybe you can suggest features that the managing director doesn't even know of, if you just know the goals. See the point? Only by separating the goals from the functionality can you develop a solution with the right functionality and meet the goals.

Note

Only by separating the goals from the functionality can you develop a solution that meets the goals and has the right functionality to do so.

Separating Business and Technology

The separation of goals and functionality is about determining the goals for the solution without paying attention to the technology. We described a similar issue in Chapter 2 when discussing the importance of separating design from technology. In that discussion, you saw that interference of technology at that stage can result in a solution with design flaws, because the technology can impose limitations. The very same thing is the issue here. However, this time it's not about design, it's about business. If you let technology interfere with business goals, vision, and processes, you'll end up with solutions satisfying the choice of technology instead of business. As an example, say you have a project involving building an e-commerce solution. If you choose Microsoft BizTalk as the technology initially before knowing if it's a business vision to take advantage of the integration services and other functionality provided by the BizTalk server, you're making a mistake and you're letting technology determine the business visions. This leads to project failure, because of unsatisfied sponsors and stakeholders.

Note

By separating business from technology you ensure that the business strategy isn't determined by technology.

Last of all, we'll just mention that one of the most important strengths of MSF is its ability to give you different perspectives while forming the solution. First the solution is looked at from the users' perspective, then from the project team's perspective, and finally from the developers' perspective. MSF is a framework, specifying what to consider during the project process. It doesn't have any guide lines for how to describe and document the things uncovered in the process— this is where UML comes into the picture. UML provides MSF with a common language to describe and document in a way understandable to all the stakeholders. UML together with MSF's ability to approach a project the right way forms the perfect partnership.

[1]Keep in mind that a best practice in one company might not be a best practice in another company. You must figure out what's best for your organization, although you might start by looking at best practices for other similar organizations.

[2]Among others, the Standish Group International makes such analysis. See for yourself at http://www.standishgroup.com or http://www.standishgroup.com/sample_research/PDFpages/extreme_chaos.pdf.


The Contents of MSF

In this section, we'll outline the content of MSF from a broad perspective and provide you with the structure of MSF. Later we'll dig into the various parts and describe them in detail.

MSF consists of a project life cycle and a collection of models. The models are the real content of MSF, containing the tools you need in your project process. The models are descriptions for what you need to consider, and some sugges tions for output. When we say "suggestions for output," it's because we want to point out that MSF doesn't have any mandatory tasks. However, in real life, you'll discover concepts that are hard to avoid, such as creating a project plan, but the content of the project plan can often vary from project to project.

The project life cycle is an iterative approach of planning, building, and man aging as shown in Figure 20-3. An enhancement from the previous MSF version is that the MSF project life cycle spans from project inception to live deployment— with MSF you have a framework covering the entire project life cycle.

Click To expand
Figure 20-3: The MSF project life cycle

Table 20-1 lists the six models in MSF. The table provides the name of the various models, a short description of each, and the most important output from the models.

Table 20-1: MSF Models
Model | Description | Output
Team Model | Describes how to form a project team and facilitate the communication | Project organization
Process Model | Describes how to manage the project process | Project plan
Application Model | Describes how to divide the solution into layers | n-tier layer object model
Risk Model | Describes how to manage the risks in the project | Risk plan
Enterprise Model | Describes how to gather enterprise- specific information | Enterprise information
Infrastructure Model | Describes how to gather infrastructure information | Infrastructure information

This is basically what MSF consists of. As stated earlier, you can choose what models, model output, and output content are relevant for your individual projects. None of them are mandatory.


Project Life Cycle

The project life cycle is a way of describing the life of a project. A project is born at some point in time, and then it undergoes some development, and at some point in time it dies. Actually, the definition of a project is that it's limited in time and has clear starting and end points. So, what happens from when the project is started until it ends is called the project life cycle. The MSF project life cycle (shown earlier in Figure 20-3) consists of a planning phase, a building phase, anda managing phase.

Planning Phase

The planning phase initiates when the project starts. In the planning phase, the project content is outlined, and the processes for developing the solution are planned. All the requirements are gathered, and vision scope, project plan, risk plan, test plan, and so on are created. Of course, the design of the solution is also created here.

Building Phase

In the building phase, the design determined in the planning phase is developed. Some of the plans made in the planning phase are also carried out in this phase. This can be the risk plan, project plan, test plan, user education plan, and so on.

Managing Phase

In the managing phase, the solution is released, and the managing of the solution begins. This means correcting errors, making changes, handing over the managing of the solution to help desk functions, and so on.

Notice that the project life cycle is iterative, meaning that it's not a step-by- step approach, but instead, as in real life, iterations of the planning, building, and managing phases occur throughout the project life cycle.

The models in MSF, which we'll describe in detail in the next sections, all fit into one or more of the phases. You can look at it this way: The project life cycle is the sequence of phases your project steps through, and the models are the content of the phases. Digging further into the details, you can consider the output as the content of the models.


Models

As briefly described in the previous section, the models in MSF are the content of the project life cycle phases. You shouldn't let the word model confuse you. It simply means that a model is a collection of guidelines and advice for the specific area. Why Microsoft have chosen the word model is hard to say, but it sometimes confuses developers when learning MSF, particularly because we tend to think in terms of UML-style models. MSF consists of six models as outlined previously in Table 20-1. We'll describe the content of each model in detail next.

Team Model

The Team Model, one of the first models to look at when you're new to MSF, deter mines how to establish the right project team, how to delegate responsibility, and how to facilitate communication. That's the content from a wide perspective. Let's first take a look at some of the pitfalls a project team faces in its daily work.

Communication failure: Communication failures are well known in many projects. Questions like "Did we promise this kind of functionality?" and "Has the deadline been postponed; why haven't you told us?" result from communication failures. Communication failures arise because the communication path isn't properly outlined. This means that the client is sometimes communicating directly to the developers and sometimes to the product manager,[3] and nobody communicates the information on to the other team members. You can see the confusion and chaos in front of you, eh?

Responsibility confusion: If the responsibility isn't outlined in written form, it tends to be the subject of confusion and errors. "I thought you were doing the testing" is an example of responsibility confusion. Responsibilities need to be outlined so that every single team member knows who's responsible for what. This goes for decision-making powers as well, and it makes sense to communicate this to the customer. If the customer knows that the only one who has the power to accept changes to the graphical user interface (GUI) is the user experience role,[4] then misunderstandings can be avoided. One example is when the customer thinks a feature has been validated and accepted by a developer, but it doesn't appear in the final solution, because the developer isn't responsible for making such a decision and perhaps agreed that it was indeed possible to implement the request, but not that it should be implemented.

Focus centralization: A project has many areas of focus that need attention, if the project is to succeed. In a project under stress, there is a tendency to focus on the development and testing, and pay less attention to areas such as user enhancements and deployment aspects. This is dangerous, because a project isn't successful if the users[5] aren't satisfied.

Loyalty conflicts: Loyalty conflicts are the most common problem in the project process. These arise when you represent interests from two opposite sides. A mid-level manager can experience loyalty conflicts when taking care of both his employees' interests and the top management's interest. This also happens in projects. The most obvious example is a project manager who takes care of the interests of both the project team and the customer. These interests can be conflicting. Take this real life example: A project manager is in a meeting with the customer and promises to include a certain feature. Back at the company, the rest of the project team is outraged, yelling out loud that there isn't enough time and that the feature is out of scope. Well, this is a real loyalty conflict, because the project manager must take care of both the customer's interests and the project group's interests, and they're conflicting in this case. Loyalty conflicts very often lead to stressful projects, schedule delays, and decreased morale in the project team. External loyalty conflicts tend to produce customer dissatisfaction and lost expectations. You'll see later that this is resolved by not having the traditional single role of project manager in MSF.

MSF solves these pitfalls by dividing the responsibilities, focuses, powers, and loyalty into six distinct roles. The Team Model incorporates the six roles in a project team. Although Microsoft has identified six roles that encompass the responsibilities of a project, those six roles don't have to be assigned to six dis tinct persons. Furthermore, a role cluster can have several persons assigned to it. A person can easily have more than one role, but some roles conflicts with each other. We'll discuss this later. The six roles are as follows

  • Product management

  • Program management

  • Development

  • Test

  • User experience

  • Release management

The roles will be described in detail later in this chapter, but before doing so, we'll first show you what makes a successful project. According to MSF, the following six goals must all be fulfilled for the project to be successful. If even only one goal isn't met, the project can't be considered a success.

Satisfied customer: For the project to be successful, you obviously need the customer to be satisfied. Satisfaction is reached by making sure you deliver what the customer expects.

Delivering within constraints: This means that to be successful you need to deliver within the constraints or boundaries that have been determined for the project. Typical constraints are budget, schedule, features, and quality.

Build to specifications: This means the project is only successful if it's developed according to the specifications outlined in the project plan (described in the "Project Plan" section later in this chapter), feature list, and technical specification (in MSF the technical specification includes the conceptual, logical, and physical design models, among other information). If you don't meet this goal, the solution isn't developed the way it was designed to be, and must therefore be considered unsuccessful.

Approve for release after addressing all known issues: The project is only successful if it isn't released before all known issues are addressed. This doesn't mean that you can't release a solution with errors (MS often releases products with a list of known bugs or issues). But you have to take care of every problem or issue and decide what to do with it. Microsoft has a philosophy that in X lines of code a developer makes Y number of issues, and if X lines of code is debugged, it generates Y number of new issues. These new issues might not be known. This is the reason why Microsoft would rather ship a product with issues that they know about and know how to work around, instead of correcting them at the last minute and risk generating new unknown issues. Between you and us, another reason is that Microsoft often has a first-to-market strategy and won't keep testing and debugging for too long. Don't expect Microsoft to confirm this . . .

Enhanced user effectiveness: The project isn't successful if the users aren't satisfied. Therefore the solution must be usable, fulfill users' expectations, and be beneficial to users. This goal is responsible for technical communications, training, usability, graphic design, internationalization, and accessibility.

Smooth deployment and ongoing operations: The last goal is a bit fluffy and often overlooked by project teams, but it's still an important goal. Your project is only successful if the deployment is smooth (otherwise it'll also violate the project constraint schedule) and from then on the solution is continuously managed. The last item means that your solution must be tracked and changes applied to be successful.

Funnily enough, exactly six MSF goals exist, and they each relate to one specific role cluster.[6] Let's take a closer look at those roles and see how the goals apply.

Product Management Role

The old project manager role as you might know it has been split up into two dif ferent roles, the product management role and the program management role. The most important reason for this is that a project manager is by nature in a loyalty conflict, as described in the in the "Team Model" section earlier in this chapter. The project manager must take care of the customer interests and the project team's interests, which conflicts in many cases. MSF has therefore split the project manager role into two distinct roles. The product management role is the one focusing on the customer's interests. The purpose of the product manager is to be the customer's advocate when dealing with the project team. It's the product manager who has the contact with the customer, and he or she carries the cus tomer's voice back to the project team. It almost sounds like the project team isn't talking to the customer at all. This can also be true. It's very sensible to only have the product manager communicate directly with the customer and write down the communication in the project plan. Of course, the other team members can still participate in meetings with the customer, but the product manager is always involved. The advantage of having the product management role is that the loyalty conflict is solved. Another advantage is that you can choose a person who's good at talking to customers (because of their business knowledge) to be the product management without fearing that this person lacks the skills for managing the project process, because this is done by the program manager.

The Goal of the Product Management Role

The goal for the product manager can be expressed in just two words: "satisfied customer." This is the overall goal, which is accomplished by being the customer advocate within your team. Of course, the product manager isn't just the customer's representative; he's also the team's advocate when dealing with the customer. More importantly, the goal "satisfied customer" is achieved by managing cus tomer expectations. For example, one customer expectation is to receive the product on time and on budget. The job for the product manager is then to manage the customer expectations so the solution delivered is what's expected. If the cus tomer expects a Ferrari, but you deliver a Ford, something has gone terribly wrong in the communication, and the expectations haven't been managed very well. Expectations are everything related to the solution, such as features, quality, ease of use, and so on. It's important to determine the expectation parameters and manage the expectations. Of course, MSF has ways of doing this, and we'll talk about that later in the "Tradeoff Matrix" section. For now, just remember that the goal of the product manager is to have a satisfied customer.

Product Management Responsibility

By now you've seen that the product manager's goal is to have a satisfied customer. The responsibilities are tied tightly to this goal. The product manager is respon sible for the customer being heard in the process, so the expectations, which sometimes change, can be managed. This role is also responsible for a part of the process. The product manager is usually the first person involved in a new project, perhaps at an initial customer meeting, so he or she is responsible for starting the project right by gathering information for the vision scope document, which we'll discuss in the "Vision Scope Document" section later in this chapter. The product manager is also responsible for collecting change requests from the customer and dealing with these in cooperation with the project team.

Note

The product manager's goal is a satisfied customer. The product manager is the advocate between the customer and the project team. The focus is with the customer.

Program Management Role

The program manager is the other role created by splitting up the old project manager role into two distinct ones. The product manager has the external focus with the customer, and the program manager has the internal focus with the project team. The program management role is more like the old project manager role. It's the program manager who's managing the daily project process with the project team, managing GANTT charts (schedule charts), status, milestones, resources, and so on. The program manager is also the initial driver for devel oping the solution architecture with UML![7] An important thing to keep in mind is that no boss exists in MSF: Not even the program manager is a boss. This is very different from the traditional project manager role in which the project manager has a certain level of power and competences. In MSF there are no bosses—in the sense that no one can rule the other project team members. Consensus has to be obtained, meaning that the program manager isn't the boss, but merely the facil itator, administrator, or coordinator. This is somewhat unlike real-life situations, where conflicts must be resolved by the superior senior manager in your company. In our experience, it's important that all people involved in the project under stand this; otherwise you'll quickly return to using the old project manager role and won't benefit from the MSF concepts. The purpose of the program man agement role is to act as a coordinator and administrator for the project team.

The Goal of the Program Management Role

The program manager controls the project process, and the goal is to deliver the solution within the constraints, which are stated in the project plan.

Program Management Responsibilities

As the goal suggests, it's the program manager who's responsible for delivering the project within the constraints. The constraints can be schedule, budget, resources, solution features, project scope, and so on. The program manager is also responsible for being the driving force in the overall project plan development. Finally, it's the program manager's responsibility to ensure that a signed-off vision scope document exists (as discussed later in this chapter) before starting the project plan development process. The project manager must also ensure the project plan has been approved before development is started. It's our expe rience that this is where the debutante MSF projects always fail. It's extremely important to obtain these sign-offs before continuing to the next step. Otherwise, you'll end up arguing about things you took for granted when it's too late to change them without wasting a lot of time and money. This makes your project fail, because you then can't deliver within the constraints. Always make sure you have the sign-offs!

Development Role

The development role is the easiest role to explain. If you're a developer, you might have a good idea about what the developer in a project is doing and what responsibilities are involved. As the name suggests the developers are those developing the solution, writing the lines of code, building the solution with components. Of course, in real-life situations the developers also participate in the design, especially when creating the physical design. Another area where the developers participate is in estimating the project. A rule of thumb is that only those actually developing a task can estimate it.

The Goal of the Development Role

The goal of the development role is to build to specifications. All the specifica tions are outlined in the project plan and the functional specification. These specifications are made on the basis of the requirements from the users and stakeholders, and described using UML. We talked about this in Chapter 2. Another important goal of the development role is bottom-up estimating. MSF favors bottom-up estimating: Those who are going to develop the parts are those estimating them in the first place. Furthermore, the development role is the key driver of the logical and physical design with UML.

Development Responsibility

The responsibility is, of course, to produce lines of code and develop according to the specifications, and ensure that the code is tested. However, this doesn't mean the developer also falls into the role of tester. The developer only delivers code to the project when it has been tested by the developer and found to be without errors. This is where unit testing comes in handy.

Test Role

The test role is very interesting and one of the key roles when ensuring quality. The test role is to make sure the solution is tested and issues are addressed. In other words, the tester should approve code for release only after all product quality issues are identified and addressed. It doesn't mean that the tester is the (only) one performing the test, but he or she is responsible for ensuring the test is performed.

The Goal of the Test Role

The goal of the test role is to approve the solution for release after addressing all known issues. This means that the tester must uncover all issues, such as errors or missing functionality, and address those issues either by correcting them, deleting features, or creating work-arounds and making sure that these work- arounds are documented.

Test Responsibility

The tester is responsible for the creation of the test packages, which are nothing more than simple guidelines for how to test the solution.[8] The tester is also responsible for performing the test using the test packages, keeping in mind that it doesn't have to be the tester that performs the actual testing. The tester is responsible for disallowing the release of the solution until all issues are known and have been addressed.

If the project has exceeded the deadline by, say, 4 weeks and the developers have been working, say, 3 nights in a row to produce the final lines of code, it's the tester's responsibility to postpone the release, because all of the issues in the solution aren't known or the quality standard hasn't been met. This means that the solution hasn't been thoroughly tested and/or that not all the issues have been addressed.

Think of this in terms of limbo dancing[9]: It's the tester who holds the limbo stick, and the height of the stick represents the quality requirement of the solution. If the solution isn't capable of passing under the stick, it's the tester's responsibility to disallow the release of the solution. This way you make sure your organization isn't releasing a product of poor quality. A reputation of releasing poor quality solutions can quickly ruin your company, so you should take this issue very seriously. There are numerous examples of software companies going bust because of this and other related problems. Now, we won't be mentioning any names here for legal reasons, but if you think about this carefully, we're sure you know of at least one company that has gone bust over the last decade or so for this reason.

User Experience Role

The user experience role is often overlooked in projects. This is a real shame, because the success of the project depends on user satisfaction and user enhancements in many ways. Just as you need a person to be the advocate between the customer and the project team, you also need an advocate between the users and the project team to be successful. That's the user experience role. If you don't have that advocate, the focus in the project is often on the customer and the functional specification. But the user's world also evolves during a project's life, with changed expectations, requirements, and needs. This has to be taken into account; otherwise you won't be able to deliver a solution satisfactory to the users, and this will lead to an unsuccessful solution. The purpose of the user experience role is to make the users heard in the project development process. You can think of this in the broadest perspective. The users' voice must be heard, not only regarding require ments but also regarding issues such as system usage training needs, system usability, help issues, and so on.

The Goal of the User Experience Role

The goal of the user experience role is "Enhanced user effectiveness," or in other words, the goal is user satisfaction and beneficence. Not only do you need satisfied users, but you also need a solution that's actually beneficial to the users, making their everyday life a bit easier and/or a bit more efficient. The user experience role is very often involved when discussing user requirements in the design process of the planning phase. Examples of what the user experience role will manage are technical communications, training, usability, graphic design, internationalization, and accessibility. Basically everything involving the user or enhancing the user experience lies within the boundaries of the user experience role.

User Experience Responsibility

The user experience role has the responsibility of being the users' advocate on the team and making sure user focus is a part of the solution. The user experience role has the responsibility of making sure the solution is user friendly, usable, and satisfactory to the user. This role is also responsible for the creation of user manuals and help functionality according to plan. Like the test role, this doesn't mean that the user experience role must perform all these tasks, but the person assigned to this role is responsible for it being done.

Release Management Role

The last role in the MSF Team Model is the release management role. This role is often overlooked and sometimes entirely left out. However, it's important to have this role, especially when you're developing enterprise solutions. The person(s) in this role concentrates on the deployment, and acts as an advocate between the deployment department (system administrators and the like) and the project team. Deployment has to be planned and managed. If not, you can end up hearing something like "We want to go live today, but the system management people says this can't be done until next week." You've probably heard something similar in one or more of your projects. The reason is that way too often, project teams don't pay attention to the deployment issue until the very last minute. This often meets resistance from the system management people who are dealing with the deployment. That's why this role is important.

The Goal of the Release Management Role

The goal of the release management role is to ensure smooth deployment and facilitate an ongoing management of the solution. Smooth deployment is about making deployment plans and making sure the solution is deployable. Ongoing management, however, is just as important. This is about applying changes and making sure the solution is functioning in a satisfactory manner. This includes instance monitoring of the system. Over time the solution might need to scale and acquire additional memory, servers, or similar improvements. We cover deployment in Chapter 15.

Start Sidebar
Security Management

As part of release management, it's important to monitor any security issues. Making secure solutions isn't a one-off task, it's an ongoing process. You constantly need to monitor the security issues, and it's advisable to have a plan for this too. Why is that? Well, security is challenged over time. Suddenly a new security leak is discovered in the software you're using, like Internet Information Services (IIS), and you need a patch or upgrade to fix the leak. You must also be aware of unauthorized access attempts. A good way of monitoring this is by tracking all access attempts in a log file, which you must analyze at a regular interval. One popular way of getting unauthorized access to a system is for the intruder to add his or her account to the administrators group, so be aware of changes to the administrators group (we're talking Windows NT security here). Another well- known way of getting unauthorized access is to simply "guess" a logon/password combination. Be aware of continuous failed logon attempts, as these might and quite often do indicate that something's wrong.

End Sidebar
Release Management Responsibility

The responsibilities of the release management role include preparing deployment plans and making sure these are followed. Again, like the other roles, this doesn't mean that the person in the release management role performs these tasks, but he or she ensures that it's done. Another responsibility of the release management role is to train the help desk staff, prepare a help desk for the solution, and tell them how to support it. Finally, the release management role is responsible for providing support for the solution while it's in beta.

Roles and Goals

You've now been introduced to the six role clusters in the Team Model and how they collaborate. You've also been introduced to the six goals in the Team Model, all having to be fulfilled in order for the project to be successful. In Table 20-2, you can see the roles and their corresponding goals.

Table 20-2: Team Model Roles and Corresponding Goals
Role | Goal
Product management | Satisfied customer
Program management | Delivery within project constraints
Development | Build to specifications
Test | Approve for release only after all product quality issues are identified and addressed
User experience | Enhanced user effectiveness
Release management | Smooth deployment and ongoing operations

Conflicting Roles

We mentioned earlier that having six roles doesn't mean that the project team must consist of at least six people—not at all. In fact, in most small projects, the number of team members is likely to be four. So a person can have more than one role, but as you might have noticed, some of the roles conflict and therefore can't be managed by the very same person.[10] This is true for the product management and the program management roles. We argued that the reason for having these two new roles instead of the old project manager role is that a conflict between customer interests and project team interests exists. So, with this in mind, these two roles can't be carried out by the same person. Another conflict is between the development and the tester. Yes, this is true. Remember how we described the test role: how the tester controls the "limbo dance" to ensure nothing's released if it doesn't fulfill your quality requirements? If the person with the developer role also has the tester role too, conflicts will most certainly arise. On the one hand, the quality requirements have to be fulfilled, and on the other hand, the developer wants to release the solution as quickly as possible.

Did you wonder why we use the word team instead of project group? It's on purpose, and in fact the distinction represents an important issue. We have two reasons for doing so: In the MSF terminology, no team member or role is more important than another. The product management role or program management role is by no means more important in the team than, for instance, the test role or the user experience role. The reason is that all the goals of the various roles have to be fulfilled in order to consider the project a success. All the goals relate to a specific role, therefore all the roles are equally important in relation to project success. Of course, the roles imply different competencies and responsibilities, but that doesn't change the fact that all roles are equally important. Another reason is that the MSF Team Model advocates team consensus. Microsoft believes that the best decisions are made in consensus with the participation of all team members. This gives you the best decisions and provides buy-in and motivation behind the decision. MSF doesn't believe in the old project group way of working, whereby a project manager is a formal leader who manages the project members. If you want buy-in to decisions and highly motivated team members, then they must be part of the decision process. We once participated in a project with unre alistic time frames for the programmers, set by the project manager without any programmer involvement. The deadline was exceeded by several weeks. The developers' answer to this was "We told you so." This is an example of low moti vation and low buy-in because of little or no decision involvement.

Team Model Summary

You've now been introduced to the Team Model. The Team Model is one of the six models used as tools in MSF, and it provides you with a set of guidelines for how to organize a project team. In the MSF philosophy, six role clusters exist in a project. These role clusters are the product management role, the program management role, the development role, the test role, the user experience role, and the release management role. Overall project success is obtained through fulfillment of six distinct goals, each equally important. The goals to fulfill are satisfying the customer, delivery within project constraints, building to specifications, enhancing user effectiveness, approving for release only after all product quality issues are iden tified and addressed, and ensuring smooth deployment and ongoing operations. Each role is responsible for one specific goal. This way project success can be controlled. An important issue in the MSF Team Model is that each role is equally important, and no team member is superior to any other team member. The mantra is consensus.

We've used MSF and the Team Model in several projects, and we must say that it's absolutely beneficial to the project process. We've outlined some advice based on our experience for getting the full benefit from the Team Model:

The team makes all decisions: The team should make all decisions based on a consensus. If a product manager is asked by the customer at a meeting whether the deadline can still be met even though a feature is added, he or she should always discuss it with the team before giving an answer that can't be changed. This is also an example of managing customer expectations.

Never compromise by skipping sign-offs: This is, from our experience, one of the most critical issues. You have a thoroughly tested framework and all the right approaches, but if you don't make sure to get the sign- offs, you can't control anything anyway. Trust us on this one; we've seen it many times. You should never accept continuing with the project plan and project process without a signed-off vision scope document. Stand firm on this, and get the sign-offs.

Always involve all team members in the estimating process: To get a motivated team with buy-in to the project, estimates should always involve those participating in the development through a bottom-up approach.

Only the team can change constraints: Many projects have been damaged when a project manager or a sponsor alone is allowed to change the project constraints, like the schedule, without involving the project team.

The team is a group and should be treated as such: The management should realize that the team is a group. No single team member should be rewarded separately. If the project is a success, it's not because of an excellent program manager, but because of an excellent team. If management doesn't realize this, they risk damaging the team spirit and morale.

Success and failure is every team member's responsibility: Even though each role has one specific goal, it's very wrong to think that as long as the goal of your role is accomplished, you're happy. If the project is a success, the entire team is a success. If the project fails, the entire team has failed. It's as simple as that.

All decisions should be written down: Believe us—suddenly you'll be challenged on issues you thought had already been agreed on. If you don't have any documentation, you're in trouble. Always remember to have written minutes of meetings, and always save your e-mails. A nice little trick when agreeing on something in a discussion is to confirm it in an e-mail exchange.

Create a project diary: This is a strange thing to suggest isn't it? But by doing this, just a few lines each day, you have documentation for the process. You might find yourself in a situation where it's nice to be able to document why the process has been like it has—for instance, which delays were caused by customer delays. A Web log can be used for this purpose.

Process Model

The Process Model is the model used to manage the project and the project process. It can be compared to the other project management methods that exist, such as the Waterfall Model,[11] the Rational Unified Process (http://www-306.ibm.com/software/awdtools/rup/), the RAD method, and others. Just keep in mind that the Process Model also follows the MSF principle that it's a framework and not a step-by-step guideline that must be followed. Even though MSF doesn't dictate you use a set of rules about how to manage the process, you should consider achieving consensus on everything without wasting a huge amount of team time. Use intranet posting and e-mail confirmation for communicating and agreeing uncontroversial issues. Have flash meetings for anything major or even a daily face-to-face team roundup—but limit the time on them, if you do follow these guidelines.

In the beginning of this chapter, you saw that the project life cycle was a con tinuous iteration of planning, building, and managing, which may lead to several versioned releases of the solution. The Process Model is a model for how to handle the process, and it therefore covers all three steps of the project life cycle. The Process Model consists of the following five phases, and these phases cover the entire project life cycle:

  • The envisioning phase

  • The planning phase

  • The developing phase

  • The stabilizing phase

  • The deploying phase

Because the Process Model is an iterative model, the phases overlap each other, and you don't complete all the work in one phase before moving on to the next phase, like you do in the Waterfall Model. The five phases are all phases that you have to step through when developing a project. No matter how small or complex the project is, you always have to step through these phases. What differs is the effort you put into each phase. The Process Model is the MSF model with the largest output, which we'll describe in detail when discussing the phases. At the beginning of the chapter, we also explained to you that the Process Model is made up of the best traits of the Waterfall Model and the RAD method. This means that besides phases, which are a characteristic from the Waterfall Model, the Process Model also has milestones, which are a characteristic of the RAD method. In fact, for each phase, an overall milestone exists, as shown in Figure 20-4, and a number of interim milestones exist within the phases, but the overall milestones are the most important and should always be included in a project.

Click To expand
Figure 20-4: The Process Model

As you can see, the Process Model is the overall model. Therefore strong relations exist between it and the other MSF models. Other Process Model char acteristics are as follows:

Each milestone has a specific role as the driver:

The Process Model is tightly related to the Team Model. In the Team Model, six roles exist, each responsible for fulfilling one of the six goals, making a project successful. The relationship to the Team Model is visible when looking at the major milestones. Each major milestone has a relationship to one or two roles that are driving the process. Here you can see which roles are driving which major milestones.

  • Vision scope approved: Product management role

  • Project plan approved: Program management role

  • Scope complete: Development and user experience roles

  • Release Readiness approved: Test and release management roles

  • Deployment: Release management role

Living documents—early baseline, late freeze:

Another strength of the way the Process Model is structured is that it focuses on an early baseline with a late freeze. In other words, this means that in the process you very quickly get a baseline for what you're analyzing. When creating the design, you very quickly get to the point of having a baseline for the design. A baseline isn't a complete unit of output, but output that needs further refinement. However, you can go to the next step and come back later to refine the baseline. Not until the very last minute, before using the output, do you freeze it—that is, no more changes or refinements are done.

After freezing the design, the developers complete the code and prepare the solution for release. This concept is known as creating living documents, because you operate with baselines, which are continuously refined. This is a strength, because you have the possibility of incorporating changes and refining the baseline for a period of time, making the solution reflect changes until very late in the process. You also avoid analysis paralysis: You keep analyzing for too long in order for (perhaps unnecessary) details to be perfect. The consequence is often exceeded deadlines. Customers usually prefer an application with core working functionality that is delivered on time rather than waiting for a "perfect" solution.

Versioned releases:

Versioned releases don't refer to the iterative approach, but to the development strategy. When developing enterprise solutions, you might be faced with a very complex solution and a huge number of lines of code. It's advisable to approach the development process like you would eating an elephant:[12] You eat one slice at a time. In MSF language, the strategy is to divide the development of the solution into independent pieces, or versioned releases. The reason for this is quite obvious: It simplifies the development process and keeps the team focus on a small piece of the solution.

The real benefit lies in the testing situations. If you develop an entire enter prise solution in one step, you end up with a huge solution that you need to test after everything has been developed. This is like building a huge tower and testing the stability after everything has been built. If something turns out to be unstable, it's hard to determine the cause. Is it because of errors in the last set of bricks laid? Is it because of a bad foundation? And what happens if we re-lay the blocks in the middle, will other parts be affected? These questions will also arise if building everything before testing when developing enterprise solutions.

That's why it's important to use the versioned release strategy. Divide the solution into at least four separate independent versioned releases.[13] Consider each version as a separate solution with its own testing, error correction, and release tasks. By doing this, you'll get small pieces of code that are easy to test and easy to correct, instead of a huge solution that will entail a very long time to test and debug. When dividing the solution into versions, make the first version the core product, and then build the following versions starting with the most important features (related to the business goals!). We've noticed that people often misun derstand the versioned release strategy. It doesn't necessarily mean that the solution is physically released with each versioned release—by no means. However, it's still important to use the versioned release approach, with or without actually releasing the versions to the customers. A key point to keep in mind when making versioned releases is to not start developing the next version before the current version has been tested, debugged, and accepted by the customer with a sign-off.

Project tradeoff:

The last key strength of the MSF Process Model we want to point out is the project tradeoff. The project tradeoff principle is directly related to our subtitle for this chapter: "Deliver IT Enterprise solutions on schedule, of the right quality, with the right features, and within budget? You can do it!" That's what the project tradeoff is all about.

In most projects, the customer demands the most extensive solution, made in a minimum of time, with a minimum of resources, and that's mission impossible. The MSF Process Model provides you with a tool to start a conversation with the customer about this paradox, shown in Figure 20-5. The triangle illustrates the rule that if you change one condition (one side of the triangle), the other conditions (sides) change as well. Using this tool, you can make clear that the customer will have to choose what to optimize, he or she can't have it all.

Figure 20-5: The project tradeoff (devil's) triangle

The tradeoff triangle has a fourth, hidden, dimension: quality. You should consider quality as a variable as well. Most people don't include it, as it's normally assumed quality can't be compromised. Actually, you can consider the triangle a tetrahedron like a pyramid, with the height representing the quality bar.

Another tool is the tradeoff matrix. The concept of the tradeoff matrix is similar to the project tradeoff triangle. The customer needs to decide whether the devel opment strategy is limited budget, richness in features, or fast to market. The most important thing to say about project tradeoff is that in MSF the focus is on the business and business goals, not on features and technology. This means that you decide with the customer what to trade off in case of changes in the solution, like when new laws force you to make changes to your solution. If you've chosen features as tradeoff objects, you simply remove features from your solution, if the project constraints are threatened, starting with the least important feature and so forth.[14] Why can you allow this? Well, as long as you still fulfill the business goals and business processes, you just need to meet the project constraints to be successful. Using this approach, you too can deliver projects on time, of the right quality, and with the right features, and meet all the expectations. Success is now achievable. The concept of the project tradeoff will be explained in detail later in the "Tradeoff Matrix" section.

Envisioning

The first phase in the Process Model is the envisioning phase. This is where you start envisioning what the project and solution is all about. If you refer to the project life cycle, envisioning is part of the planning phase. Consider the envi sioning phase as the phase where you determine what it is you're going to build and why. After doing this, you'll plan how to actually build it in the planning phase of the Process Model.

So what is it you envision in this phase? Initially you envision what you're going to develop and why. You also find out what the overall goals and triggers are for the project. In fact, what the envisioning phase is all about is gathering the high-level requirements for the project. This is a crucial step in project devel opment. You need to know what to create and why, what its purpose is, and what success indicators exist. If you don't have all this information, it's impossible to have a successful project. It's like running to win a race without knowing where the goal line is, or if success is at all dependent on being the fastest. Imagine you're going to build a car for us. If that's the only thing you know about the project, you're in deep trouble. For example, you don't know if we expect a high-quality car or a cheap car. You don't even know what we're going to use the car for. Maybe we're going to participate in Indianapolis 500; maybe we need a car to use for the harvest. Can you see the point? If you don't know all these things, you can't design the right car. This too goes for software projects.

Tip

The envisioning phase is where you gather the overall requirements and goals for the project.

During the envisioning phase, the project team gets a clear understanding of what's going to be developed, and this forms the basis for future planning. Another key thing to uncover is the stakeholders' success parameters for the project. This is basically what the envisioning phase is all about. It ends with completing the vision scope approved milestone. The major output, the vision scope document, is explained in detail in the next section. Other outputs are a risk assessment and a project structure document.

Note

The major output from the envisioning phase is a vision scope document, and the phase ends with the completed milestone vision scope approved.

Vision Scope Document

In this section, we'll introduce you to the contents of the vision scope document. For each item, we'll explain what it contains and what its purpose is. We'll also give you some examples and advice from our experience. Finally, we'll add some additional items to the vision scope that have proven very valuable in some of the projects we've participated in. We'll make sure to point out if some of those items aren't directly part of MSF vision scope. Table 20-3 outlines the content in the vision scope document.

Table 20-3: Vision Scope Document Content
Name | MSF Origin
Problem statement | Yes
Vision statement | Yes
Business goals | Yes
Design goals | Yes
Solution concept | Yes
Risks | No
Project team | No
Planning deliverables | No
Development strategy | No
User profiles | No
Schedule and budget | No
Revision history | No
Sign-off | Yes
Problem Statement

What do you want to solve—what triggered the project?

The first information in the vision scope document is the problem statement. The problem statement outlines why you want to create a project. This can be regarded as background information, but it can be very valuable. It can provide the project team with a clear understanding of the reason for the project, and what the objectives of the project are. It can also force the customer to talk about the project in a more objective way, considering why the project has to be created.

This is important because the MSF approach is business focused and not technology focused. Technology focus is often the first thing a customer can remember— "We too need a Web site"—but for what reason? That's the important part, and the problem statement helps you focus on the business. One way of digging around for this is to ask what prompted the project at the initial customer meeting. The answer often involves some kind of problem that the customer experiences, like declining sales. When you know what the problem statement is, it's easier to have the same understanding of the project as the customer, and you can help him or her define the goals and objectives. Here's an example of a short problem statement:

We have experienced declining sales recently because our competitors are selling directly to the customer through other sales channels like the Internet:To keep up with the competitors, we need to be present in sales channels other than the traditional one.

By looking at the sample problem statement, you can see that we focus on the problem or the things that have triggered the project initiation. We don't focus on the technology, and we don't point out that a reason could be that it's exciting to be present on the Internet. By knowing this problem statement, the project team is better suited to help with identifying goals and strategies.

Vision Statement

What is the vision—in what direction do you want to go?

The vision statement is the overall vision for the project and the solution as such. If you're going to build some kind of Web site as indicated in the problem statement, you need to know the vision for the solution. Otherwise, you can't be sure to make the right design, or choose the right development strategy or goals. If the customer's company is a bookstore, you need to know its vision for the solution. One vision can be to become the dominant online bookstore in the world with the richest features, whereas another vision can be to be the dominant online bookstore for a niche book category; a third vision can be to be present on the Internet at the lowest cost, enabling your customer to use the Internet as an additional sales channel. As you might have guessed, these different visions will require very dif ferent goals, strategies, and designs. That's why the vision statement is so important. Another function of the vision statement is that it gives the involved parties a common understanding of where they're heading, and they can make this knowledge influence their work and ideas. When the developers are stuck in the middle of the night and have lost the overview of the project, the vision must be clear enough to help them focus on the task and know why they are developing the project. The vision statement is the overall long-term goal.

Making a good vision statement isn't as easy as it may seem. However, a few rules of thumb exist. The vision statement must be understandable, short, and easy to remember. It must also be realistic. Nobody wants to go for a goal that isn't even remotely realistic. It's also a good idea to make the vision statement time based. This way you have a clear goal and a time frame. An example of a good vision statement is when John F. Kennedy in the sixties said something like

In this decade we'll have a man on the moon.

This example is both short, easy to remember, time based (in this decade), and realistic (well, it turned out to be). This single vision statement helped all organi zations and parties involved in the process stay focused and aim for the same target. You need the same benefits in your project.

Continuing with the online bookstore example from the problem statement, a good vision statement might be as follows:

This year we'll be the dominant online bookstore in the U.S: for selling pet books.

Notice that we keep using the future form in the vision statements. This makes the vision statement more relevant than a formulation of something we would like to have, within a specified time frame. You should write your vision statements in present form too, and you should also notice we've made the vision statement example geographically specific. This is also a good idea in order to specify the ambitions.

Business Goals

What you want to achieve in the project—what benefits will the business gain?

The present project is just one step on the way to fulfilling the vision as stated in the vision statement. The business goals are the goals of the business for the specific project you're dealing with. In Chapter 2 you saw that besides fulfilling the user requirements and expectations, the solution has to be beneficial to the business. You also need to know what the goals are, what the business sees as beneficial, before you can design the solution. If the goals are to increase profit, you'll design the solution differently than if the goals are simply to brand the company. Follow the point? You design the solution to fulfill the business goals with the vision statement as the overall guiding factor. Speaking of the vision statement, it's important that the business goals are in sync with this statement. The project might just be a single step on the road to reaching the vision. If the vision is to be the dominant online bookstore in a specific market segment, you'll have business goals in the project that help you achieve that. Examples of business goals can then be as follows:

  • Increase sales by 20% through the new Internet sales channel.

  • Become the market leader in the online pet books market, measured in unique hits on the Web site.

By defining the business goals, you know what to obtain in order to make a successful project; you also get a base for making a return-on-investment (ROI) analysis. The acronym SMART, which stands for Specific, Measurable, Achievable, Realistic, and Timely, is often used when validating goals.

A popular thing to do when specifying business goals is also to specify non- business goals. By doing that, you're nailing down the scope even more. One nonbusiness goal can be "The solution isn't multilingual." This is the same as a scope constraint.

Design Goals

What do you develop to reach the business goals?

The design goals are the goals for how you fulfill the business goals. MSF focuses on the business, so all you do is related to the business goals. The design goals are the foundation of the design process in which you specify, in detail, how the solution must be designed. For each business goal, the process is to specify one or more design goals at a high level. The business goal "increase sales by 20% through the new Internet sales channel" can lead to the following design goals:

  • Develop an e-commerce Web site with all books from our catalog available.

  • Create a solution for book searching from third-party Web sites.

It's a good idea to give each business goal a unique number, and in each design goal to specify which business goal number it relates to. That way you make sure that all business goals have related design goals, but you also clarify in your vision scope document that the focus is on the business goals, and every thing is related to the business goals.

Solution Concept

Outline the concept for the solution.

The solution concept involves making an outline for how the solution must be developed, still from a wide perspective. Later on in the design process, the solution concept will be used as the foundation and will be transformed into a specific design. You specify the solution concept in nontechnical terms. If technology choices are made too early, it can result in design flaws. The solution concept can consist of features and a solution outline. You should consider the solution concept as an early scope definition for the solution. Here is an example of a solution concept:

  • E-commerce Web site allows credit card purchases.

  • Catalog searches can be done by ISBN, author, or title.

  • Book purchasing.

  • User has choice of shipping method.

  • Display book details and front cover.

  • Online help is available.

  • Contact information is available for customers.

  • Users can get a logon and specify default purchase information.

  • The solution supports 10,000 users and at least 100 concurrent users.

Risk Statement

Specify the risks the customer faces.

This section wasn't originally part of the vision scope document, but we feel it should be included in some circumstances. The risk assessment is an internal document that the customer mustn't be made aware of, partly because not all risks will be acceptable to the customer. However, in some projects, we feel that if the customer insists on including issues that we've argued not to include, and that we've agreed on is a risk the customer deals with, this section should be pro vided. The risk statement in the vision scope includes all the risks the customer faces, such as these examples:

  • Deploying on a platform installed with a beta product.

  • By extending the existing system, the development effort needed may increase.

  • The project meets resistance in the customer organization.

By specifying customer risks in the vision scope document, you clarify to the customer that he or she also faces some risks, and you can later document this.

Project Team

Specify the project organization.

Specifying the project team or project organization in the vision scope document isn't directly a part of the original approach advocated by Microsoft. Sometimes the envisioning phase can be quite long and complex, like when it's uncertain what the project must deliver. In such situations, you might find it beneficial to have a clear project organization described in the vision scope document. It helps you clarify communication and competence issues, and you'll more officially have the resources granted.

Planning Deliverables

Describe what deliverables must be made.

This wasn't originally included in MSF vision scope, but it can be very helpful in the project process. If you're developing a project in which the envisioning phase is very complex and time consuming, it can be a good idea to outline what the deliverables from the envisioning phase are to manage the expectations. You might choose to make competitor analysis, current system state analysis, market analysis, or some other analysis in the envisioning phase, if the project is complex. It's a good idea to outline this up-front for the customer. This way you can manage the process and expectations and specify when you need participation from the customer or customer organization.

Development Strategy

Specify the development strategy and identify the tradeoff objectives.

Development strategy was originally not a part of the vision scope document, but a part of the project plan document. In real life, it's a good idea to start talking about tradeoffs and decide the development strategy in the envisioning phase, because you have to manage the customer expectations right from the start. The development strategy and tradeoffs will be described in detail when we talk about the planning phase.

User Profiles

Determine the characteristics of the users who'll be using the solution.

This wasn't originally part of the vision scope document, but only part of the project plan document. In this section, you describe high-level characteristics of the users involved in the solution. This can ease the step of identifying actors[15] in the design process and help the customer to understand the importance of identifying actors.

Schedule and Budget

Include schedule and expense information.

This is also a section that originally belonged to the project plan document and not to the vision scope document. The preferred way to create an estimate and a budget in the envisioning phase is by looking at time and material, because you don't know the exact amount of work. However, in many projects you'll very quickly be asked for a time estimate and a budget for the solution, or at least for the envisioning phase. So you might be forced to include a schedule and a budget, but remember that it should only cover the envisioning phase, because you don't know all the requirements yet!

Revision History

Create a document history.

This wasn't officially part of any of the MSF documents. However, we like the idea that of including in all documents a revision history table showing the revision history and the people who have revised the document (see Table 20-4). This is very common in project documentation—documents should be subjected to version control in the same way you would with software. Distribution lists are another thing you can include. Distribution lists are also common in project doc umentation and shows who has received the document.

Table 20-4: Revision History
Date Revised | Revised By | Description
010501 J | ohn Hansen | First version
020601 J | ohn Hansen | Revised first version—paragraph about competitors removed
040901 | Carsten Thomsen | Second version—two paragraphs added

Sign-Off

This wasn't initially part of any MSF documents at all (even though Microsoft advocates that the documents are signed off). We believe it's very important to get the sign-offs from the customer before moving on to the next step. Otherwise, you can't control the process at all. We believe the right place to have a sign-off is in the document itself.

How to Make a Vision Scope Document

You've been introduced to the vision scope document and its content. We'll finish this section with some tips and guidelines for what to do when creating a vision scope document.

Driving the process: The primary person driving the process is the product manager, because he or she is usually the first person to meet with the customer. The sales force might also be meeting with the customer, but this is often just to get a foot in the door (you know how pushy these guys can be . . .).

Economy: Always seek to create the envisioning phase on a time and material base, because of the uncertainty in the project and in this phase as well. The uncertainty is high because no requirements have been uncovered yet.

Ask the right questions: A typical error is that the product manager just fills out the vision scope document by guessing what's part of the various sections. This makes the vision scope document just another document that no one takes seriously. A good way to gather the necessary information is by stepping through the sections with the customer in a meeting. Here you can ask all the right questions. Afterwards you write the vision scope document, let the customer review it, and make a final version. The final version is signed-off by the customer.

Other output: You've been introduced to the vision scope document, which is the output from the envisioning phase. However, the risk assessment is also an output from this phase, because it's an ongoing process starting in the envisioning phase; some risks will decrease—for example, understanding of the requirements improves—whereas others may worsen, such as an increasing impact on related applications.

No step-by-step template: This is a reminder; even though you've been introduced to all the sections that can be included in a vision scope document, you mustn't use it as a step-by-step guide: Use it as inspiration.

Envisioning Summary

The envisioning phase is the first phase in a project. In this phase, you start gathering the overall requirements. MSF focuses on the business instead of technology. You, too, must focus on the business and identify the vision for the project and the business goals. The vision statement points in the direction that the solution and organization are heading. The business goals are what the business expects to get out of the project—the benefits. Later on, to find out what to create in the project, you're specifying what must be developed in order to meet the business goals. All this is collected in a document called the vision scope document. This is the primary output from the envisioning phase. When the vision scope document is signed-off by the customer, the vision scope is completed, which is a major milestone, and the envisioning phase has been completed. It's the product manager who's the primary driver in this phase. The vision scope document is the basis in the planning phase for digging further in and specifying exactly what must be developed.

Planning

The second phase in the Process Model is the planning phase. In the planning phase, you start planning and designing how to develop the things you identified at a high level in the envisioning phase. The input to this phase is the output from the envisioning phase: the vision scope document and the risk assessment. The process is then to transform the vision scope document into detailed specifica tions that the developers and project team can use in the development phase.

The planning phase is very important when dealing with software projects. It's in the planning phase that you create the design and the skeleton of what you'll build in the development phase. The MSF Process Model planning phase consists of a design process that again consists of three perspectives. The first perspective is the conceptual design, in which you design the solution as seen from the users' perspective using a language the users understand. In the second perspective, you design the solution in a logical way, using the conceptual design output as the input. This phase is from the project team's perspective. Finally, the third perspective is that of the developers. This is the physical design. It's where you determine how the solution, as designed in the logical perspective, will be physically implemented. The output from the planning phase is a functional specification and a project plan. This output will be input to the next phase, which is the development phase, and you have reached the major milestone: project plan approved.

Design Process

The design process is where you design the solution. It's sometimes regarded as an independent model at the same level as the Team Model, Process Model, and so on. We've chosen to place it as a process under the Process Model, because the Process Model and the design process are so integrated that none of them can stand alone. As mentioned, the design process consists of three different kinds of design, which are the conceptual design, the logical design, and the physical design. The reason why the design is split up like this is that the design process involves different people who have different perspectives and different skills. To make sure all parties contribute to and have the same understanding of the project, the design process is split up. Another reason is that to achieve project success, you've got to focus on the business and the business needs before focusing on the technology; the three perspectives help you do that. We won't drill into detail when describing the design process, because the rest of the book explains everything with examples and detailed explanations. However, we'll cover every thing from a wide perspective.

Conceptual Design

The conceptual design is the first of the three perspectives. The aim in this step is to involve the users and gather users' requirements and expectations. The con ceptual design contains information seen through the eyes of the users. The conceptual design starts from the vision scope. By analyzing the vision scope and especially the business goals, design goals, and the solution design, you define the core processes needed in your solution. By user involvement, you might identify additional processes needed. When all the processes are identified, you describe what tasks are included in each process. These tasks are the real functionality of the solution. This leads us to the official structure of the conceptual design, which consists of the following:

  1. Research baseline: In this first step, you identify the key business processes and activities. Most of them can be identified directly from the vision scope document. In the search for business processes, you can look at other sources as well. By analyzing existing documentation, business diagrams, organization diagrams, and enterprise architecture documentation, you might identify additional business processes your solution needs to include. You can actually start interviewing users in this step, if the solution is complex and business process identification is hard. To put it another way, in this step, you need to understand the business and how the business works. This is done by researching all information available about the business.

  2. Analysis baseline: In the analysis step, you take the baseline a step further. Here you describe in detail what the solution will solve. After completing the research baseline step, you'll have a clear understanding of what processes are needed in the solution. The next thing you'll have to do is to decide exactly what processes must be included in the solution, and how these processes are performed.

    Let's assume that you had discovered in the research baseline the need for an order process in an e-commerce solution. A process will typically contain a number of low-level linked tasks. In the analysis baseline step, you must find out exactly which tasks are needed to perform the process and what information is passed between them. Why must you do that? Well, because that's exactly what needs to be implemented in the solution.

    In order to do this, you can perform some additional analysis of the business, like creating a workflow diagram that shows the workflow related to the order process (see Figure 20-6). The workflow diagram just shows who takes part in the process, which is very important, but doesn't show what the tasks are or the material being passed, like a typical workflow diagram would. Another suggestion can be to interview the users who are performing the tasks. Finally, you can observe how the work is performed.

    Click To expand
    Figure 20-6: Workflow diagram

    What to choose is really up to you. We suggest that for simple processes you interview the users involved, and for very complex processes, like tax calculation in an enterprise, you should conduct interviews and perform workflow analysis. When you know what tasks are needed to perform a process, you need to document this. For documenting you can use UML, by creating use case diagrams, scenarios, and sequence diagrams or collaboration diagrams. (How to create the UML diagrams is described in detail in Chapters 4 and 5.)

    When creating the use case diagrams, you'll have to relate those to actors. MSF advocates that the user profiles and actors of the solution are identified as a separate step. We disagree slightly on this. We believe it's more efficient to focus on the processes and scenarios first and then add the actors to the use case diagrams.

    When creating the diagrams of the processes, you can make both current-state and future-state diagrams. Current-state diagrams illustrate how the business processes and tasks are today; future-state diagrams illustrate how the business processes and tasks will be once implemented. We discussed this in Chapter 2, and our recommendation is that you focus on the future state only, unless the business processes are too complex, because the current state is very time consuming and isn't really beneficial unless the business is complex.

    The bottom line is that in this step you transform all the user requirements and business tasks into UML use case models and sequence diagrams. Because the perspective in the conceptual design is the users', no technical terms or language should be used.

  3. Optimization baseline: In the optimization baseline step, you take a look at the diagrams and models created in the analysis baseline step, and try to optimize these. The key words for this step are redesign processes. You've just identified and documented all of the processes and tasks in the analysis baseline step, but some of the processes might not be optimal. In one process, you might have identified the need for manually transforming orders into invoices, say, once a day. What if this can be done automatically? Well, then you've optimized that process. It's as simple as that; analyze all the processes and try to come up with ideas for optimizing the process.

    Another frequent subject for optimization is when different processes can be implemented as one process. If you have three processes for managing three different types of master data, you might be able to implement only one process to manage all three types of master data.

  4. Another very important thing to do in this step is to test your processes and scenarios. To do this you can create prototypes, outline the user navigation on paper, and so on. The important thing is that all the processes and tasks are stepped through and corrected until both the users and the business are satisfied and can say, "This is the way the processes must be implemented."

  5. The output from this step is optimized and tested UML use case and sequence diagrams.

After stepping through the three steps of the conceptual design, you've doc umented what must be implemented in the solution, and you've done it in a way that's understandable to the users. All the output from the conceptual design is input to the logical design, during the creation of which you'll sit down with the project group and determine how to structure the solution in a way so that the documented user needs are implemented.

Logical Design

After the conceptual design step, you've documented all the user require ments and business processes. In the logical design, it's time to transform this into a logical model of the solution. The word logical is important here, because to make the best solution, you've got to design the solution without being limited by physical constraints, and in a way that the entire project team can contribute. The perspective of the logical design step is that of the project team, meaning that technical terms and language not understood by the entire project team aren't used. The overall purpose of logical design is to provide the project team with a common and clear understanding of how to create the solution before drilling into the physical considerations. The logical design consists of these steps:

Analysis baseline: In the analysis baseline step, the aim is to create a business object model of how the solution will be created. To do this, you first need to identify all the business objects and services. In Chapter 2, you can see how this is done. When identifying the business objects, services, and their relationships and attributes, the models and diagrams from the conceptual design are analyzed. MSF advocates the use of 3-tier modeling. This is a nice approach in the COM+ world, but in .NET development, we feel that it's often just as appropriate to use ordinary class diagrams.

Rationalization baseline: Just as the conceptual design has a step for optimizing the models, the logical design also has an optimization step. This step is called the rationalization baseline, and this is where you refine the business objects by eliminating out-of-scope objects, combining redundant objects, and making the objects as detailed as possible without dealing with physical considerations. Finally, you test your models and diagrams by making prototypes and step through the scenarios and sequence diagrams to see if it's possible to complete those in your design.

Remember that the design steps are indeed iterative, meaning that you'll iterate through the steps many times during your design. The design steps aren't strictly sequential (like the Waterfall Model), which means that the next step can start before the previous step has finished.

Physical Design

The physical design is where the models and diagrams created in the logical design step are transformed into physical models and diagrams. The developers need to know how to physically implement the solution diagrammed in the logical design. This is what you do in the physical design, and it's important to involve developers in this step, so the perspective is that of the developers.

  1. Research baseline: The first step is to do some research. You must determine which physical constraints exist for your solution. These constraints will mostly be described in your vision scope document. One example can be that a design goal in the vision scope document dictates that the solution must be developed using Visual Basic. Other sources for physical constraints can be the logical models. You also need to determine the existing infrastructure to know how the solution fits into it. Actually, you need to know a lot about the enterprise. You need to know about existing components—maybe some of those can be reused. You also need to know of other applications in the enterprise—maybe some of those create physical constraints for your solution.

    Tip

    When developing enterprise solutions, it's important to look for current-state and future-state gaps. If you design a solution demanding things that the existing enterprise can't deliver, it has to be documented and addressed. An example can be that you design your solution for implementation in an environment with high-speed network capabilities. If the enterprise doesn't provide this, this has to be addressed.

  2. Analysis baseline: In this step, you're ready to determine the preliminary deployment model and the involved network and component issues. Here it's important to diagram the deployment and involved components. This is very useful when you deploy the solution.

  3. Rationalization baseline: Before you can continue with the physical design step rationalization baseline, you need to determine which technologies you'll use to build the solution. The remaining physical design depends on the technologies you choose, because you're going to design components, interfaces, and so on. We've decided to make the discussion on "Technology Choice" an independent section, because it's usable not only for the physical design, but also for planning in general—like when discussing technology at the initial customer meetings. Wait a minute, discussing technology choices at the initial meetings isn't an option, is it? No, it isn't—you can only determine technology choices when all requirements are known. However, physical constraints do exist in the vision scope in the form of design goals and solution concepts, and customers very often insist on talking a little bit about technology. Therefore, we'll talk about technology choices a little later in this chapter.

    Now, let's get back to the rationalization baseline. In the rationalization baseline, you determine how to package and distribute the classes and components in your solution. In other words, you split up your services into real isolated services whereby only data services perform data access and so on. After doing that, you need to decide how to package your services. If some of your services are COM+ components, you need to determine which services will be packaged together in the same component. A rule of thumb is that you should package COM+ services in the same component if they're coupled through shared functionality. Notice that if any possibility exists that two services will run on different physical machines, they shouldn't be packaged in the same component. Also notice that if one service fails, all other services in that component won't run.

  4. Specification baseline: The final step is the specification baseline. In this step, you determine a programming model and finalize the object and component specifications, so the programmers can take over and develop the solution. A programming model is a set of standards and guidelines for how to use the technologies you've selected. One example can be that you decide that all COM+ components must be stateless. Other examples can be threading model considerations or error handling guidelines. All of this is part of a programming model, together with other existing development guidelines that must be followed. After doing that, you take your models and transform them into real physical models with the final interface descriptions, transactional information, and so on. When completed, the programmers are ready to take over and start the development phase.

    Tip

    The physical design should always aim at developing solutions that are easy to change, easy to scale, and easy to reuse.
Technology Choice

Determining your technology choice is an important step to take before finalizing the physical design with interfaces and physical considerations, which are dependent on the choice of technology. For making technology choices, we recommend that you make a matrix for comparing technologies, like the one in Figure 20-7.

Click To expand
Figure 20-7: Technology choice matrix

The use of the technology matrix is explained in Chapter 2. What's important is to transfer all the requirements into physical constraints if possible. Here are items that you may include in the technology choice matrix:

  • Performance

  • Security

  • Deployability

  • Scalability

  • Reliability

  • Reusability

Functional Specification

One output from the planning phase is the functional specification, which is what the developers use to develop the solution in the development phase. In the "old days," when talking about functional specifications, you might only have been talking about diagrams and feature lists; in MSF, there is much more to it than that. An MSF functional specification includes the following:

Vision summary: This is a summary of the information of the business as described in the vision scope document. It includes the vision statement, scope, problem statement, and other relevant information.

Design goals: Most of them can be taken from the vision scope document, but look out for new design goals that may have turned up during the planning phase.

Requirements: The requirements are gathered from the users and the customer. They include both functionality and performance requirements. A functional requirement can be something like "The system must require logon with NT logon." An example of a performance requirement is "The response time must be less than 3 seconds for all queries."

Usage summary: This is a summary of when the solution will be used. It can be very important for the developers to know whether the solution is an annual tax calculation only used in January. You'll also summarize who'll use the solution. Here you can use the actor descriptions and information from the user education plan.

Features: This is a prioritized list (prioritized because you might remove features when trading off) of all features in the solution, specifying exactly what the solution does and how it works.

Dependencies: Here you specify if other factors exist that the solution depends on. One example can be that the solution is dependent on a new installation of Windows XP on all workstations.

Schedule summary: This is simply a summary of the schedule with milestone information and deliverables, including who's responsible for the various deliverables.

Issues: Here you specify issues that might affect the project, especially which risks might be involved and their impact.

Appendixes: In the appendices, you place all the UML diagrams and models created in the planning phase. This is the real developer specification that the developers will use to develop the solution.

Prototypes: If you've developed any prototypes during the envisioning or planning phase, you should include those as well in the functional specification.

The last thing to do before handing the functional specification over to the developers is to validate it. It's important that all project team members partic ipate in validating the functional specification, and you should also involve the customer in this validation process, because design changes are more costly once the development phase has started. The last thing we'll say about the func tional specification is that it can be in any form you like. We prefer it to be electronic and, in large projects, placed on an intranet for easy access by all parties involved.

Project Plan

The project plan is the other major output from the planning phase, with the functional specification being the first. To put it directly: The project plan is an evolvement of the vision scope document in which all issues are specified. The driver in creating the project plan is the program manager.

Revision history: It's a good idea to specify a history of the previous versions of the document and name the document with a version indicator. This ensures that everyone refers to the newest version.

Distribution list: It's also a good idea to include a distribution list so everyone can see who has received the document.

Vision scope summary: You'll include a vision scope summary of all the business information such as vision statement, problem statement, business goals, and design goals. If any of these have changed, you should apply the changes.

Development plan: In the development plan, you specify how the solution must be developed. You'll divide the development into iterations, and specify a plan for third-party involvement if your project has any.

Test plan: The test plan is driven by the tester role, and includes a plan for how and when to test. You'll also specify how to report errors, and what the consequences are if deadlines aren't met. We strongly advise you that you create a test plan for internal use, and another for the customer. In the customer test plan, you must specify the consequences if the deadlines aren't met, such as the project will be delayed and the resources necessary will increase because team members are waiting. A good practice is to agree on turnaround times with the customer— for example, having the document back within two days. You can even be hard on your customer by considering the documents as accepted if no inputs are received within the time frame—but only if you have agreed on the turnaround time frames and have these agreements in writing (in the project plan). In the customer test plan, you'll also have to specify very carefully how to test, perhaps preparing some test scenarios. Otherwise, customers tend not to test everything and focus on graphical design instead of functionality. Another thing to remember when you create test plans is that in your UML diagrams you have a lot of things to test. You must test that the business goals are fulfilled, that the processes are implemented, and that the scenarios from the use cases and sequence diagrams can be performed. Finally, you should always plan some kind of stress test or load test, simulating many concurrent users.

User education plan: The development of the user education plan is driven by the user education role. In the user education plan, you specify the plan for how to educate the users in using the solution.

Communication plan: The communication plan is very important. In this plan, you specify how to communicate in the project process. You can, for example, specify that the customer can only contact the product manager and that change requests must be submitted using a special change request form. The communication plan is important because it helps you specify the responsibilities for the project.

Deployment plan: You specify how and when to deploy. Important information to include in this plan is who will be involved in the deployment. You might need some of the system administrators to support you when deploying.

Project team: This is just a specification of the project team and the roles. If your native tongue isn't English, you might want to translate the role names, because these often confuse customers. This is quite alright, as long as you don't change the role meaning.

Product ship date: The date the solution will be finally released. This comes after the stabilizing phase.

Development schedule: This is simply the schedule for the development. Remember to split the schedule up into iterations.

Test schedule: This is the schedule for testing. Don't forget to include time for error corrections.

Training schedule: The training schedule is tightly related to the user education plan and is simply a schedule for when the training takes place.

User support schedule: In the user support schedule, you specify when the user support takes place. You might plan for additional user support like hotline functionality, or you might plan additional user support sessions.

Deployment schedule: This is the schedule for the deployment.

Communication schedule: Here you specify the schedule for the communication, such as scheduling status meetings, and so on.

Sign-off: Last, but not least, don't forget to get that vital customer sign- off, signaling that the project plan has been accepted and is ready to be carried out.

Developing

The developing phase is quite simple: Go create the code! Well, of course, there is more to it than that, but it certainly is the main activity in this step. The purpose of this phase is to create the code, but there are a few issues we'll point out:

Iterations: It's extremely important that the development is divided into iterations. You saw why this is important in Chapter 2. The main reason is that the development process is much more effective if the developers can focus on a limited part of the complex solution. Another reason is that the testing phase is quicker, because fewer lines of code are tested and therefore easier to debug. You should have at least four iterations, depending on the size of the solution. Always start with the core processes and then the most important ones. Treat each iteration as a separate project, with tests and customer acceptance. However, you don't need to physically implement each iteration in a live environment, even though it can be done.

Test: You should plan a test phase for each iteration. The test phase should include time for the internal tests performed by internal testers, time for corrections (there's really no point in testing, if you don't have time for making the corrections), tests by the customer, and time for correcting errors reported by the customer. It's important the customer tests and accepts the iteration before moving on to the next iteration. Only by doing that can you ensure progress and a true iterative approach. Controlling the customer is a major issue here. You need to specify up front in your project plan when the customer will participate in testing and return error reports. In our experience, it's a good idea to create a test package, specifying exactly how the customer should perform the test, which steps to perform, and so on. Otherwise, we've experienced that the customer very often doesn't test everything, and focuses on the graphical design instead of the functionality.

Sign-offs: You should always make the customer sign-off on the current iteration before moving to the next. If not, you'll find yourself in iteration three while still correcting one of the first iterations, and then the benefits of iterative development have vanished.

The output from the development phase is tested code ready for release, and the scope complete milestone has been met.

Stabilizing

The stabilizing phase is another very simple phase, easy to understand. You're in the stabilizing phase after the development phase has finished, and the solution has been released. In the stabilizing phase, you follow the solution for a limited time, like a week. In that time, you make sure the solution is running satisfactorily in the real-life environment. You can compare this to when you make a paper boat and carefully watch it during the first 2-to-3 meters it sails. The reason for doing this is that some errors only turn up when the solution is running in a real-time environment, like scalability problems. After watching the system for a while and implementing the necessary corrections, the solution is ready to be deployed.[16]

Note

You should never correct anything but errors that prevent the solution from working while you're in the stabilizing phase.

This is very important: Never start correcting minor errors or implementing change requests in this phase. By doing so, you risk creating other errors or getting an unstable solution. Minor errors and change requests must be handled in a new version of the project. You need to make this clear to the customer at an early stage.

Deploying

In the deploying phase, the project team deploys the solution and stabilizes the deployment. The solution should be stable at this point (otherwise the release readiness milestone has not been met in the stabilizing phase). Another task in this phase is to transition the project (ownership) to the customer and the rel evant functions (support, development, and so on). This phase ends with the deployment complete milestone. For reaching the deployment complete mile stone, the team needs customer acceptance (sign-off). At this time, the solution should provide the customer with the expected business value as stated in the business goals.

Tradeoff Matrix

The tradeoff matrix is a tool you can use when discussing the development strategy with the customer. It's a tool for explaining to the customer that you can't develop the most extensive solution in the world with limited resources available and in no time at all. These demands conflict, and the customer has to choose which one to optimize. Just like when buying a house: You can't get the biggest house in town, placed in the best location, and expect it to cost close to nothing— it just can't be done. Basically, you can choose from three overall development strategies:

First to market: The first strategy is to be the first to come up with a solution and thereby benefit from being the first mover. If no online bookstore exists, you can benefit from being the first to have an online bookstore by selling a lot of books before any competitors arrive.

Within budget: Another strategy is to develop the best possible solution within a specific budget. If you're going to develop an online bookstore, but only have a budget of $50,000, you must develop the best solution within that budget.

Enhanced solution: This strategy is to get a competitive advantage by having a solution that is superior to the competitor's solution. If you're going to develop an online bookstore, and you realize that hundreds of online bookstores already exist, you might decide to develop an online bookstore with many more features than the others, to get the competitive advantage.

To help you discuss these things with the customer, MSF has a tool called the tradeoff matrix (see Figure 20-8). In the tradeoff matrix, you may only place one "X" in each column and one "X" in each row.

Click To expand
Figure 20-8: The tradeoff matrix

Constrain: The Constrain setting means that this "criterion" must be met. If you place the constraint setting in the Schedule row, it means the schedule must be met. You then have a first-to-market strategy. On the other hand, if you place the "X" in the Resources row, you have chosen a within-budget strategy. Finally, if you have a constraint in the Feature row, you have an enhanced-solution strategy, meaning that the strategy is to make the best and most enhanced solution.

Accept: The Accept column is an indication of what to trade off. You can't optimize on resources, schedule, and features—you have to choose one of them. In the Accept column you decide which area to trade off. If you have acceptance in the Resources row, it means that you can add more resources, if necessary. If you have acceptance of Features, it means that you can remove features from the prioritized feature list, if necessary, as long as the business goals are met. Notice that you can't add resources or delete features just because the project team is behind schedule; this is still an internal problem, but if new features suddenly have to be implemented or the customer or a third party delays the process, then you can use the tradeoff on the issue stated in the Accept column.

Optimize: The Optimize setting is somewhat vaguer, because it lies in a gray zone between the Constrain and Accept settings. What it means is that the remaining row, not having Accept or Constrain specified, has the Optimize setting. Optimize means that you seek to optimize the item, but you don't trade off or exceed the scope. In Figure 20-9, you can see a tradeoff matrix in which you trade off resources (more resources can be added) and you want to make the most feature-enhanced solution (constraint in features).

Figure 20-9: Tradeoff matrix with resources tradeoff specified

The tradeoff matrix is really a valuable tool in that it can help you deliver solutions on schedule, of the right quality, and with the right features. Use it in your projects and present it to the customer early on in the process. This way, the customer will know what project tool you're working with and how you use it to balance his or her requests.

Risk Model

When we talk to Microsoft consultants and ask them which MSF model they think should first be implemented, the answer is often, surprisingly, the Risk Model. Those arguing this point out that controlling risks in a project is the single most important issue. We pretty much agree. However, we do believe that the Process Model is more important to implement, if the organization doesn't already have a project methodology implemented.

The Risk Model is, as mentioned before, all about controlling the risks in the project. The MSF Risk Model aims at decreasing the risks, as the project evolves. This is done by identifying the risks, managing the risks, and trying to minimize the overall risks in the project.

The risk assessment, which is the output from the Risk Model, is an internal document, only used and seen by the project team. The reason is that the risk assessment might contain information that you don't want customers or other external parties to be aware of. As examples, we can mention risk descriptions such as "The developers lack .NET skills," "The customer is hard to deal with," or "The customer changes contact person frequently." You don't want external parties to know about risks like these. However, in real-life situations, you might want to have an external risk assessment as well. This applies if you're working with resources from the customer organization, but you should still have an internal risk assessment.

What Is a Risk?

Before we start digging into the Risk Model and its elements, let's take a look at what risks are in the first place. A risk in the context of a project is something that threatens the project. The threat is the risk of a loss. The loss doesn't have to be of financial nature—well, not directly anyway. It can be the loss of time, reputation, quality, and so on. In other words, a risk is the threat of damage to your project.

Risk Strategy

The goals of the MSF Risk Model are as follows:

Minimize the risk of loss: The overall strategy in the MSF Risk Model is to minimize the risk of a loss. A loss is a threat towards the project and can very often lead to unfulfilled goals and thereby an unsuccessful project. That's why it's important to minimize the risks of loss. You have two ways of doing this: You can either minimize the possibility that the risk occurs, or you can minimize the impact when the risk occurs.

Be proactive, not reactive: This is the philosophy and the strength of the MSF Risk Model. You should be proactive, and not reactive. The difference between the two concepts is that being proactive means you take action before the risk occurs, whereas being reactive means that you take action when the risk has occurred. It sounds like a minor difference, but this is in fact what differentiates successful risk management from unsuccessful risk management. By being proactive, you decrease the overall risks, and thereby the threat of a loss, as the project process evolves. This is true because you take some action to minimize the loss and the likelihood of the loss of occurring. How this is done is described in the "The Risk Model Content" section. Figure 20-10 shows how the project risk decreases as the project process evolves.

Click To expand
Figure 20-10: Risk decreases over time.

Focus on reason not consequence: Another strength of the MSF Risk Model is its focus, which is on the cause of the risks not the consequences. You can often improve the effort you put in decreasing the consequence if a risk occurs by focusing on the reason why it occurs. To use a metaphor, imagine you're the owner of a warehouse, and one risk identified is a fire in the warehouse. The consequence is damaged stock. If you only focus on the consequence, you might try to minimize the loss by installing a sprinkler system or by minimizing the items on stock. This is fine. As a matter of fact, it's a nice action to take, but it might be more valuable if you look at the reason for the risk of fire, such as too high a temperature or too many flammable materials in the warehouse, and try to minimize this. In a proactive approach, you would have less flammable material in the building, or install temperature control and video cameras. This way, you minimize the possibility that the fire risk actually occurs.

Track risks: The last characteristic of the MSF Risk Model is that it focuses on tracking the risks in an iterative way. Risk management isn't a one-off task—it's an iterative task. In too many projects, risk management involves identifying risks just once in the project initiation process, putting the risk assessment document away, and taking a look at it when the project has finished. This method of risk management is meaningless. First of all, the risks need to be looked at in a proactive way. Actions have to be taken in order to minimize the likelihood of the risks occurring and to minimize the impact of the risks when they occur. You have to track the risks to see how these actions have influenced the risks. Another reason for tracking the risks is that over time some risks will disappear, and new risks will show up. One example: Risks in developing using a beta product disappear once the product is officially released, and new risks such as communication failure if the customer changes contact person in the middle of the process can suddenly be identified. Actually, risk tracking is one of the reasons Microsoft itself stays ahead in the software industry. Microsoft monitored the risk to its business brought on by the Internet (which was being heavily promoted by rival companies) in the early 1990s when it wasn't part of the company's strategy. By the end of 1995, the risk to its business was so great, because the Internet was obviously going to be massive, that Microsoft switched huge resources over to developing its own Internet product set.

The Risk Model Content

As mentioned earlier the Risk Model is an iterative model, meaning that the steps involved are repeated during the project process. The Risk Model consists of six steps. These steps are Identify, Analyze, Plan, Track, Control, and Learn. Figure 20-11 shows you the iterative steps in the Risk Model, which we describe in the next sections.

Click To expand
Figure 20-11: Risk Model steps
Risk Assessment

The risk assessment is the output from the Risk Model. It's a "living" document describing the risks identified and the plans for minimizing the threat to the project. The risk assessment document is made by stepping through the first three steps of the Risk Model. Each step adds new things to the risk assessment document. In the fourth and fifth steps, the risks are analyzed to see if something has changed since the last time. This can very likely be true. Earlier we pointed out that some risks can disappear and others can suddenly show up. Besides this, probability and impact of each risk on the project will also change, because you take action to reduce it. Finally, in the sixth step, the project team captures knowledge and lessons learned in a reusable form for reuse within the enterprise. Let's take a look at what information is included in the risk assessment, and after that we'll introduce you to the risk steps to see how the information in the risk assessment is filled in. But first the content of the risk assessment:

Risk description: The risk description is simply a description of the risk in just a few words or sentences. One risk description can be "The project is built using beta software that might not be released until sometime after our deadline."

Impact: The impact is a measurable indication of what loss or damage the project will face, if the risk occurs. The measure can be in time, like weeks or days, or in expense, meaning money. We suggest that you choose what you think is best, but it's important to choose the same measurement for all risks in order to make the risks comparable. We have experiences with both the time and the expense measures, and personally we find the time measure the best one, because it's not dependent on different hourly prices. So, here you specify how the project will suffer if the risk occurs, measured in either time or money. For example, say that a beta product failing to be released by the deadline results in the deadline being exceeded by 8 weeks, which is the time it will take to rebuild the solution using another development tool. This is a fairly high impact.

Probability: The probability is the likelihood that the risk will actually occur. Here you specify what you think the objective likelihood is. As in the impact case, you'll have to choose a measuring scale. You can use a percentage, a scale from 1 to 5, a scale from low to medium to high, or something similar. It's advisable to choose a measurement that is numeric, because in calculating the risk exposure you'll need to multiply the impact with the probability. We prefer to use a scale from 1 to 5, where 5 is the highest probability, because we find the percentage measure hard to use in real-life situations. A funny thing about the MSF Risk Model is that a probability can't be 0% or 100%. The reason is that if a probability is 0%, then there isn't any risk at all, and you don't have to think about it; if a probability is 100%, there is no risk either, because it has already occurred— that is, it's become an issue or problem that now needs to be resolved. Risks that have already occurred aren't part of the risk assessment, because the contingency plan has been triggered. It makes sense if you think about it. In the example with the risk of building using a beta software product, you can estimate the probability as 3 on a scale from 1 to 5.

Risk exposure: The risk exposure is the most important information in the risk assessment. It's by this value you sort the risks in order to focus on the most influential risks first. The risk exposure is calculated by multiplying the impact with the probability. To continue our example with an impact of 40 days (8 weeks) and a probability of 3, we'll have a risk exposure of 40 × 3 = 120. 120 is then the risk exposure score.

Mitigation plan: After specifying the risk and the risk exposure score, you need to plan what to do in order to lower the risk exposure score and thereby minimize the project risk. The plan for what to do, in order to lower the risk exposure, is called the mitigation plan. In order to lower the risk exposure, you can minimize the probability or the impact. The plan details the actions you'll take to minimize the risk exposure. In the example with building using beta software, the mitigation plan might be to develop the code in an alternative way, making it possible to use another software product instead. This will minimize the impact quite a bit. Another mitigation plan might be to participate in the beta program, to get support and release candidates when available. This can lower the probability a little bit. There are usually a number of mitigation options, varying in cost and effectiveness.

Contingency plan: You also need a plan for what to do if the risk occurs. That's the contingency plan. In the example of building using beta software, you can decide to deploy the solution on a previously released version of the beta product.

Risk ownership: Much too often risks have been identified in projects without anyone taking action, like executing the mitigation plan or the contingency plan. The reason frequently is that no one has been assigned to the tasks, so everyone forgets about it and thinks that somebody else is taking care of it. That's why risk ownership is important. In determining risk ownership, you specify who's responsible for tracking the risk and making sure the mitigation plan is executed. This doesn't mean that the owner of a risk is executing the tasks, but that he or she is responsible for making sure it's actually done.

Risk ID: The risk ID is just an ID, like a sequential unique number. This is used instead of the risk description when discussing the risks. It's only function is identification. You can consider this ID as a primary key in a database table that you don't change.

Miscellanea: Other things to include in the risk assessment that aren't directly advocated by Microsoft can be creation date, planned review date, a description of what triggers the risk and when it will trigger, and so on.

Identify

The first step in the Risk Model is to identify risks. This is an important step because only identified risks can be managed. You must remember in this step that there's no need to be afraid of identifying too many risks—not at all. In fact, the number of risks threatening your project is there no matter whether you identify them or not. So identifying them enables you to control them. Generally, you should be much more skeptical about a project with only 3 risks identified than a project with say 80 risks identified.

Several ways exist for identifying risks. We advise that for enterprise projects, you have a brainstorming session with participation from all people involved in the project. You can also look at other sources to identify risks, such as examining historical project plans and risk assessments. You'll also benefit from asking about other people's experience with risks in similar projects. The identified risks are added to the risk assessment document.

Analyze and Prioritize

In this step, it's time to analyze the risks identified. For each risk identified and listed in the risk assessment, you specify an impact score, a probability score, and the risk exposure by multiplying the two scores. After that, it's time to rank the risks. The risks should be ranked by risk exposure in a descending order. This way, you always have the risks with the highest risk exposure at the top of your document. The document with the ranked risks is called the Master Risk List.

Plan and Schedule

In the planning and scheduling step, you start creating the mitigation plan and the contingency plan for each risk in the risk assessment document. Creating the contingency plan is straightforward: You just make a plan for what actions to take if the risk occurs. The mitigation plan is much more interesting because it's by performing the actions in this plan that you decrease the exposure in your project. The mitigation plan is also a bit more complicated. For each risk, you need to decide which kind of strategy will be appropriate. The Risk Model differs between six kinds of strategies for making mitigation plans. These are Research, Accept, Transfer, Mitigation, Contingency, and Avoid.

In both the Mitigation and the Contingency strategies, you plan which actions to take to reduce the risk exposure by either reducing the risk probability or by min imizing the risk impact. In the Transfer strategy, you look for ways to transfer the risk to other parties. It's not as bad as it sounds . . . you can use third-party companies to create certain parts of the project and thereby transfer the risks to those parties. Research is about getting additional information about the risk before moving on. The Accept strategy simply refers to the notion that you have a risk you can't do anything about, and that you have to accept it—an example might be the gov ernment tightening Section 508 requirements.[17] The last strategy is Avoid. Ask yourself if there is any way to avoid the risk. Can you, for example, avoid building using the beta software in the first place? You can also consider rejecting the project if you consider it's too risky.

Lastly, you specify the owner of the risk, meaning the one responsible for the plans being executed. Before leaving the planning and starting the work of the mitigation plans, you should make a top ten list of the risk exposures and use this list, which is called the Master Risk List. The reason is that in an enterprise project you might have identified 100 risks, and you're in danger of focusing on too many risks, making the risk minimizing process difficult. By having a top ten list of risks in your project that you try to minimize, you ensure that the project team focuses on the most threatening risks. This is easier for the team to handle than having 100 risks to focus on at a time. Besides, you make sure to reduce the overall threat during the project process as illustrated earlier in Figure 20-11.

Track and Report

As we've outlined earlier, the Risk Model is an iterative model, and the risk process is an ongoing activity. The strength of the Risk Model is in the tracking of the risks: You monitor if the mitigation plans have had any effect on the risk probability or the risk impact—if so, the risk exposure has changed as well. A good idea is to have a schedule for risk tracking meetings, say, every second status meeting or on a monthly basis. This way, you make sure that these meetings are actually held and that people are reporting a status for the risks they own.

In a risk tracking meeting, for each risk you should analyze whether the per formed mitigation plan has changed the risk exposure score. After that, you should look at the remaining risks, keeping in mind that you have only been performing mitigation plans for the top ten risks. For each of the remaining risks, you should analyze if something has changed the risk exposure scores. Finally, you hold a brainstorming session for additional risks that can be identified. These additional risks are analyzed through the first three steps and placed in the risk assessment document. Next, you rank the risks and make a new top ten list, which you track and report on the next risk tracking meeting. Finally, you should outline the risk status in a risk status report.

Control

The control step is linked with the track and report step, and is actually performed either in the risk tracking meeting or afterwards by the program manager. In the control step, you look at the risk status to see if some risks can be retired. Risks to be retired are those that have actually occurred, or those for which the mitigation plan has reduced the risk exposure score to 0. One example is if you're building using beta software, and the mitigation plan is to build using a previously released version of the beta product.

Learn

In the sixth and final step of the Risk Model, the project team gathers lessons learned and knowledge in a reusable form. For example, you can create a knowledge base of successful risk plans and lessons learned.

A good idea when retiring risks and removing them from the risk assessment document is to archive them in another document. By doing this, you can later track how you've reduced the risk in the project, and you can use the document as inspiration when identifying risks in another project.

Risk Model Summary

You've now been introduced to the Risk Model, one of the six models in MSF. The Risk Model provides you with a set of guidelines for how to control and manage the risks in a project. The strength of the Risk Model is that it's made proactive by focusing on the risks before they occur instead of reactive, an approach that focuses on the risks when they've occurred. The way the risk process works in MSF is it makes risk management an ongoing task in the process.

The Risk Model consists of six steps, which are Identify, Analyze and Prioritize, Plan and Schedule, Track and Report, Control, and Learn. The output is the Master Risk List. In the Master Risk List, the risks are ranked by the risk exposure, which is a calculation of the risk impact multiplied by the risk probability. From the Master Risk List, the project team focuses on the top ten risks and tracks the risks in meetings at a frequent interval. During the project process, a risk owner is responsible for executing the mitigation plan, which is a plan for reducing the risk exposure. The strength of the MSF Risk Model is that the overall project threat decreases as the project evolves, because the most threatening risks are continuously handled in a proactive way. The Master Risk List is an internal doc ument and shouldn't be made available to the customer.

Application Model

The Application Model is one of the minor models of MSF. Actually, you've already seen the Application Model "in action" in Chapter 2, but back then we just called it Windows DNA. However, the concepts of the Windows DNA are the same as the concepts of the Application Model. The whole idea behind the Application Model and Windows DNA is that applications must be developed as service-based applications. In traditional application development, you have the same functionality in many applications. You might have a function for tax calcu lation in several applications, and you might have functionality for language support in several applications. Not anymore! With service-based development, you only have one service for language support and one service for tax calcu lation, and then you use these services in all your applications. The benefits are more rapid development, because you can rely on existing services; easier changes (maintainability), because you only have to change functionality in one place; and finally easier testing processes, because you only test isolated functionality. You should consider applications as a mix of different services that can easily be used by other services and applications. The Application Model distinguishes between three different types of services:

User services: User services are the services interacting with the users, such as services presenting data and information to the users or services performing user validation, and so on.

Business services: Business services are services containing business logic. By isolating the business logic from the user services and data services, you benefit from having smaller isolated business logic for easier updates and the capability of running business logic services on separate servers.

Data services: Data services are services performing data access. When having data services performing data access, you can easily reflect changes in the data source by just changing the data access services, without having to change all the business services using the affected data. The data services performing the data access will, for performance reasons, also have to be separated from the business logic, because you quite often want the data services to run on a database server and the business logic services on another server.

A deliverable from the Application Model is the 3-tier model.

Enterprise Model

The Enterprise Model is interesting when dealing with enterprise projects. In enterprise projects, the project itself and the surrounding environment is rather complex. In enterprise development, it's impossible to develop a system without being influenced by the enterprise characteristics. Your solution in such a case won't be an isolated island, but a brick in the overall enterprise architecture. Therefore, it's crucial for your solution that you know the enterprise character istics so you can adopt the characteristics and information into your solution. If you don't do this, you can end up with a solution that doesn't fit in with the existing enterprise environment. If you're building a solution that handles orders, it might be important for you to know what happens to the orders after they leave your solution, or how the organization handles orders in general. Information like that is what the Enterprise Model is all about: describing the enterprise so that valuable knowledge can be incorporated in your solution, such as existing processes your solution is dependent on, existing applications your solution will have to interact with, enterprise architecture that determines technology constraints, and so on. MSF differentiates between four perspectives when documenting the enterprise: the business perspective, the application perspective, the information perspective, and the technology perspective. In other words, the enterprise focuses on the processes, the people, and the technology in the organization you're developing the solution for, and which your solution will relate to. The Enterprise Model is used in the planning phase and driven by the program manager.

Perspectives

As already mentioned, four perspectives exist. You'll use these four perspectives for gathering information about the organization that is valuable to your solution.

Business

The business perspective describes how the business works. This step is usually performed by business analysts. The aim is to get a clear understanding of the business processes—how they work and how they interact. This can be very valuable. First of all, you might discover some business processes or actors you weren't aware of. Second, if you're planning an interview with some of the users involved, you might want to interview some of the business users as well. The business perspective includes plans for how to move the business from its current state to the future state. It also includes descriptions of how the business works and interacts. These descriptions are made using UML. In Figure 20-12, we've made an example of some business actors. Notice that we've included a stereotype called "Business Actor" and attached it to the actor to indicate it's a Business Actor and not an actor to the solution. The diagramming of processes and inter actions will be through class diagrams, use case diagrams, activity diagrams, and sequence diagrams.

Click To expand
Figure 20-12: UML Business Actors modeled in VEA and UmL 1.2
Application

The application perspective is about analyzing the existing enterprise applica tions and their relationships. The aim is to see which existing applications your solution will at some level interact with. The output is a list of applications with a description of interfaces and relationships with other applications.

Information

In the information perspective, you describe and document what information is needed for the enterprise to perform its processes. This description may include information about data policies and dataflow diagrams of how the information flows.

Technology

The last perspective is the technology perspective. In this perspective, you analyze the enterprise software and hardware needed to support the business. The output is lists of descriptions and hardware diagrams.

Enterprise Architecture

So far, we've explained the Enterprise Model using the approach that you simply need some background knowledge to build an enterprise solution that works with the existing environment. We believe this is true, even though it's under standable if you argue that you just need to gather the right requirements through the design process. Well, this is only partly correct, because most enterprise projects are dealing with a complex organization and environment that you have to know about in order to develop a successful solution.

However, the Enterprise Model has a second purpose. You might be asked to develop an enterprise architecture. You can use the approach of the Enterprise Model by analyzing through the four perspectives. The development of enterprise architecture is simple to explain. You describe the current enterprise architecture— where you are now—and the future enterprise architecture—where you want to go. What exists in between are the versioned releases of your implementation strategy for the enterprise architecture.

The Enterprise Model isn't described in great detail here. You should use this model with care. It provides you with some good guidelines for how to develop enterprise architecture, although in most of your projects, you'll most likely only use the analysis approach of the existing enterprise environment. Regardless, this is a very important step.

Infrastructure Model

The Infrastructure Model is a model for handling the infrastructure issues involved with the solution. We don't think of the infrastructure in the sense of network infrastructure or data infrastructure. These concepts are covered in the enterprise architecture and in the Process Model in general. In this model, the infrastructure is about the way the solution is adopted in the enterprise. When you develop an enterprise solution, you need to address certain aspects that don't usually exist in smaller projects, such as the following:

System management: The system management people need to know about your solution. They need to know how to install the solution, how to maintain the solution, and how to make backups and what to backup. Basically, all the information needed for a system management department has to be documented. That's what they need, but you also need something from them: You need to know how the system management works in order to plan the system management team's involvement in your solution.

Help desk: The help desk function has an important function in an enterprise organization. You need to prepare the help desk for your solution by documenting and describing how to provide user assistance to the solution. Good advice is to include a section on possible errors and what to do with them and a section on how to reinstall the solution.

Communication: Communication is another issue in enterprise development for which you'll have to create documentation. It's sensible to document how the communication regarding the solution takes place. You can describe how errors are reported, how change requests are submitted, and so on.

Note

Prior to MSF 3.0, MSF consisted of two distinct Process Models, one for application development and one for infrastructure development. Now, the two Process Models are merged into one Process Model. We do, however, find that it's relevant to still talk about the Infrastructure Model as an independent model.

[3]The product manager is described in detail in the "Product Management Role" section.

[4]The user experience role is described in detail in the "User Experience Role" section.

[5]Here the users correspond to the customer's employees, but this may well refer to users external to your customer's company.

[6]Microsoft named a role for a role cluster because you can have several people performing the same role in your project—for example, this could be the case if your project consists of several subprojects.

[7]At least the program manager will be responsible for the logical design and the functional specification, whereas the developers will be responsible for the physical design. However, if the developers are unfamiliar with UML, the program manager might be responsible for all the design.

[8]A test can be much more complicated than this—for example, automated test scripts can be created. However, the tester should at least create a plan for how to test the solution, and as such it's a simple task.

[9]A dance that involves bending over backwards and passing under a stick. The stick keeps going lower each pass, making the dance more difficult.

[10]There's often discussion about this statement, but what we mean is that if conflicting roles are managed by the same person, such as when just one person is in charge of a project, the team model just isn't the way to go.

[11]The Waterfall Model method is an example of another process model directly comparable to the MSF Process Model.

[12]Last we heard, elephants aren't really suited for human consumption . . .

[13]The number of four is our recommendation; you should always consider this on a case-by-case basis.

[14]The features are prioritized by the customer—make sure you negotiate the priorities of each so that you have some less important ones to hold.

[15]Actors are described in Chapter 4.

[16]After the release readiness milestone is reached.

[17]Described in Chapter 2.


Does MSF Work with UML, VB .NET, and C#?

MSF certainly works with UML, VB .NET, and C#. As you've seen in the design process, the UML models and diagrams are perfect for use with MSF, because UML too divides the focus into user team, project team, and developer team, and keeps focusing on the business requirements before technology. This means that MSF and UML share the same vision about projects. Technology independence is also a shared characteristic. Both MSF and UML are technology independent. The use of VB .NET or C# is also relevant when working with MSF and UML. VB .NET or C# is often used when developing solutions in which rapid development and high performance are mandatory. VB .NET and C# are perfect for both with their true object-oriented high-performance code and rapid development envi ronment. This too fits perfectly with the MSF and UML iterative approach. In fact, we find MSF excellent for most projects—software projects as a well as non- software projects. Another issue we'll briefly mention is that the Rational Unified Process (RUP, http://www-136.ibm.com/developerworks/rational/products/rup) built by Rational (the inventors of UML) uses many of the same approaches as MSF. RUP also has an iterative approach and a design process divided into three perspectives.


Best Practices

Is the MSF concept a piece of cake to understand? Some might say so. But it's damn hard to go out and use it in a successful way. Maybe you're a golfer? In golf, it's fairly easy to learn the theory on how to perform a new kind of swing, but it's very hard to go out and do it the right way. It takes practice. The same counts for MSF projects or for project management in general, for that matter. Jack Nicklaus, the famous golfer, once said something along the lines of "I'm often accused of being lucky. It's funny that the more I practice the luckier I get." This really hits the nail on the head. Success isn't about luck, it's about practice. What's important is that through practice, you keep improving yourself. Microsoft has a method for this we want to introduce you to: best practices. This isn't in particular a part of MSF, but the concept is very useful when applied to MSF, so here goes:

Best practices is something widely used by Microsoft. The concept is to con stantly collect best practices of work done. A best practice consists of the best your organization has done so far with a particular task. It's not the very best task in the world or in your country. You only have internal focus. The best practices are collected and used as guidelines or inspiration for employees performing a similar task the next time. If an employee or group of employees manages to make a task even better than the best practice, you have a new best practice. This way the organization and the quality in tasks should increase over time. MSF itself was created via collecting best practices.

Let's take an example: Imagine you have a project plan that is the very best project plan your organization has made so far. This will be your best practice project plan. The next time someone is making a project plan, the best practice project plan should be used as inspiration, and the goal is to make an even better project plan. If this succeeds, you'll have a new best practice project plan, and so on. This helps you ensure that quality continuously improves, but also that good experiences are taken advantage of.

Microsoft has made this a kind of hype. They announce the producers of the best practices as "champions." In our example we'll then have a project plan champion. This champion is the one to go to for advice or help on developing a project plan. This is a sensible way of doing things, we believe. This way, you'll have "leaders" in different areas, so everyone has responsibility by performing well. Besides this, you ensure that the "leaders" are those who have knowledge in the specific areas.

In our experience, this can work very well. We've seen best practices used as the most important tool in quality and management. We have, however, noticed that the thing that always makes difficulties is the announcement of new best practices and champions. It's important the announcement is made by an inde pendent committee, or one or two senior managers, who on a monthly basis collects best practice candidates from the managers in the organization. Otherwise, the announcement might be made by a mess of people insisting in having the new best practice, and you risk announcing the wrong new best practices.

We believe the concept is interesting and encourage you to go out and use it. You can use it for everything, not just project management issues.


Summary

You've now been introduced to MSF and seen its six models in detail. It's important to notice that MSF is a framework providing you with the tools and guidelines for what to address when developing projects. It's almost the opposite of traditional project methodologies that often provide you with a set of checklists and guide lines that must be strictly followed. MSF is flexible, scalable, and technology independent—this is exactly what makes it strong. It fits perfectly with UML and the .NET Framework, because it focuses on business instead of technology and approaches design through three perspectives, which is what UML is also designed to do. The iterative and fast-moving approach fits perfectly with the .NET Framework. MSF was created by Microsoft by gathering best practices from project experiences for over 20 years. We advise you to use MSF and UML in all of your projects. Those who have the skills of delivering project success through the use of MSF and UML are the most valuable in a project.


Appendix: Useful Links and References

Overview

In this appendix, you'll find useful references and links, including HTML links, books, and Microsoft Official Curriculum (MOC) material. The listings include cross-references to where the links and references are mentioned in this book (where applicable).

The links and references are organized into the following categories:

  • Unified Modeling Language (UML)

  • Visual Basic .NET (VB .NET)

  • C#

  • Microsoft Solutions Framework (MSF)

  • Visio

  • Visual Studio .NET (VS. NET) Enterprise

  • Miscellaneous


UML Links and References

Table A-1: UML Links and References
Link | Description | Chapter Reference
http://www.omg.org/uml | Object Management Group (OMG) UML area | Chapter 4, opening section
http://www.omg.org | OMG information on UML version 2.0 | Chapter 1, "ER and ORM Diagrams" sidebar; Chapter 3, "Going Public with OMG" section; Chapter 19, "UML Version Support" section
http://www.objectsbydesign.com/ tools/umltools_byPrice.html | UML products by price | Chapter 19, "Cost" section
http://www.magicdraw.com | Information about MagicDraw, a UML model- ing tool from No Magic | Chapter 12, "Evaluating VEA" sidebar
http://www-931.ibm.com/bin/ cp/driver.cgi;jsessionid=0000WPxGHNSI a2V3YavqxNuHUv1 :v387ggss?tn=28722_ 1OTR_1IN | UML for Database Design, a Webcast from IBM Rational |
http://www.omg.org/mda/webcast/ omg_webcast_presentation.htm | OMG Webcast presentation: "Build it Better, Faster, Cheaper," three Webcasts aimed at UML 2.0 |
http://webcast.cern.ch/Projects/ WebLectureArchive/deacon/vstr1.ram | Introduction to the UML, a 90 minutes long UML introduction Webcast |


VB .NET Links and References

Table A-2: VB .NET Links and References
Link | Description | Chapter Reference
http://msdn.microsoft.com/library/ default.asp?url=/library/en-us/ vbcn7/html/vaconNamespaces.asp | VB language concepts; namespaces | Chapter 4, "Packages" section
news://msnews.microsoft.com/ microsoft.public.dotnet.languages.vb | Official VB .NET language newsgroup | Chapter 6, "Choosing a Single Solution or Multiple Solutions" section
http://www.gotdotnet.com/team/vb/ VBSampleGuidelines.htm | VB .NET sample guidelines | Chapter 1, "Coding Conventions" sidebar


C# Links and Refreence

Table A-3: C# Links and References
Reference | Link | Chapter Reference
Official C# language .NET newsgroup | news://msnews.microsoft.com/ microsoft.public.dotnet.languages. csharp | Chapter 6, "Choosing a Single Solution or Multiple Solutions" section
C# and the .NET Platform, Second Edition, Andrew Troelsen (Apress, 2003; ISBN: 1590590554) | http://www.apress.com/book/ bookDisplay.html?bID=129 |
Programming C#, Gary Cornell (Apress, 2003; ISBN: 1590590007) | http://www.apress.com/book/ bookDisplay.html?bID=60 |
A Programmer's Introduc- tion to C#, Second Edition, Erik Gunnerson (Apress, 2001; ISBN: 1893115623) | http://www.apress.com/book/ bookDisplay.html?bID=83 |


MSF Links and References

Table A-4: MSF Links and References
Link | Description | Chapter Reference
http://www.microsoft.com/technet/ treeview/default.asp?url=/technet/ itsolutions/tandp/innsol/default.asp | MSF on TechNet | Chapter 2, "The Microsoft Solutions Framework Design Process" section
http://msdn.microsoft.com/practices | Microsoft patterns and practices | Chapter 2, "The Microsoft Solutions Framework Design Process" section
http://www.microsoft.com/technet/itsolutions/ techguide/msf/default.mspx | MSF materials and services | Chapter 19, "Comparing MSF to RUP" section; Chapter 20, opening section
http://www.standishgroup.com/sample_research/ PDFpages/ extreme_chaos.pdf | Extreme Chaos (Project Failure) article | Chapter 20, "Project Failure: Most Projects are a Failure" section
http://www-306.ibm.com /software/awdtools/rup | IBM Rational product overview | Chapter 2, "Gathering Requirements" section; Chapter 20, "Process Model" section
http://msevents.microsoft.com/CUI/ EventDetail.aspx?EventID= 1032249578&Culture=en-US | MSDN Webcast: Microsoft Solutions Framework overview: Leveraging Microsoft's best practices for planning, building, and deploying a variety of technology solutions— Level 200 |


Visio Links and References

Table A-5: Visio Links and References
Link | Description | Chapter Reference
http://www.microsoft.com/office/ visio/prodinfo/editions.mspx | Visio 2003 edition comparison | Chapter 1, "Taking a Quick Look at Visio" section; Chapter 12, opening section
http://www.microsoft.com/office/ visio/prodinfo/compare.mspx | VEA 2003 and Visio 2002 Professional comparison | Chapter 1, "Taking a Quick Look at Visio" section; Chapter 12, opening section
http://www.microsoft.com/downloads/details.aspx?FamilyID=3fb3bd5c-fed1-46cf-bd53- da23635ab2df&DisplayLang=en | Visio Viewer 2003 download | Chapter 1, "Taking a Quick Look at Visio" section; Chapter 12, "What About Creating Reports for the Other UML Diagrams?" section
http://www.microsoft.com/office/ visio/prodinfo/trial.mspx. | Visio 2003 trial version | Chapter 1, "Taking a Quick Look at Visio" section
http://www.amazingvisio.com/ visio_HowTo_BackgroundPage.htm | Visio background pages | Chapter 7, "Versioning Your Models" section
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devref/object.asp | Microsoft Visio object model | Chapter 19, "Object Model" section


VS .NET Enterprise Links and References

Table A-6: VS .NET Enterprise Links and References
Link | Description | Chapter Reference
http://msdn.microsoft.com/ vstudio/default.aspx | Visual Studio development |
http://msdn.microsoft.com/ vstudio/extend | Visual Studio Industry Partner Program (VSIP) | Chapter 10, "Choosing a Help Collection" section
http://msdn.microsoft.com/ vstudio/productinfo/roadmap.aspx#whidbey | Microsoft's upcoming developer tools | Chapter 12, "Evaluating VEA" sidebar
http://support.microsoft.com/ default.aspx?scid=kb;en-us;157714 | Visual SourceSafe log file storage | Chapter 11, "Database Folders and Files" section
http://msdn.microsoft.com/ vstudio/previous/ssafe/downloads/addon | Addons and components for Visual SourceSafe | Chapter 11, "Visual SourceSafe Extras" sidebar
http://www.sourcegear.com/sos/index.asp | SourceGear SourceOffSite tool | Chapter 11, "Visual SourceSafe Extras" sidebar
http://msdn.microsoft.com/ library/?url=/library/en-us/dnvss/html/vssbest.asp?frame=true | Microsoft Visual SourceSafe best practices | Chapter 11, "Best Practices for Using Source Control" section
http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/ vsintro7/html/vxgrfregisterproperty.asp | Visual Studio's Register property | Chapter 15, "Adding Windows Configuration Files" section
http://msdn.microsoft.com/ vstudio/downloads/tools/bootstrapper | VS .NET Bootstrapper download and overview | Chapter 15, "Including the .NET Framework" section


Miscellaneous Links and References

Table A-7: Miscellaneous Links and References
Topic | Link | Description | Chapter Reference
Application Center Test (ACT) | http://www.microsoft.com/applicationcenter | ACT version bundled with Microsoft Application Center 2000 | Chapter 13, "Introducing ACT" section
Code conventions | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconwhatiscommonlanguagespecification.asp | Common Language Specification | Chapter 1, "Coding Conventions" sidebar
Code conventions | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/ cpconvaluetypeusageguidelines.asp | Value type usage guidelines | Chapter 1, "Coding Conventions" sidebar
Code conventions | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/vsent7/html/vxconcodingtechniques.asp | Coding techniques | Chapter 1, "Coding Conventions" sidebar
COM+ | http://msdn.microsoft.com/ library/default.asp?url=/ library/en-us/cossdk/htm/pgservices_spm_5stu.asp | COM+ Shared Property Manager | Chapter 5, "Stateless Classes" sidebar
Custom help | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp.asp | Microsoft HTML Help 1.4 SDK | Chapter 10, "Creating Custom Help Topics" section
Database/data access | http://otn.oracle.com/tech/ windows/Oracle_dotnet.pdf | Oracle .NET data provider | Chapter 6, "Choosing Data Access" section
Database/data access | http://support.microsoft.com/ servicedesks/webcasts/wc060600/wc060600.asp?fr=1 | Webcast on applying normalization to your database | Chapter 2, "Modeling the Physical Database" section
Database/data access | http://www.mysql.com/articles/ dotnet/#ADO.NET | MySQL native .NET data providers | Chapter 6, "Choosing Data Access" section
Database/data access | http://www.apress.com/book/bookDisplay.html?bID=100 | Database Pro- gramming with VB .NET, 2nd Edition, Carsten Thomsen (Apress, 2002; ISBN: 1590590325) | Chapter 1, "Creating the Database Model Diagram" section; Chapter 2, "Modeling the Physical Database" section; Chapter 6, "Choosing Data Access" section
Database/data access | http://www.apress.com/book/bookDisplay.html?bID=63 | Database Pro- gramming with C#, Carsten Thomsen (Apress, April 2002; ISBN: 1590590104) | Chapter 1, "Creating the Database Model Diagram" section; Chapter 6, "Choosing Data Access" section
Database/data access | http://www.apress.com/book/bookDisplay.html?bID=81 | .COM and .NET Interoperability, Andrew Troelsen (Apress, 2002; ISBN: 1590590112) | Chapter 1, "Creating the Database Model Diagram" section; Chapter 6, "Choosing Data Access" section
Defect tracking | http://www.axosoft.com/OnTime.htm | Axosoft OnTime Defect Tracking and Feature Management tool | Chapter 6, "Defects" section
Defect tracking | http://www.compuware.com/products/ devpartner/ 1969_ENG_2003.htm | Compuware DevPartner TrackRecord application | Chapter 6, "Defects" section
Defect tracking | http://www.testingfaqs.org/t-track.htm | List of defect tracking tools | Chapter 6, "Defects" section
Deployment | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/dv_vstechart/html/vstchdeployingvsusing activedirectory.asp | Active Directory deployment | Chapter 15, "Deploying to Multiple Target Machines" section
Deployment | http://support.microsoft.com/default.aspx?scid=kb;en-us;327792 | Microsoft Systems Management Server deployment | Chapter 15, "Deploying to Multiple Target Machines" section
Deployment | http://www.wise.com/wfvsn.asp?bhcp=1 | Wise for Visual Studio .NET tool | Chapter 15, "Investing in a Third-Party Product" section
File attributes | http://support.microsoft.com/?kbid=224351 | Dsofile (tool for editing Office document properties from VB and ASP) download | Chapter 15, "File Attributes" section
Instrumentation | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconbrowsingthewmischema.asp | Windows Management Instrumentation (WMI) | Chapter 6, "Instrumentation" section
Instrumentation | http://www.microsoft.com/downloads/ details.aspx?-displaylang= en&familyid=80DF04BC-267D-4919-8BB4- 1F84B7EB1368&displaylag=en | Enterprise Instrumentation Framework (EIF) download | Chapter 6, "Instrumentation" section
Internationalization and Localization | http://www.apress.com/book/bookDisplay.html?bID=62 | Internationalization and Localization Using Microsoft .NET, Nick Symmonds (Apress, 2002; ISBN: 1590590023) | Chapter 15, "Adding Windows Satellite Assemblies" section
JavaScript | http://www.oreilly.com/catalog/ jscript4/index.html | JavaScript: The Definitive Guide, 4th Edition, David Flanagan (O'Reilly & Associates, 2001; ISBN: 0596000480) | Chapter 13, "Introducing ACT" section
.NET Framework | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconapplicationdomainsoverview.asp | Application domains overview | Chapter 15, "Setting Up the Remote Application" section
.NET Framework | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/cpgenref/html/cpconFinalizeDispose.asp | Finalize and Dispose implementation | Chapter 17, "Setting Operation Types and Adding Operations" section
.NET Framework | http://www.microsoft.com/downloads/ details.aspx?familyid=262D25E3-F589-4842-8157-034D1E7CF3A3&displaylang=en | Localized.NET Framework Version 1.1 redistributable packages download | Chapter 15, "Localized .NET Framework" section
Rational Unified Process (RUP) | http://www-106.ibm.com/ developerworks/rational/library/354.html | A simplified approach to RUP | Chapter 19, "Comparing MSF to RUP" section
Rational Unified Process (RUP) | http://www-136.ibm.com/ developerworks/rational/products/rup | RUP resources | Chapter 2, "Gathering Requirements" section; Chapter 19, "Comparing MSF to RUP" section; Chapter 20, "Does MSF Work with UML, and VB .NET or C#?" section
IBM Rational XDE | http://www.rational.net | Rational Developer Network | Chapter 18, "Learn More About Rational XDE" section
IBM Rational XDE | http://www-106.ibm.com/ developerworks/rational/library/1053.html | Free Rational Developer Network trial membership | Chapter 18, "Learn More About Rational XDE" section
IBM Rational XDE | http://www-136.ibm.com/ developerworks/rational | Technical Resources and best practices for the Rational software platform | Chapter 18, "Learn More About Rational XDE" section
IBM Rational XDE | http://www14.software.ibm.com/ webapp/download/preconfig.jsp?id=2003-09-18+15%3A02%3A18.447448R&cat=s wdev&fam=&s=c&S_TACT=TrialsAn dBetas&S_CMP= | Rational XDE trial download | Chapter 18, "Learn More About Rational XDE" section
Registry Editor | http://www.microsoft.com/ windows2000/en/advanced/help/ under_stand_reged.htm | Overview of the Registry Editor | Chapter 15, "Registry Editor" section
Sample code | http://www.apress.com/book/download.html | Download this book's sample code and other information |
Security | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconhowaspnetsecurityworks.asp | How ASP.NET security works | Chapter 15, ".NET Framework Security Mechanisms" section
Security | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/ cpconintroductiontocodeaccess security.asp | Introduction to code-access security | Chapter 15, ".NET Framework Security Mechanisms" section
Security | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/cpguide/html/cpconintroductiontorole- basedsecurity.asp | Introduction to role-based security | Chapter 15, ".NET Framework Security Mechanisms" section
Security | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconstrong- namedassemblies.asp | Strong-named assemblies | Chapter 15, "Strong Names" section
Security | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dotfuscator/dotf3rax.asp | Obfuscation introduction | Chapter 15, "Obfuscation" section
Security | http://msdn.microsoft.com/library/default.asp?url=/workshop/security/authcode/ authenticode_ovw_entry.asp | Authenticode overview and tutorials | Chapter 15, "Authenticode" section
Security | http://msdn.microsoft.com/ msdnmag/issues/01/02/CAS/default.aspx | Code-access right enforcement | Chapter 15, "Application Download Cache" section
Security | http://www.apress.com/book/bookDisplay.html?bID=104 | .NET Security and Cryptography, Jason Bock et al (Apress, 2002; ISBN: 1590590538) | Chapter 15, ".NET Framework Security Mechanisms" section
Setup | http://www.microsoft.com/ downloads/ details.aspx?FamilyId=BF253CFD-1EFC-4FC5-BA7E- 6A6F21403495&displaylang=en | .NET Framework Setup.exe Bootstrapper sample | Chapter 15, "Including the .NET Framework" section
Testing | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnbda/html/ bdadotnetarch081.asp | Tools for capacity planning | Chapter 6, "Testing" section
Testing | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvsent/html/ foodmovers6.asp | Instrumentation, testing, and deployment information | Chapter 6, "Testing" section
Testing | http://www.nunit.org | NUnit information | Chapter 6, "Testing" section
Testing | http://www.xprogramming.com/testfram.htm | Unit testing, Beck Testing Framework | Chapter 6, "Testing" section
VBScript | http://www.oreilly.com/catalog/vbscriptian2/ index.html | VBScript in a Nutshell, 2nd Edition, Paul Lomax et al (O'Reilly & Associates, 2003; ISBN: 0596004885) | Chapter 13, "Introducing ACT" section
Versioning | http://llamasery.com/forum/index.php?s=9a57b0a197c4b88367 40ffeaba49c491&showtopic=3067 | Article about versioning | Chapter 15, "Application Versioning" section
Versioning | http://msdn.microsoft.com/ library/default.asp?url=/library/en-us/cpguide/html/cpconassemblyversioning.asp | Assembly versioning | Chapter 15, "Application Versioning" section
Versioning | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/version.asp | Windows Installer version | Chapter 15, "Application Versioning" section
Versioning | http://nenya.ms.mff.cuni.cz/ publications/Gergic-Versioning.pdf | Versioning model for component- based software assembly | Chapter 15, "Versioning" section
Versioning | http://www.creativyst.com/Doc/ Std/StableSW/v10a/StabSW01.htm | Creativyst Software stability ratings | Chapter 15, "Application Versioning" section
Versioning | http://www.lgc.com/resources/Software%20Version%20Scheme.doc | Landmark's software numbering scheme | Chapter 15, "Application Versioning" section
Visual Basic 6 | http://support.microsoft.com/default.aspx?scid=http://support.microsoft.com:80/ support/kb/articles/Q192/4/ 61.ASP&NoWebContent=1 | Download runtime files | Chapter 15, "Adding Windows Configuration Files" section
Windows Distributed Internet Applications Architecture (Windows DNA) | http://www.apress.com/book/bookDisplay.html?bID=44 | A Programmer's Introduction to Windows DNA, Christian Gross (Apress, 2000; ISBN: 1893115178) | Chapter 2, "The Windows DNA Approach" section
Windows Installer | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsintro7/html/ vbconwhatyouneedtoknowaboutmi crosoftwindowsinstaller.asp | Windows Installer introduction | Chapter 15, "The Microsoft Windows Installer" section
Windows Installer | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/ property_reference.asp | Windows Installer property reference | Chapter 15, "Conditions" section
Windows Installer | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/ conditional_statement_syntax.asp | Windows Installer conditional statement syntax | Chapter 15, "Conditions" section
Windows Installer | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsintro7/html/ vbconwhatyouneedtoknowaboutmi crosoftwindowsinstaller.asp | Windows Installer redistributable for Windows 95, 98, and Me download | Chapter 15, "The Microsoft Windows Installer" section
Windows Performance Counters | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/counter/default.asp | Windows 2000 Performance Counters for analyzing Web server and application performance | Chapter 13, "Setting Test Properties" section
Windows shell | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/ programmersguide/ shell_basics/ shell_basics_extending/ fileassociations/fa_verbs.asp | Verbs and file associations | Chapter 15, "File Types Editor" section
XML editing | http://www.xmlspy.com | xmlspy, the world's leading XML editor | Chapter 8, "Editing an Existing Enter- prise Template File" section


Index

A

Accessibility requirements (Section 508), 41
ACT (Application Center Test), 537–564
computer roles, 538–539
creating a test, 552–555
cutting a test short, 560–561
introduction to, 537–545
opening, 540
recording a test, 553–554
running a test, 558–561
stand-alone, 539–541
test duration, 556
test report categories, 562–564
test scripting code, 555
users and groups, 546–549
using to establish a baseline, 537
using in VS .NET IDE, 543–544
ACT controller, explained, 539
ACT group, creating, 547
ACT project, creating, 543
ACT project environments, 545
stand-alone, 545
VS .NET IDE, 545
ACT project files, 542, 544
ACT project properties
setting, 549–552
stand-alone, 549
VS .NET IDE, 549
ACT Project Properties dialog box
Debugging tab, 551–552
General tab, 550
ACT Test Properties dialog box, 556–558
Counters tab, 557–558
General tab, 556
Users tab, 557
ACT test reports, 562–564
Additional Network Statistics category, 564
Errors Counts category, 564
examining, 561–564
Properties category, 563
Response Codes category, 564
Summary category, 564
Summary Overview category, 563
Test Run Graph category, 563
ACT Test Results dialog box in VS .NET IDE, 561
ACT UI with project opened, 541
ACT users
creating, 547–548
deleting, 549
Action State shapes, on an activity diagram, 146
Actions category (Dynamic Help), 385
Activations (on sequence diagrams), 130–131, 134
Activities, 100–101, 145–146
Activity diagrams, 100–101, 144–150
Action State shapes on, 146
activities, 145–146
Decision shape on, 149
decisions on, 148–150
elements of, 144
state on, 148–149
summary of, 150
swimlanes on, 145
transitions on, 146–147
Actor lifeline, sequence diagram with, 129
Actor notation (stick figure), 95, 107
Actors (on use case diagrams), 107–112
vs. business actors, 108
defined, 53
generalizing, 108, 110–111
identifying preliminary, 668–669
list of typical, 108
relationships between, 111, 112–115
ACTSamples.act project, 554
Add Dialog box (user interface), 601
Add New Item dialog box, 276, 378–379
configuring, 339–349
project ELEMENT nodes for, 344
project item ELEMENT nodes for, 342–343
.vsdir file and, 284–286
Add New Project dialog box (VS .NET), 223, 273, 275, 347, 380–381, 586
Add Project dialog box, 339–349
Add Project Output Group dialog box, 609–610
Add or Remove programs control applet, 620
Add to SourceSafe Project dialog box, 481–482
Add User dialog box, in VSS Administrator, 451
Admin user account password, 434
Administrative installation, 658
running, 650–651
starting, 650–651
uninstalling, 651
ADO.NET, 221
AItem child node of Attributes node, 404–405
AItem node of Context node, 396
and CTXTATTRIBUTE node, 414
Name attribute, 406, 413–414
Value attribute, 405–406, 413–414
Analysis baseline, 872–874, 876
Analysis paralysis, 858
Analyze (command-line utility), 456–457
Analyze help window, with command-line switches, 457
Analyzer Wizard, 570–573
Analyzing components and events,
deciding on, 576–577
Analyzing data, 580–583
Analyzing distributed application
performance, 565–583
Analyzing performance of Web
applications. See ACT
Analyzing similarities in development
blocks, 78
Animated icon, 392
App.config file, with a dynamic property, 229
Application deployment, 585–662
Application download cache, 636, 657–658
Application Model (MSF), 893–894
Application monitoring, 231
Application performance, analyzing, 565–583
Application perspective (MSF), 896
Application prototype (enterprise templates), 249–291
Application versioning, 641–642
Approve and Validate Time Entries
class diagram, 728–730
sequence diagram, 713–716,731
use case, 694–696
Archive Wizard (VSS), 459–462
Archiving VSS databases and projects, 457–463
ASP.NET applications, deploying, 621–630
ASP.NET Page stereotype, 208
ASP.NET Web Service, for enterprise template project, 274
Assemblies, 187, 617–618, 641, 782–783
Assembly attributes to file properties mapping, 618
Assembly information file, 617
Assembly with a strong name, compiling, 782–783
Assembly versioning, 641
Association relationship (UML 1.4), 823
Association Role shape (collaboration diagram), 140–141
Associations, 113
collaboration diagram with, 142
configuring menus using, 353–355
configuring the toolbox using, 364–365
to disable a menu or menu item, 354
to disabled a toolbox item, 365
static structure diagram with, 141
Asynchronous calls, explained, 131
Asynchronous messages, explained, 132
ATM (automated teller machine), 95
Atomicity, of attributes, 65
Attribute list for Product business object, 66
Attributes, 65–66, 159–161
as nouns, 65
as properties, 617
identifying, 66–67
viewing, 415, 417–419
Attributes node of Context node, 396
Audit trail, source control for, 424
Authentication, securing files using, 433–434
Authenticode, 635
Auto deployment, 651–658
Automatic code generation, 499–513
Automatic item merge message (VSS), 489


Index_B

Team LiB

Index

B

Bad design
cost of, 46–49
criteria for, 45–46
Banner logo, 639–640
Base class, in OOP, 767
Baselines, 582
analysis baseline, 872–874, 876
establishing, 537
optimization baseline, 873–874
rationalization baseline, 875–876
research baseline, 872, 875
specification baseline, 876–877
Behavior diagrams, 97–101
Behavioral (dynamic) models (UML), 105–151
Binary association, 174–178
Body Search test (ACT), 555
Bonus class dependency relationship, 179
Booch, Grady, 88, 90
Booch Development Method, 90–91
Booch diagrams, types of, 90
Books class, on UML diagram, 511
Boolean type, 17–18
Bootstrapper option (Windows Installer), 605
Boundary objects, explained, 58
Browser Type test (ACT), 555
Budget (project), 68, 868
Bugs (software defects), 232
Build output, 647
Bulletin board, using the Task List as, 438
Business, separating from technology, 839–840
Business actors, 107–109, 896
vs. actors, 108
with generalization (inheritance), 110–111
with stereotypes, 112
Business analysis, explained, 108
Business facade, for enterprise template project, 274
Business facade project, 254
Business goals, 68, 864–865
Business modeling, 243, 677
Business object attribute list, 66
Business object candidates, 59, 64
discarded, 65
retained, 65
Business object model, 66–67
Business objects, identifying, 58–59, 64–65
Business perspective (MSF), 895–896
Business processes
defined, 51, 144
optimizing, 64–66
Business rules, for enterprise template project, 274
Business services, 75, 894
Business Use Case stereotype, 118
ByVal, 17


Index_C

Team LiB

Index

C

C# class, creating, 18–19
C# code
generated for Customer class, 157
generating for Logon class, 19–21
C# code preview for GetList operation, 167
C# code template settings in the Registry, 519
C# Distributed Application template, 251
C# language
learning, 217
links and references, 903
programming in, 216
C# project, planning, 213–234
C# Simple Distributed Application template, 251
C++, programming in, 216
Calculation service, 63
Car object expressed using UML, 86
CATEGORIES first-level container, 337
CATEGORIES node, 301
CATEGORY node of ELEMENTS node, 337
CCW (COM Callable Wrapper), 567
CEmployee class code, 730
Central database, 426
Change control, 244
Change request form, 80, 244
Change requests, formal (written), 80, 244
Change Source Control dialog box (VSS), 484
Check In dialog box (VSS), 475–476
Check In Now option (VSS), 441, 475–476
Check Out dialog box (VSS), 470
Check Out Now option (VSS), 441, 471, 470
Chen, Dr. Peter, 22
Choose Project to Archive dialog box (VSS), 458
Class attributes, 159–161
Class destructor, 163
Class diagrams, 3, 96–97, 153–182, 198
based on sequence diagrams, 238
building, 716–730, 749–767
with CEmployee class, 728
classes on, 158–174
creating, 716–730, 749–767
with database table and relation, 724
elements of, 154
with a form on an ASP.NET page, 726
generating code for, 767–778
of ITREmail class, 732
need for, 675
packages on, 154–158
physical, 754–767
relationships on, 97, 174–182
reverse-engineered table on, 39
starting, 749–751
with updated class, 13
Class inheritance. See Inheritance
Class instantiation, explained, 170
Class lifeline, sequence diagram with, 128–129
Class operations (methods), 161–174
Classes (VB .NET)
adding to a diagram, 510–511
adding to a project, 504–506
on class diagrams, 158–174
creating, 7–14
creating in C#, 18–19
diagramming complex, 678
generating C# code for, 19–21
generating VB .NET code for, 14–17
modeling, 719–730
parts of, 159
reverse-engineered, 510
Classic ADO, 221
Classic ADO library, 334
Classifier, defined, 128
Classifier Role shape, on collaboration diagram, 140
ClassImpl C# default template, 528
ClassImpl code template, 521, 525
ClassImpl VB .NET template, 527
Clean Up Local Temporary Files Directory dialog box, 466
Client role (ACT), 539
Clients, VSS, 426–427
Client/server architecture of VSS, 425–433
CMDID element MENU element, 350
Codd, Edgar F., 73
Code Editor, with Microsoft Access DDL script, 34–35
Code generation summary, 21
Code generation types
Visio supported, 814–815
XDE supported, 815
Code pane of Output window, 506
Code Preview dialog box, 527–528
Code preview for element with programmatic error, 518
Code skeleton, generating from UML diagrams, 500
Code template settings
in Preferences dialog box, 519
in the Registry, 519
Code templates
default, 520–524
macros for use with, 522–523
modifying, 524–528
using, 518–528
in XDE, 805–809
Coding conventions, 10–11
Coding the project, preparing for, 215–220
Coffee Inc. example solution, 739–787
background story, 739
class diagram, 749–767
gathering requirements, 740–742
sequence diagram, 742–749
use cases, 740
in VS .NET IDE, 769
Collaboration diagrams, 91, 98–99, 139–144
Association Role shape on, 140–141
with associations, 140–142
Classifer Role shape on, 140
elements of, 139
links, 140–142
messages, 143
Multi-Object shape on, 140
objects, 140
vs. sequence diagrams, 126
summary, 144
Collection filters, 572, 574–578
custom, 575–576
predefined, 575
Collections, modeling, 778–781
Column Properties dialog box, Data Type tab, 27
Columns category page, Database Properties window on, 26
COM applications, creating, 783–785
COM component
adding a reference to, 785–786
event collection and analysis, 567
identifying in a policy file, 333–334
that is not a type library, 334
COM Interop, 221
COM Interop assemblies, 333–334
COM+ components, 60
building, 63
creating and using, 781–786
explained, 187
with ObjectControl interface, 196
COM+ runtime environment, ObjectControl interface, 195
Command-line shell, 448
Command-prompt executable, 448
Communicates relationship, 113–114, 204
Communication, in enterprise development, 898
Communication failure (project team), 843
Communication plan, 80
Complex classes, diagramming, 678
Complex data type definition, 268
Component Designer (canvas), 254
Component diagrams, 102, 187–200, 732
code generation from, 196–200
component element, 189
dependencies on, 191
elements of, 188
interfaces on, 192–196
node element, 189–191
Component element (on component diagrams), 189
Component file, 254
Component reference name in Properties window, 335
Component Services dialog box, new component in, 784
Components
acceptable performance of, 582
company standards for, 293
on deployment diagrams, 202–204
explained, 187
key properties of, 189
third-party, 677
Components to analyze, deciding on, 576–577
Components category of UML Node Properties dialog box, 190
ComponentStop event, 583
Conceptual design (MSF), 50, 51–56, 60, 214, 871–874
Conceptual name of table entity, 26
Configuration, explained, 589
Configuration file types, 226
Configuration files, 226–229
Configuration Manager, 648
Confirm User Deletion dialog box (VSS), 451
Conflicting Modifications Detected dialog box, 442
Connection points on UML shapes, 113
Connectors, defined, 102
Constraints
categorizing physical, 69–70
configuring menus using, 351–353
configuring toolbox using, 363–364
to disable a menu or menu item, 351
to disabled a toolbox item, 363–364
examples of physical, 71
menu item disabled by, 353
policy file global, 313–314
CONSTRAINTS element, 351, 363
CONSTRAINTS node, 299, 302, 313–314, 317
Constructor, explained, 170
Context element, 403
Context file, 406
with context node, 404
described, 398
CONTEXT node in ELEMENTS node, 301, 394–396, 406–407, 409
of DynamicHelp, 389
in a policy file, 407, 410, 412
Contingency plan, 891–892
Control flow transitions, explained, 147
Control objects, explained, 58
Control Properties dialog boxes, 228
Controlled units, XDE, 821–822
Copy Project dialog box, 625
Copy Project feature, 624–625
Core iteration, explained, 215
Cost
of bad design, 48
of UML products, 824–825
Counters tab of ACT Test Properties dialog box, 557–558
Create Local Project from SourceSafe dialog box, 482
Create Personal Report use case, 699–701
Create Totals Report use case, 698–699
Crow's feet notation, on an ER diagram, 22
CTS (common type system), 18
CTS compatible types, 18
CTXTATTRIBUTE node of CONTEXT node, 396, 404, 411, 416
with AItem node, 414
NAME and VALUE nodes, 414
CTXTKEYWORD node in ELEMENT node, 394, 396, 402, 411, 413–414, 417
Current state assessment, 677
Current systems, analyzing and documenting, 52
Custom Actions Editor, 601–603
Custom enterprise template projects, 269–290
Custom help context file, 400
Custom help file
in Internet Explorer, 399
linking to policy file, 398
Custom help topic links
in Dynamic Help window, 413
filtering, 411–417
Custom help topics, 250, 383–422
associating with policy file, 397
compiling, 397
creating, 396–417
defining categories of, 399–401
in Dynamic Help window, 408
HTML file for, 402–403
language-specific, 415
in Microsoft Document Explorer, 409
Custom role, 440
Customer class, 527
binary association with Shopping
Basket, 177
C# code generated for, 157
generalization relationship, 181
in Generate dialog box, 156
VB code generated for, 173
VB .NET code generated for, 157, 521
Customer class attributes, 160
Customer class with binary association, VB code for, 177
Customer class operations, 163
Customer interacting with the system, diagrammed, 55
Customer table columns, 72–73
Customers table, reverse-engineered, 39
CustomerStatus operation, VB code preview for, 169


Index_D

Team LiB

Index

D

DAP.tdl policy file, 251, 294
Data access
choosing, 221–222
for enterprise template project, 274
Data access project, 254
Data flow diagram, 89, 100
Data model for ITReady solution, 734–735
Data providers to access the DBMS, 221
Data services, 75, 894
Data type definition (complex), 268
Data type mapping, relationship to .NET, 524
Data Type tab of Column Properties dialog box, 27
Data types
creating, 717–719
IDL, 11
for lists, 781
Data validation against a schema (XML), 269
DataAccess project
reverse-engineered, 510
in Solution Explorer, 508–509
Database administration (VSS), 454–468
Database class diagram, creating, 751–754
Database element UML mapping, 734
Database locked in VSS Administrator, 455
Database locking, 454–455
Database model, 87
Database model diagram
adding a table to, 22–24
creating, 21–29
Database model error-check messages, 30–31
Database modeling, 21–39, 87
Database modeling alternatives, 736
Database organization (VSS), 427–433
Database Properties window, 28
on Columns category page, 26
Indexes page, 29
in Visio workspace, 23–24
Databases
generating, 30–36
modeling, 72–74, 733–736
reflecting inheritance in, 754
reverse engineering, 36–39
switching between in VS. NET IDE, 480
DataSet objects, 163, 222, 763–764
DBCS (Double Byte Character System), 27
DBMS (database management system), 221–222
DDL scripts, 21, 34–35
Debugging information, in Dynamic Help window, 417–419
Debugging tab of ACT Project Properties dialog box, 551–552
Decision shape
on activity diagram, 149,
on statechart diagram, 187
Decisions (on activity diagrams), 148–150
Decisions (on statechart diagrams), 185–187
DEFAULTACTION element, 412
DEFAULTACTION node, 299–300, 309–310, 317
DEFAULTSETTINGS node, 299–300, 308
Defects (software), 232–233
collecting information about, 232
reporting functionality, 232
tracking, 232–233
Delete dialog box (VSS), 479, 485
Dependencies (on component diagrams), 191
Dependency relationship, 178–179, 204
between VIPCustomer and Bonus
classes, 179
detecting, 626
for external systems, 692
Deployed items on target machine, 615–621
Deploying phase of Process Model, 883
Deploying services, 78
Deployment, 585–662
of ASP.NET applications, 621–630
explained, 585
of full setup package with patches, 660
to multiple target machines, 658
of new releases and patches, 659–661
no-touch, 651–658
options, 587–588
planning, 222–223
using third-party products, 661
Deployment diagrams, 78, 102–103, 200–205, 677
components on, 202–204
elements of, 200
nodes on, 201
relationship on, 204–205
relationship types, 204
with two different node types, 200
Deployment functionality, VS .NET, 661–662
Deployment permissions, 635–636
Deployment planning, 222–223
Deployment projects, types of, 586–588
DeploymentProject content, 615
DeploymentProject detected project dependencies, 611
Derived class, in OOP, 767
Design, 41–78, 214
concept of, 42–43
cost of bad, 46–49
criteria for bad, 45–46
criteria for good, 44–45
explained, 42–49
good vs. bad, 44–46
importance of, 43–44
logical, 57–67
optimizing, 77–78
physical, 67–78
user acceptance of, 56
Design goals, 68, 865
Design guidelines, from a business perspective, 45
Design patterns, 85, 809–810
Design process (MSF), 49–78, 871. See also Design
Design-time properties, 357
Destroy permanently option (VSS), 479, 485
Destructor operation, 171
Developer acceptance of sequence diagrams, 716
Developer knowledge and experience, 69
Developer skills, 77
Developing phase of Process Model, 881–882
Development iterations, 881
Development role (MSF), 849
Development strategy, 867–868
Development test phase, 881–882
Devices, defined, 102
Diagram view, 8
Diagramming high-level requirements, 53–54
Diagramming scenarios, 54–56
Difference Options dialog box (VSS), 486
Differences dialog box (VSS), 487
Display silent check in command (VSS), 440–441
Display silent check out command (VSS), 440–441
Dispose method, 762–763, 771
Distributed application performance, analyzing, 565–583
Distributed Application template, 251
Distributed Internet Applications Architecture, 61
DLL hell, 187
Document supporting objects, explained, 125
Document technical issues, explained, 125
Documentation (UML), 235–245
maintenance of, 238–240
updating in stages, 236
what to update, 236–238
when to update, 235–236
Documentation text box for Invoice use case, 116
Documentation tool, Visio as, 241
Documentation window, 116–117
Documenting a solution, 81, 237
DTS (Data Transformation Services) packages, 118
Duwamish 7.0 VB sample application
in Model Explorer, 513
reverse-engineered, 796
in Solution Explorer, 508
Duwamish-DataAccess.vsd, 509
Dynamic Help page of Options dialog box, 421
Dynamic Help window (VS .NET IDE), 383–389
arranging and sorting, 419–422
custom categories, 420–421
custom help topic in, 408
custom help topic link in, 413
display options, 420
displaying debugging information, 417–419
filtering in, 387
predefined categories, 384–385, 420
Dynamic Help window Debug mode, 415
Dynamic model (OMT), 89
Dynamic models (UML), 105–151
Dynamic properties
in app.config, 229
for a control, 228
explained, 226
Dynamic Properties dialog box, 228
Dynamic tests, explained, 538
DynamicHelp root node, 389


Index_E

Team LiB

Index

E

Edit Alias dialog box, 654
Edit Filter dialog box, 577
Edit New Filter dialog box, 575–576
Edit Template dialog box, 520, 524–525
Edit User dialog box (VSS), 452
EFPROJECT root element, 257, 270
EIF (Enterprise Instrumentation Framework), 231
ELEMENT action, 309–310
ELEMENT definition with MEMBERCONSTRAINT node, 319
ELEMENT definition of VB code files, 318
ELEMENT expressions, 338
ELEMENT identifiers, 321–336. See also IDENTIFIER node combinations
ELEMENT node, 295, 301–302, 315
project item PROTOTYPE for, 341
property constraints for, 358–359
ELEMENT nodes of policy file, linking, 409
ELEMENT prototypes, defining, 336–337
Elements
causing an error, 265
to describe a policy, 298
in a text file in XML format, 257
ELEMENTS node, 300, 316
ELEMENTSET node, 302, 316–317, 359
Empty Project template, 502
Enterprise, defined, 4
Enterprise applications, defined, 4
Enterprise architecture
Enterprise Model and, 897
examining, 52
Enterprise development, 4–5
Enterprise Model (MSF), 894–897
Enterprise modeling, explained, 5
Enterprise project ELEMENT nodes, 348
Enterprise solution structure and elements, 294
Enterprise template project (.etp) file, 254, 306
child elements, 258–263
creating, 271–283
editing, 269–271
solution created with, 253–254
VB Distributed Application, 255–265
Enterprise template project file hierarchy, 264
Enterprise template project layers, 254
Enterprise template project schema file, 265–269
Enterprise Template Project template, 251
Enterprise template projects, 225–226, 249–291, 293
adding to New Project dialog box, 284–290
adding project items, 275–276
adding projects, 272–275
adding wizards, 277–283
adding an XML Web Service, 280–283
advantages of, 249–250
associating a policy file with, 306–307
building blocks, 273–274
cleaning up, 283–284
custom, 269–290
icons for, 286–288
policy cache file, 283
prebuilt, 250–269
saving, 289–290
subfolders, 282, 284
.suo file, 283
Enterprise template solution, name and location values, 289
Enterprise templates, list of prebuilt, 251
EnterpriseServices namespace, 161, 781
Entity, defined, 25
Environment Variables dialog box, 449
Envisioning phase of Process Model, 861–870
ER (entity-relationship) diagrams (ERDs), 21–22
ERP (Enterprise Resource Planning) system, 95
Error checking, in Visio, 514–518
Event collection
pausing and resuming, 579–580
starting, 578
stopping, 579
Event List for a filter, 581
Event log, viewing, 580–581
Events
explained, 89
recommended for analysis, 577
Events to analyze, deciding on, 576–577
EXCLUDE node, 317
Excluded from Source Control option (VSS), 478
Expectations of target audience, 44–45
Extends relationship (UML 1.4), 115, 823
Extensibility, services and, 63
Extension points, explained, 117
External automation, libraries for, 819
External help, 386–388
External project, 739–787
External systems, dependency relationship for, 692


Index_F

Team LiB

Index

F

FEATURELINKS node, 302
FEATURES element, 349
FEATURES node, 301, 349, 361
adding menu items to, 350
adding toolbox items to, 362
Fields, of complex data type definition, 268
File attributes, 616–619
File-to-folder deployment, 593–594
File Properties dialog box, 616
File System Editor, 591–595
conditions, 595
target folders, 592–594
File types, UML code, 211
File Types Editor, 595–597
File types in Windows Folder Options dialog box, 596
Files, support for multiple users working on, 242
Filters
editing, 577
removing, 577–578
Finalize destructor, VB code preview for, 172
Finalize operation, 171
Flowchart diagram, 144
Focus centralization (project team), 844
Folder Options dialog box (Windows), 596
Folder Properties dialog box (Window XP), 653
Folder sharing, 434
Forked transition, 146
Forward engineering, 499, 500–506
Visio, 814
XDE, 815
Free-form diagram, 795
Function procedure, 17, 168
Functional model (OMT), 89
Functional specification, 878–879
Functionality, separating from goal, 839
Functionality diagrams, 95–97
Future visions, 69


Index_G

Team LiB

Index

G

GAC (Global Assembly Cache), 187
GENERAL element of EFPROJECT, 257
Generalization, 89, 182, 754
Generalization relationship (UML 1.4), 180–182, 823
Generalizing actors, 108, 110–111
Generate dialog box, 15, 173, 500–501, 726
with classes selected, 768
with Customer class, 156
with _Imageshrink interface selected, 197
Generate Wizard
opening page of, 32
second page of, 33
Generated code, controlling the look of, 518–528
Get Latest Version command (VSS), 474–475
Get method, 170
GetList operation, 163–165, 167
Getting Started category (Dynamic Help), 384
GLOBALS element of EFPROJECT, 257
Glyph node, 392–393
Glyph node attributes, 393
Goal, separating from functionality, 839
Goals for project success, 845–846
Good design, criteria for, 44–45
Graphical diagrams, explained, 125
Graphical symbols (UML), 93–103
Groups (in ACT), 546–549
Guard expressions, 150, 185–186
Guest user account password, 434
GUI (graphical user interface) design, 42
GUID element MENU element, 350


Index_H

Team LiB

Index

H

Help categories, predefined, 400
Help category (Dynamic Help), 384
Help collection, 388–389
Help context file format, 389–396
Help context links, setting up, 402–404
Help desk, 898
Help settings in VS. NET IDE Options dialog box, 388
Help topic references, adding to policy file, 406–410
Help topics (see also Custom help topics)
external or internal display of, 386–388
filtering, 404–406
in Microsoft Document Explorer, 386
High-level requirements, diagramming, 53–54
High-level use case diagram, 741–742
History dialog box (VSS), 492–493
History Options dialog box (VSS), 491–492
Hotfix package, deploying, 660–661
HTML help files, 402–403
HTTP (Hypertext Transfer Protocol) 1.1, 537
HTTP session cookies, 546


Index_I

Team LiB

Index

I

IBM, support for XDE and Rose, 825
IBM Rational Rose, 500
IBM Rational Rose XDE, 791
IBM Rational XDE. See XDE
Icons, integer values mapped to, 392–393
Icons for enterprise template projects, 286–288
ID column, 28–29
ID element of MENU element, 350
ID nodes, 301
of ELEMENT node, 315, 321
valid and invalid, 315
IDE. See VS .NET IDE
IDE integration, source control and, 424
IDE menus, configuring, 349–355
Identified items (policy file), 295, 315
IDENTIFIER node combinations, 322–336
CODE/Attribute, 322–323
CODE/Implements, 323–324
CODE/Inherits, 324
CODE/Kind, 323
CODEVARIABLE/TypeInherits, 324–325
CODEVARIABLE/TypeName, 325–327
HTMLELEMENT/Attribute, 328–329
HTMLELEMENT/Tag, 329
PROJECT/FileExtension, 329–330
PROJECT/Global, 330
PROJECT/Kind, 330
PROJECT/Property, 331
PROJECTITEM/FileExtension, 331
PROJECTITEM/Kind, 332
PROJECTITEM/Property, 332
Reference/FileName, 333–335
Reference/MajorVersion, 335–336
Reference/MinorVersion, 336
IDENTIFIERDATA node, 322, 359
IDENTIFIERS node, 302, 321
IDisposable interface, 762, 771
IDL (Interface Definition Language) data types, 11
Imageshrink interface (_Imageshrink)
class diagram with, 198
VB code generated for, 197
Implementation Class stereotype, 133
Implementation diagrams, 101–103
INCLUDE node of ELEMENTSET node, 317, 358
INCLUDE/PERMISSION combination, 309
Include relationship (UML 1.4), 823
Independent Developer role, 440
Indexed column, name column as, 29
Indexes page of Database Properties window, 29
Information perspective (MSF), 896
Infrastructure Model (MSF), 897–898
Inheritance (generalization), 180–182, 823
of business actors, 108, 110–111
explained, 89
reflecting in a database, 754
Inherits keyword, 772
Installation, testing, 649
Instrumentation, 231
Integer values mapped to icons, 392–393
Integration with existing environment
Visio, 816–817
Visio vs. XDE, 814–815
XDE, 818–819
IntelliSense, 303, 390
Interaction diagrams, 90, 98–99
Interactions, actors representing, 107
Interfaces, 76
on component diagrams, 192–196
defined, 102
shown in Model Explorer, 195
Internal help, 386–388
Internal project, 665–737
International formatting, 220
International sales service example, 739–787
Internet Explorer
custom help file in, 399
Visio VSD file in, 533
INTERSECT (TDL keyword), 338
Interviews, for requirements gathering, 52
Invoice use case documentation text box, 116
IsPolymorphic keyword, 182
Issues (software defects), 232
Items, types of in policy file, 295
Iteration plan, 81, 215
Iterations, explained, 215
ITReady class diagrams, 716–730
Approve and Validate Time Entries, 728–730
Maintain Time Entries, 727
Register Hours, 720–727
ITReady example solution, 665–737
background story, 665–667
capturing system requirements, 667–674
choosing UML models, 674–677
clarifying system requirements, 670–672
identifying high-level processes, 669–670
identifying preliminary actors, 668–669
IT infrastructure, 666
mandatory diagrams, 675–676
modeling use case diagrams, 678–701
other diagrams, 676–678
preliminary relationships, 672–674
system requirements, 666–667
UML data model for, 734
Visio data model for, 735
ITReady sequence diagrams, 701–716
Approve and Validate Time Entries, 713–716, 731
Maintain Time Entries, 709–713
Register Hours, 702–709
ITReady use cases
Approve and Validate Time Entries, 694–696
Create Personal Report, 699–701
Create Totals Report, 698–699
Maintain Projects, 690–692
Maintain Tasks, 691–694
Maintain Time Entries, 687–689
Register Hours, 684–687
Send Disapproved Notification, 696–698
user and sponsor acceptance of, 701


Index_J

Team LiB

Index

J

J#, programming in, 216
Jacobson, Ivar, 88, 91
JScript, dynamic tests using, 538


Index_K

Team LiB

Index

K

Key symbol, for primary key field, 87
Keywords and attributes of VS .NET items, viewing, 415, 417–419
Keywords child node of Context node, 394
KItem node, 394, 402, 414


Index_L

Team LiB

Index

L

Label control on a Windows form, 227
Langid folders, 282
Language-specific custom help topics, 415
Launch Conditions Editor, 604
LCID (language and code page code ID), 400–405
Legacy systems, 45
LegalRight class code, 777
Libraries, Visio vs. XDE, 819–820
License agreement, creating, 637–638
License Agreement dialog box, 638
with banner logo, 640
in German, 644
LinkGroup attribute of LItem node, 390–392, 395, 400, 404
LinkGroup node of DynamicHelp, 389, 390–394, 399
priority attribute, 390–391
priority values, 391
title attribute, 391
Links (on collaboration diagrams), 140–142
Links element, 403
Links node of Context node, 395–396
Links and references, 901–915
C#, 903
miscellaneous, 907–915
MSF, 904
UML, 902
VB .NET, 902
Visio, 905
VS .NET enterprise, 906
LItem element of Links element, 403
LItem node of Context node, 395–396
LinkGroup attribute, 395, 404
Priority attribute, 395
ToolTip attribute, 396
URL attribute, 395, 404
Living documents, 858
Local-access security, 434
Localization issues, 643–646
Localized .NET Framework, 646
Location property of Windows Form controls, 359–360
Lock Visual SourceSafe Database dialog box, 454
Locking, source control for, 423
Locking a database for maintenance, 454–455
Locking a UML model, 241–242
Log files, with version information, 428
Logical design (MSF), 50, 57–67, 874–875
attributes and relationships, 66–67
the big picture, 57–58
business objects, 58–59
.NET services, 60–61
optimizing business processes, 64–66
Windows DNA approach, 61–63
Logical modeling (Booch), 90
Logical validation, 30–31
Login ID (SourceSafe) text box, 443
Logon class, 9
generating C# code for, 19–21
generating VB .NET code for, 14–17
Logon processes, modeling, 7–21
Loyalty conflicts (project team), 844


Index_M

Team LiB

Index

M

Macros for use with code templates, 522–523
MagicDraw, 534
Maintain Projects use case, 690–692
Maintain Tasks use case, 691–694
Maintain Time Entries
class diagram, 727
sequence diagram, 709–713
use case, 687–689
Maintain Users use case, 741
Maintainability, 63, 69
Maintaining UML documentation, 235–245
Maintaining UML in a project team, 240–243
Maintenance
collecting information on new
functionality, 229–231
planning for, 229–233
responsibility for, 238–240
services and, 63
Manifests, explained, 187
Manufacturer support, and choosing a UML product, 825
MEMBERCONSTRAINT node, 319
MEMBERCONSTRAINTS node, 317
Members, of complex data type definition, 268
MENU element child elements, 350
Menu item disabled by a constraint, 353
Menu item names, 350
Menu items
adding to FEATURES node, 350
disabling, 351, 353–354
Menu names, 350
MENU node, 318, 353
MENU node definition for View Code
menu item, 318
MENUCONSTRAINTS element, 352
MENUCONSTRAINTS node, 314, 351
MENULINK node, 354
MENULINKS node, 353
Menus
configuring using associations, 353–355
configuring using constraints, 351–353
disabling, 351, 354
MENUS element, 349
Merge SourceSafe Version into Local Version dialog box, 489–490
Merge warning options (VSS), 489
Merging two versions of a project item, 424
Message, sequence diagram with, 134
Message calls, explained, 131
Message with message name (on sequence diagrams), 135
Message parameter setting (on sequence diagrams), 137
Message types (on sequence diagrams), 131–132
Messages (on collaboration diagrams), 143
Messages (on sequence diagrams), 131–137
Method category of UML Operations Properties dialog box, 763
Method overriding, 772–773
Method shadowing, 773
Method signature, defined, 767
MFC (Microsoft Foundation Classes), 49
Microsoft Access database validation, 30–31
Microsoft Access DDL script, 34–35
Microsoft Application Center Test .NET Edition, 537
Microsoft Document Explorer
custom help topic in, 409
help topics in, 386
Microsoft guidelines for coding conventions, 10–11
Microsoft .NET data provider for Oracle, 221
Microsoft Office 2003, 6
Microsoft Office Runtime 1.0 Type Library, 334
Microsoft support for Visio, 825
Microsoft Windows Installer, 604–606
Migration
from Rose to XDE, 802–805
XDE, 801–805
from XDE to Visio, 805
Milestones, 80, 858
Mitigation plan, 891–892
MOC (Microsoft Official Curriculum), 901
Model Documentation window (XDE), 819
Model Explorer (XDE), 818
with Duwamish 7.0 VB sample application, 513
interface shown in, 195
Top Package folder, 15–16
Modeling, explained, 5
Modeling classes, 719–730
Modeling collections, 778–781
Modeling a database, 21–39, 72–74, 733–736
Modeling different views, 243–244
Modeling a logon process, 7–21
Modeling the physical database, 72–74
Modeling the physical .NET services, 74–76
Modeling polymorphism, 773–775
Modeling primer, 3–39
Modeling tool (Microsoft). See Visio
Models. See UML models
Monitoring (application), 231
Morale, bad design and, 48
MSDN Library, 388
MSF (Microsoft Solutions Framework), 41, 826
as a framework, 833, 840
as a toolbox, 835
best practices, 899–900
contents of, 840–842
design process, 49–78
design process steps, 50
enterprise perspectives, 895–896
links and references, 904
missing tools, 835
phases and roles, 239
vs. RUP, 826–829
stabilizing, 828
using with software and technologies, 898
MSF 3.0, 833–900
MSF 3.0 design process, 41. See also Design process
MSF models, 841, 843–898
Application Model, 893–894
Enterprise Model, 894–897
Infrastructure Model, 897–898
Process Model, 668, 856–885
Risk Model, 885–893
Team Model, 843–856
MSF project life cycle, 841–843
building phase, 842
managing phase, 842–843
planning phase, 842
MSF project roles, 239, 439–440
conflicting, 853–854
development role, 849
driving milestones, 858
product management role, 846–847
program management role, 847–848
release management role, 852–853
test role, 849–850
user experience role, 851
MSF Readiness discipline, 70
MSSCCI (Microsoft Source Code Control Interface), 423
Multi-Object shape on collaboration diagram, 140
Multiplatform solutions, 216
Multiple solutions, 218
Multiple target machines, deploying to, 658
Multiple users working on the same files, 242
Multiplicity, explained, 778
Myopia, 46
MySQL, 221
MySQL.NET data provider, 221


Index_N

Team LiB

Index

N

N-tier applications, 4
Name column, as indexed column, 29
NAME node of PROPERTYCONSTRAINTS node, 357
Namespace, defined, 120. See also Packages
Nested properties, 359
.NET assemblies, explained, 187
.NET components
explained, 187
identifying in a policy file, 333–334
making visible to COM, 567
.NET configuration application, 636
.NET data provider to access the DBMS, 221
.NET developers, Visio for, 499
.NET Framework (Microsoft)
detecting, 630–631
including in setup, 632–633
issues of, 630–633
launch condition, 631
localized, 646
mapping UML code to, 209–211
security, 633–637
security mechanisms, 634
type library only components, 334
vs. UML elements, 150–151
warning for nonexistence of, 632
.NET language support, Visio and XDE, 820
.NET languages, unit-testing framework for, 224
.NET services
explained, 60
identifying, 60–61
modeling physical, 74–76
.NET types of operations, 161–162
.NET Web servers, stress-testing, 537
.NET Wizards, 637
New Code Template dialog box (XDE), 807–808
New constructor, 170–171, 773
New feature request, 231
New functionality request, 230
New Project dialog box, 252, 540, 543
adding an enterprise template project to, 284–290
enterprise project ELEMENT nodes, 348
enterprise template project icons, 286–288
.vsdir file and, 284–286
New Users Group dialog box (ACT), 548
NewEnterpriseHelp.doc, 403
NewEnterpriseHelp.htm custom help file, 397, 399
NewEnterpriseHelp.xml context file, 389, 401, 404–405
NewEnterprisePolicy.tdl file CONTEXT node, 407
NewEnterprisePolicy.tdl policy file, 306, 401, 407–408, 412, 415
NewTemplateProject.etp file, 306, 408
initial, 278
with Wizard reference, 279–280
NewWebService folder subfolders, 282
NewWebService.vbproj file, 281–282
No-touch deployment, 651–658
No-touch deployment stub, 655–656
Node element (on component diagrams), 189–191
Nodes (XML elements), 257
on deployment diagrams, 201
to describe a policy, 298
key properties of, 189–190
Normalization, 73
Northwind sample database, 36
Note shape with text, 138
Notes (on sequence diagrams), 138
NotInheritable keyword, 772
Nouns, attributes as, 65
NTFS vs. VSS, 424
NUnit unit-testing framework, 224


Index_O

Team LiB

Index

O

Obfuscation, 635
Object base class, 172
Object diagram (Booch), 90
Object flow transitions, explained, 147
Object In State shape, 148
Object model
OMT, 89
Visio vs. XDE, 819–820
Object-oriented software, 88–89
Object types, 58
ObjectControl interface of COM+ runtime environment, 195
class diagram with, 198
COM+ component with, 196
Objects, 88, 720
on collaboration diagrams, 140
on sequence diagrams, 126–129, 133–134
stateful or stateless, 148
ODBC .NET data provider, 221
OLE DB .NET data provider, 221
OMG (Object Management Group), 91–92
OMG committee, 91
OMT (Object Modeling Technique), 88–89
OMT steps, 89
OMT models, 89
OOP (object-oriented programming), 3
OOP inheritance, 182
OOP techniques, 767
OOSE (Object-Oriented Software Engineering), 91
OOSE method, 91
Operations (class), 161–174
adding to a class diagram, 758–767
.NET types of, 161–162
Operations category of UML Interface Properties dialog box, 193
Optimization baseline, 873–874
Oracle 8.1.7, 221
Oracle .NET data provider, 221
ORDER node, 299, 311–312, 317
Order process, tasks for performing, 55
ORM (Object Role Modeling), 22
ORM diagrams, 22
Output window, 30–31
Code pane, 506
showing semantic errors, 16
Source Control list in, 437–438
Overloading, explained, 767
Overloads keyword, 777
Overridable keyword, 182
Overrides keyword, 172, 773–774, 777
Overriding a method, 172, 767, 772–774, 777


Index_P

Team LiB

Index

P

Package notation, 118
Packages
on class diagrams, 154–158
creating, 719
in UML use case diagrams, 118–122
Packages diagram, 121
Parameterized collaborations, 810
Parameters category of UML Operation Properties dialog box, 194
Parts of the model, locking, 241
Passwords
for Admin and Guest user accounts, 434
maximum number of characters for, 27
Patches, deploying, 659–661
Path environment variable, 449
Path maps, in Rose, 804–805
Pending Checkins window (VSS), 436–437
Performance, 69. See also ACT
acceptable for a component, 582
analyzing, 565–583
establishing baselines for, 582
Performance counters, 557–558
Permissions, deployment, 635–636
Persistent objects, explained, 58
Phases and roles (in MSF), 239
Physical class diagram, 754–767
adding classes, 755–756
adding operations, 758–767
complete, 766
setting parameters, 757–758
Physical constraints
categorizing, 69–70
examples of, 71
Physical database, modeling, 72–74
Physical design (MSF), 50, 67–78, 875–877
choosing technologies, 68–72
database modeling, 72–74
deploying services, 78
.NET service, 74–76
optimizing system processes, 77–78
technology comparison matrix, 70–72
Physical modeling (Booch), 90
Physical name of table entity, 26
Physical .NET service, modeling, 74–76
Physical sequence diagram, 746–749
Physical validation, 30
Picture database diagram, 751–754
Place service, 60
Planned releases, deploying, 659
Planning deliverables, 867
Planning deployment, 222–223
Planning phase of Process Model, 870–877
Planning process, 79–81, 213–224
choosing data access, 221–222
designing the solution, 214
gathering requirements, 214
iteration plan, 215
planning deployment, 222–223
preparing for coding, 215–220
steps in, 213–214
testing, 223–224
Planning a project, 213–234. See also Planning process
configuration files, 226–229
enterprise template projects, 225–226
maintenance, 229–233
Policies
configuring VS .NET IDE using, 338–365
items that can be managed with, 338–339
Policy behavior, unexpected, 311
Policy file concepts, 293–297
Policy file contexts, 294–295
Policy file ELEMENT nodes, linking, 409
Policy file format and schema, 297–302
Policy file items, 295–296
Policy file loading error, 308
Policy File property, 297
Policy file scope, 296–297
Policy file skeleton, creating, 303–308
Policy file structure, 297
Policy files, 250, 293–381
adding first-level ELEMENTS node to, 316
adding help topic references to, 406–410
adding items to, 315–337
associating custom help topics with, 397
associating with enterprise template project, 306–307
changing from VS .NET IDE, 307
CONTEXT child node settings in, 407, 410, 412
creating and editing, 302–365
creating with a text editor or XML editor, 298, 302–365
default ELEMENT action, 309–310
default item policy, 300, 309
ELEMENT expressions, 338
ELEMENT identifiers, 321–336
ELEMENT prototypes, 336–337
global constraints, 313–314
global default behaviors, 308–314
grouping items, 337
IDE menus, 349–355
identifying COM or .NET components, 333–334
item ELEMENTSETs, 316–321
linking to custom help file, 398
overriding policies, 311
policy mode, 309–310
policy order, 311–313
prebuilt, 294
removing a reference to, 276–277
root and first-level nodes, 298–301
TDL nodes for use in, 366–376
TDL root node, 298–299
types of items in, 295
in use, 303
validation, 366
Policy reminders
fixing, 366
in Task List, 328, 360–361
Policy validation, 366
Policy validation errors, fixing, 366
POLICYMODE element of DEFAULTSETTINGS element, 412
POLICYMODE node, 299–300, 309–310
Polymorphism
explained, 89, 182
modeling, 773–775
Postconditions (use case), 116
Preconditions (use case), 116
Preferences dialog box, 781, 519
Primary Interop Assemblies folder, 333
Primary key, ID column as, 29
Primary key field, key symbol for, 87
Priority attribute of LinkGroup node, 390–391, 399
Priority attribute of LItem node, 395
Problem statement, 862–863
Process diagram, 583
Process Model (MSF), 856–885
deploying phase, 883
developing phase, 881–882
envisioning phase, 861–870
planning phase, 870–877
stabilizing phase, 882
Processes, 53
business processes, 51, 64–66, 144
focusing on, 838–839
UML notation for, 96
on use case diagrams, 115–118
Processors, 102
Product business object attribute list, 66
Product management role (MSF), 846–847
Program management role (MSF), 847–848
Program manager, explained, 239
Programmatic errors, 516–518
Programming languages
choosing, 216–217
development team skills in, 216
learning more than one, 217
with VSEA edition, 11
Project (see also Solution)
adding classes to, 504–506
adding to a solution, 502–504
adding to source control, 480–482
generated code added to, 502–503
open in VS .NET IDE, 313
Project budget, 68, 868
Project dependencies, detecting, 610–612, 626
Project ELEMENT nodes
for Add New Item dialog box, 344
for Add New Project dialog box, 347
Project failure, 837–838
Project file versions, file names of, 428
Project files, 254
Project group, vs. project team, 854
Project hierarchy (VSS), 432–433
Project item
ELEMENT nodes for Add New Item dialog box, 342–343
PROTOTYPE for an ELEMENT node, 341
valid, 340
Project item sharing, source control for, 424
Project management, 244
Project-oriented source control, 424
Project output, 609–615
categories of, 610
graphics files, 612–613
project dependencies, 610–612
Windows configuration files, 613–615
Windows satellite assemblies, 612
Project plan, 68, 879–881. See also Planning a project
Proect process, vs. project team, 834
Project process methods, 836–837
Project properties, 588–590
Project PROTOTYPE for an ELEMENT node, 345
Project rights assignment (VSS), 453–454
Project Rights tab of SourceSafe Options dialog box, 453
Project roles. See MSF project roles
Project success, goals for, 845–846
Project team, 867. See also Team Model (MSF)
maintaining UML in, 240–243
potential pitfalls, 843–844
programming language skills of, 216
vs. project group, 854
vs. project process, 834
roles and responsibilities, 844–854
working with Visio, 241
Project team development
Visio, 821
XDE, 821–823
Project tradeoff, 859–860
Project types, 223
choosing, 217–218
company standards for, 293
Projectschema.xsd file, 265–269
ProjItemVBCodeFile ELEMENT node for policy file, 407
ProjItemWebForm ELEMENT node, 412, 415–416
Properties
as attributes, 617
configuring, 355–361
design-time, 357
nested, 359
nodes used to control, 356
runtime environment–dependent, 356
Properties window, 335, 355, 589
Property constraints
for included ELEMENT node, 358
minimum definition for, 357
Property Pages dialog box for a setup project, 590
PROPERTYCONSTRAINTS node, 314, 356–357, 359
PROTOTYPES node of ELEMENTS node, 302, 336–337
Prototyping, 78, 302, 336–337
Proxy settings, 550
Public Function procedure, 168


Index_Q

Team LiB

Index

Q

Q&A-based use case diagram, 672


Index_R

Team LiB

Index

R

RAD (Rapid Application Development) method, 837
Rational Rose (IBM), 500
path maps, 804–805
Rose model, 803
Rose to XDE migration, 802–805
Rational Rose (Rational Software), 6, 88
Rational XDE (IBM). See XDE
Rationalization baseline, 875–876
RCW (Runtime Callable Wrapper), 333
Read-only, saving a UML model as, 241
Readiness discipline (MSF), 70
Readme.htm file, 507
READMESS.HTM file, 425
Real business objects, explained, 64–65
Receptions, defined, 132
Recovering a VSS database without Admin password, 467–468
Redoing, cost of, 47
References and links, 901–915
Reflecting inheritance in a database, 754
Register Hours class diagram, 720–727
Register Hours sequence diagram, 702–709
Register Hours use case, 684–687
Registry
changing settings in, 417–418
code template settings in, 519
Registry Editor, 417–418, 597–598
Relationship to .NET data type mapping, 524
Relationships
between actors, 111, 112–115
on class diagrams, 97, 174–182
defined, 66
on deployment diagrams, 204–205
identifying, 66–67
preliminary, 672–674
types of, 113, 174
in UML 1.4 use case diagrams, 823
use case diagram with, 674
Release management role (MSF), 852–853
Releases of software, finding out about, 229–231
Reliability of the solution, 45, 69
Remote-access security, 434
Remote application setup for no-touch deployment, 652–657
Remote components setup (VS .NET), 569
Report Preview, 530
Report types, 529
Reports
creating for UML diagrams, 529–533
elements of, 529
previewing, 530
Visio, 820–821
XDE, 821
Reputation, bad design and, 48
Requirements, diagramming high-level, 53–54
Requirements gathering (planning process), 51–53, 214, 740–742
REQUIRESURL element (enterprise template file), 264
Research baseline, 872, 875
Resource files, using, 219–220
Responsibility confusion (project team), 843–844
Restore Wizard (VSS), 463–465
Restoring a VSS database or project, 463–465
Return message on sequence diagram, 136
Return messages, 131, 136
Reusability, services and, 63
Reusable code, looking for existing, 219
Reverse Engineer button (Visio), 817
Reverse Engineer Wizard, 37–38
Reverse Engineer Wizard database tables review page, 38
Reverse-engineered C# form
in Visio, 814
in XDE, 815
Reverse-engineered class on UML diagram, 511
Reverse-engineered classes, 510–511
Reverse-engineered DataAccess project, 510
Reverse-engineered Duwamish 7.0 VB application, 796
Reverse-engineered table, on a class diagram, 39
Reverse engineering, 499, 507–513
of a built project, 511–512
of a database, 36–39
of a solution, 512–513
Visio, 814, 816–817
in VS .NET IDE, 816–817
XDE, 815
Revising, cost of, 47
Revision history, 868–869
Risk, explained, 885
Risk assessment, 888–890
Risk decreasing over time, 886
Risk Model (MSF), 885–893
content, 887–893
summary, 893
Risk Model steps, 888
analyzing and prioritizing risks, 891
control, 892
gathering lessons learned, 892–893
identifying risks, 890–891
planning and scheduling, 891–892
risk assessment, 888–890
tracking and reporting, 892
Risk statement, 866–867
Risk strategy, 886–887
Robots.txt file, 550
ROI (return on investment), 45
Roles (in MSF). See MSF project roles
Root folder
explained, 432
in Visual SourceSafe Explorer, 433
Root project, selecting, 458
Round-trip engineering
explained, 500
XDE, 815
RPC (Remote Procedure Call) bridge, 567
Rumbaugh, James, 88
Runtime environment-dependent properties, 356
RUP (IBM Rational Unified Process), 51, 826, 898
vs. MSF, 826–829
RUP transition, 828


Index_S

Team LiB

Index

S

Sales-force servicing example, 739–787
SalesCompanyUser class
generated code, 771–772
modified, 776
Samples category (Dynamic Help), 384
Save As dialog box
saving a model as read-only, 242
Web page option, 531
SBCS (Single Byte Character System), 27
Scalability, 63, 69
Schedule and budget, 868
Scheduling, 79, 868
Schema file used for policy files, 297
Scripts folder, 282
Section 508 design standard, 41
Securing default users, 434–435
Securing files, using authentication for, 433–434
Security, 69
implementing, 633–637
VSS, 433–435
Security and audit trail, source control for, 424
Security management, 852
Select Item in Project dialog box, 603
Semantic errors
explained, 16
in Output window, 16
in UML diagrams, 514–516
Send Disapproved Notification use case, 696–698
Sequence diagrams, 56, 98–99, 125–139, 701–716
activations on, 130–131, 134
with all use case tasks, 705
based on use case diagrams, 238
with class and actor lifelines, 129
class diagram based on, 238
with class lifeline, 128–129
vs. collaboration diagrams, 126
creating, 742–749
for customers and users, 749
elements of, 126
with an Employee object, 702
identifying objects and events, 702–716
with a message, 134
message with message name on, 135
message parameter settings, 137
message types, 131–132
messages on, 131–137
more IT-specific, 709
need for, 675
notes on, 138
objects on, 126–129, 133–134
for project team, 749
physical, 746–749
return message on, 136
summary of, 139
time-based, 126
Time Sheet object added to, 704
with two use cases, 711
with use case and login information, 707
user and developer acceptance of, 716
XDE, 797
Servers, VSS, 426
Service-based development, 76–77
Service candidates, 61
ServicedComponent class, 765, 767, 781
Services
as verbs, 60–61
concept of, 60
deploying, 78
identifying, 60–61
splitting up, 74–76
Services component of System.Web namespace, 333
Services list, 66
Session cookies, 546
Set method, 170
Setup attributes, 619–621
Setup and deployment options, 587–588
Setup and deployment projects, types of, 586–588
Setup folder URL (Windows Installer), 606
Setup packages, running, 649–651
Setup project
adding files to, 608–615
adding to solution, 607–608
adding to Web solution, 623–625
building, 647–649
customizing, 637–640
localizing, 643–645
Property Pages dialog box for, 590
Setup project editors, 591–604
Setup project file (.vdproj), 645
Setup project properties, 620
Shadowing, explained, 172
Shadowing/hiding a method, 773
Shadows keyword, 772–773, 777
Shape Display Options dialog box, 681
Shared Property Manager, 161
ShoppingBasket class, 177
Sign-off, 869, 882
Simultaneous browser connections (ACT test), 556
Single or multiple solution, 218
SKUs (stock-keeping units), 75
SLA (service-level agreement), 70
SMS (Microsoft Systems Management Server) deployment, 658
Socket request time-out, 551
Software defects, 232–233
Software releases, finding out about, 229–231
Software solution. See Solution
Software-testing solutions, 223–224
Solution (see also Project)
adding a project to, 502–504
adding setup projects to, 607–608, 623–625
adding to source control, 480–482
choosing single or multiple, 218
created with enterprise template, 253–254
documenting, 81
finding out about new releases of, 229–231
multiplatform, 216
name and location values for, 289
reliability of, 45
reverse engineering, 512–513
technologies in, 294
usability of, 44
Solution concept, 866
Solution design. See Design
Solution Explorer, 253, 339
ACT test results in, 561
DataAccess project in, 508–509
Duwamish 7.0 VB sample
application, 508
help topics in, 387
new enterprise template project in, 272
project files in, 254
Solution (.sln) file, 284
Solution items, policy file standards for, 293–294
Solution planning. See Planning process
Solution structure and elements. See Policy files
Solution templates. See Enterprise template projects
Solution for tracking time spent on projects, 665–737
Solution user options (.suo) file, 283
Source control, 243
best practices, 495–497
checking in frequently, 495–496
commenting all item check-ins, 496–497
unfinished items, 496
user naming convention, 497
uses for, 423–424
validating database integrity, 497
Source control applications, 423
Source control items, explained, 423
Source Control list (VSS), 437–438
Source Control menu (VSS), 435–436
Source Control Options (VSS), 439–445
General category, 439–442
SCC provider category, 442–445
Source control software, 242. See also VSS
SourceOffSite, 495
SourceOffSite Classic, 495
SourceSafe Options dialog box
General tab, 444, 465–466, 485
Integration tab, 445
Project Rights tab, 453
Specification baseline, 876–877
Sponsor acceptance of use cases, 701
SQL Server 7.0, 221
SQL Server .NET data provider, 221
Srcsafe.ini file, 434
Stabilizing, in MSF, 828
Stabilizing phase of Process Model, 882
Standard installation, running, 649–650
Standards, for components or project types, 293
State, defined, 101
State diagrams, explained, 89
State shape, 148
State transition diagram (Booch), 90
Statechart diagrams, 99–100, 106, 182–187
content of, 182
decisions on, 185–187
elements of, 183
states on, 183–184
transitions on, 184–185
Stateful classes, 161
Stateless classes, 161
Stateless objects, 148
States (on activity diagrams), 148–149
States (on statechart diagrams), 183–184
Static icon, 392
Static models (UML), 105, 153–211
Static structure diagrams (Visio), 3, 121, 141, 153, 500, 675
Stereotypes, 108, 111, 205–208
built-in, 206–207
business actors with, 112
user-defined, 207–208
Stick figure notation for an actor, 107
Storage, source control and, 424
Storage units, XDE, 821–823
String (VB .NET data type), 18
Strong names, for assemblies, 634–635, 782–783
Struct stereotype, 207
Structural diagrams (UML), 153–211
Sub procedure, 168
Subsystem, defined, 120
SUBTRACT (TDL keyword), 338
SuggestedBaseName field name, 288
Support Info dialog box, 620
Swimlanes (on activity diagrams), 101, 145
Symbols (UML), 93–103
Synchronization, XDE, 798–801
Synchronization policy properties, 799
Synchronization settings for an element, 800
System, defined, 120
System boundaries (on use case diagrams), 123–124
System management, 897
System objects, for enterprise template project, 274
System processes, optimizing, 77–78
System structure diagram, 123
System.DataSet, 163, 222, 763–764
System.EnterpriseServices namespace, 161, 781
System.Web.Services component, 333


Index_T

Team LiB

Index

T

Table
adding a database model diagram to, 22–24
defined, 25
Table entity names, 26
Table properties, setting, 25–26
Tagged values, explained, 117
Tags (XML elements), 257
Target audience, expectations of, 44–45
Task List
policy reminders in, 328, 360–361
in team development, 438
TDL (Template Description Language), 296
as an implementation of XML, 297
start tag and end tag, 299
white spaces, 315
TDL nodes for use in policy files, 366–376
TDL root node (policy file), 298–299
TDLSchema.xsd file, 297
Team. See Project team
Team Model (MSF), 843–856
best practices, 855–856
roles and responsibilities, 844–854
summary of, 854–856
Team Model roles
conflicting, 853–854
development role, 849
goals and, 853
product management role, 846–847
program management role, 847–848
release management role, 852–853
test role, 849–850
user experience role, 851
Technical details, 68
Technologies, 294
choosing, 68–72, 877–878
questions you must always ask, 71–72
separating from business, 839–840
Technology candidates, identifying, 72
Technology choice matrix, 877–878
Technology comparison matrix, 70–72
Technology perspective (MSF), 896
Templates (template projects), 223, 225–226, 251–253 . See also Enterprise template projects
Templates folder, 282
Test role (MSF), 849–850
Test Status dialog box, in ACT, 560
Testing, 223–224. See also ACT
Testing plan, 81
Testing user scenarios, 77
Third normal form (3NF), 73
Three-tier modeling, 76
Time, bad design and, 48
Time sheet example project, 665–737
Time sheet project Q&A, 730–733
TimeSheet class code, 727, 730
TimeSheet class Save operation, 723
Toolbox
configuring, 361–365
configuring using associations, 364–365
configuring using constraints, 363–364
Toolbox items
adding to FEATURES node, 362
disabling, 363–365
TOOLBOXCONSTRAINTS node, 314, 363
TOOLBOXITEMS element, 361–362
TOOLBOXITEMS node, 361–362
TOOLBOXLINKS node, 364–365
TOOLBOXLITEMS node, 364
ToolTip attribute of LItem node, 396
Top Package, 109, 120
Top Package folder (Model Explorer), 15–16
TopPackage solution, 505
TopPackage1 project, test class added to, 505
ToyCar Enterprise System, 120
packages diagram, 121
structure diagram, 123
Tradeoff matrix, 860, 883–885
Tradeoff triangle, 860
Transitions
on activity diagrams, 146–147
in RUP, 828
on statechart diagrams, 184–185
types of, 147
Type libraries, 819–820
TYPE node of ELEMENT node, 321–322


Index_U

Team LiB

Index

U

UI control properties, 226
UI projects, 254
UML (Unified Modeling Language), 41, 50–52, 85–103
areas in which it can be used, 92
history of, 88–91
introduction to, 85–87
links and references, 902
maintaining in a project team, 240–243
packages in, 118–122
success of, 93
using, 92–93
UML 1.2 notation, 514
UML 1.4 use case diagram relationships, 823
UML 2.0, expected changes in, 824
UML Association End Properties dialog box, 780
UML Association Properties dialog box, 176, 682, 779
UML Association Role Properties dialog box, 142
UML class, notation for, 97
UML Class Properties dialog box, 9, 127, 162
with Cuwith Customer class attributes, 160stomer class operations, 163
with Customer class properties, 158
showing attributes, 10
stereotypes in, 206
when class has no operations, 199
UML Classifier Role Properties dialog box, 127, 703
UML code, mapping to .NET, 209–211
UML code file types, 211
UML Code Generation dialog box, 505–506
UML Component Properties dialog box, 203, 733
UML data model for ITReady solution, 734
UML Datatype Properties dialog box, 717
UML diagrams, 95–103
for complex requirements, 676–677
creating reports for, 529–533
deciding which to create, 676–678
generating a code skeleton from, 500
mandatory, 675–676
reverse-engineered class on, 511
semantic errors in, 514–516
specifying operations and parameters, 11–13
starting and adding classes to, 7, 8–10
viewing, 582–583
UML documentation, 235–245
maintenance of, 238–240
updating in stages, 236
what to update, 236–238
when to update, 235–236
UML elements, vs. .NET, 150–151
UML Interface Properties dialog box, 193
UML Message Properties dialog box, 135
UML Method Properties dialog box, 775
UML modeling of a database, 734–735
UML modeling tool. See Visio
UML models, 3, 93–94. See also UML diagrams
behavioral models, 105–151
categories of, 94, 105
generating, 499–513
locking, 241–242
maintaining views of, 243–244
saving as read-only, 241
saving as a Web page, 531–532
situations causing updates to, 240
static models, 153–211
updating after deployment, 244
versioning, 243
which to use, 94, 674–678
UML to .NET mapping, 151
UML Node Properties dialog box, 190, 204
UML notation, 93–103
3-D box, 103
box with rounded corners, 100
elongated oval, 100
oval, 96
rectangle, 97
solid arrow, 100
solid box, 100
solid circle, 100
solid line, 97
stick figure, 95
UML Operation Properties dialog box, 135, 164
with code generation settings, 166
for Customer Status operation, 169
with customer Type ID, 165
Method category, 763
Parameters category, 194
showing parameters, 12
UML products
manufacturer support of, 825
price of, 824–825
summary of comparisons, 829
XDE and Visio comparison, 813–825
UML profiles, 824
UML Report preview window, 530
UML sequence diagrams. See Sequence diagrams
UML shapes, connection points on, 113
UML standard, 91–92
UML Static Structure Report, 530
UML Stereotypes dialog box, 208
UML structural diagrams, 153–211
UML tools, 6
UML Transition Properties dialog box, 150
UML update responsibilities, table of, 239
UML Use Case Properties dialog box, 116–117, 685, 687, 690, 693–695, 697–698, 700
UML version 1.2, 105
UML version support, 823–824
Undo Checkout command (VSS), 472
Undo Checkout dialog box (VSS), 473
Undoing default text modifications, 645–646
Unicode format text files, 425
Unidentified element, explained, 301
Unidentified items (policy file), 295
Uninstalling, 650
UNION (TDL keyword), 338
Unique primary key, 87
Unique row ID, 28
Unit testing, 224
Unit testing framework for .NET languages, 224
Unsafe code, 217
Unsigned integer error in VB .NET code, 517
Update responsibilities, table of, 239
Updates to the UML model, situations causing, 240
Updating the UML model after deployment, 244
Upload class code, 782
Upload Picture class diagram, 750
Upload Picture sequence diagram, 743–749
Upload Picture-c class diagram, 754–767
URL attribute of LItem node, 395, 404
Usability of the solution, 44
Usage requirements, 69
Use case with Business Use Case stereotype, 118
Use case diagrams, 95–96, 106–125
with actor and two processes, 54
with actors, 107–112
with actors and processes, 670, 672
adding content to, 683–701
basic elements of, 106
detail in, 679, 682–683
with documentation, 237
high-level, 741–742
mixing different systems, 680
modeling, 678–701
need for, 675
number of, 679–682
packages on, 118–122
processes on, 115–118
Q&A-based, 672
with relation to another system, 680
with relationships, 674
with relationships between actors, 112–115
with relationships in UML 1.4, 823
sequence diagram based on, 238
summary of, 125
system boundaries, 123–124
with two processes, 53
types of relationships, 113
verb-based, 670
Use case model, 95
Use case in a package, 119
Use cases (see also ITReady use cases)
communicates relationship, 113–114
concept of, 91
defined, 91
oval notation for, 96
preconditions and postconditions, 116
splitting to reuse functionality, 689
two in one sequence diagram, 711
user and sponsor acceptance of, 701
uses relationship between, 114
User acceptance
of design, 56
of sequence diagrams, 716
of use cases, 701
User administration (VSS), 450–454
User class generated code, 769–771
User experience role (MSF), 851
User groups, VSS and, 450
User Interface Editor, 599–601
User name/password combination, 433
User profiles, 868
User records, table for, 753
User scenarios, testing, 77
User services, 74, 894
User subclass, table for, 754
Users (ACT), creating and deleting, 547–549
Users and groups (ACT), 546–549
Users tab of ACT Test Properties dialog box, 557
Users.txt file, default, 434–435
Uses relationship, between use cases, 114


Index_V

Team LiB

Index

V

Value attribute of AItem node, 405
VarChar columns, maximum length of, 26–27
VAT (value-added tax) calculation service, 63
VB (Visual Basic) 6.0
Data Types package, 718
Distributed Application enterprise template file, 255–265
Visual Modeler, 6
VB code
generated for a class and interface, 199
generated from a component diagram, 196–200
generated for Customer Class, 173
generated for Customer Class with binary association, 177
generated for _Imageshrink interface, 197
VB code preview
for CustomerStatus operation, 169
for Finalize destructor, 172
for GetList operation, 167
for New constructor, 171
for VIPCustomer class, 181
VB Distributed Application solution, 253
VB Distributed Application template, 251–253
VB .NET (Visual Basic .NET), 3
learning, 217
links and references, 902
programming in, 216
VB .NET class
creating, 7–14
default code template for, 520
VB. NET code
generated for Customer class, 157, 160, 521
generating for Logon class, 14–17
VB. NET code template settings in the Registry, 519
VB .NET newsgroup, 218
VB .NET project, planning, 213–234
VB Simple Distributed Application template, 251
VBScript, dynamic tests using, 538
VEA. See Visio
VEA 2003, 5–7, 499–535 . See also Visio
Verb-based use case diagram, 670
Verbs
services as, 60–61
from system requirements, 669
Version information
log files with, 428
maintaining, 243
Versioned releases, 858–859
Versioned versions, explained, 243
Versioning (software), 640–643
articles and documents on, 642–643
extensions for saved versions, 428
source control for, 423
of UML models, 243
Versioning history, 69
View Code menu item disabled, 320
View filters, 574, 580
Views, enlarging or reducing, 128
VIEWS element (enterprise template file), 264
VIPCustomer class
dependency relationship, 179
generalization relationship, 181
VB code preview for, 181
Visio (Visio for Enterprise Architects–VEA), 5–7
as a documentation tool, 241
editions of, 499
error checking in, 514–518
evaluating, 534
events as operations in, 162
integration with existing environment, 814–819
links and references, 905
migration to from XDE, 805
for .NET developers, 499
with a new database model diagram, 23
with a new UML model diagram, 8
with reverse-engineered DataAccess project, 510
static structure diagrams, 3, 121, 141, 153, 500, 675
support for UML models, 105
supported code generation types, 814–815
VS .NET IDE integrated toolbar, 816
VS .NET IDE integration, 816–817
and working in a project team, 241
vs. XDE, 813–825
Visio 2003, 5–7, 499–535
Visio Code Editor, with Access DDL script, 34–35
Visio modeling of a database, 735–736
Visio object model, 820
Visio Professional 2003, 6
Visio reports, 820–821
Visio type library, 820
Visio versions, 6
Visio Viewer, 7, 533
Visio VSD file in Internet Explorer, 533
Vision scope document, 862, 869–870
Vision statement, 863–864
Visual Modeler, Visual Basic 6.0, 6
Visual SourceSafe. See VSS
Visual Studio Analyzer, 565–583
analyzing data, 580–583
architecture of, 565–568
client and server, 568
collection filters, 572, 574–578
event collection, 566–567, 578–580
event collection and analysis process, 566–567
Event List for a filter, 581
event recording and collection, 573–574
setup options, 569
Visual Studio Analyzer components, installing, 568–570
Visual Studio Analyzer project
creating, 570–574
in VS .NET IDE, 570
Visual Studio Analyzer Project Wizard, 570–573
VS .NET (Visual Studio .NET)
Coffee Inc. solution in, 769
missing deployment functionality, 661–662
remote components setup, 569
upcoming release (Whidbey), 18, 534
VS .NET 2003 Command Prompt window, 448
VS .NET ACT project files, 544
VS .NET Combined Collection, 388
VS. NET deployment, overview of, 585–604
VS .NET enterprise links and references, 906
VS .NET enterprise templates. See Enterprise template projects
VS .NET IDE (integrated development environment), 6
ACT test results in, 561
items added by XDE, 818–819
new ACT project in, 544
project open in, 313
with source control applications, 423
splitting the view, 800–801
switching between databases, 480
using ACT in, 543–544, 561
VSS integration with, 435–445
VSS items, 435–438
VS .NET IDE configuration using policies, 338–365
VS .NET IDE integrated toolbar (Visio), 816
VS .NET IDE integration, Visio, 816–817
VS. NET IDE Options dialog box, help settings, 388
VS .NET Installer supported languages/locales, 643
VS .NET item keywords and attributes, viewing, 415, 417–419
VS .NET setup and deployment options, 587–588
VS .NET Setup and Deployment projects, 223, 586–588
VS .NET solution. See Solution
VS .NET solution file (.sln), 284
VS .NET vs. Windows DNA architecture, 62
VS .NET XML Designer, 303
.vsdir file, 284–286
.vsdir file elements, 285–286
VSEA (Visio Studio .NET Enterprise Architecture) edition, 5, 11, 499
VSED (Visio Studio .NET Enterprise Developer) edition, 5
VSIDE.tdl policy file, 294
VSIP (Visual Studio Integration Partner) collection, 388
VSS (Visual SourceSafe), 423–498
action when opening or closing a solution, 440
adding items to a project, 477–478
adding a project from source control, 483
adding a solution or project, 480–482
administration, 447–468
advanced tasks, 480–494
allowing multiple checkouts, 485
archiving databases and projects, 457–463
background status updates, 443
checked-in item actions, 441–442
checking in items silently, 476–477
checking in project items, 475–476
checking out items silently, 471–472
checking out project items, 469–470
comparing item versions, 486–488
creating a new project from source control, 482–483
daily tasks, 469–479
deleting and destroying items, 479
editing a project item, 447
excluding items from a project, 478
getting latest versions of items, 474–475
getting started, 446–447
integration with VS .NET IDE, 435–445
main folder, 434
manipulating item versions, 491–493
merging item versions, 488–491
navigating compared items, 488
vs. NTFS, 424
Pending Checkins window, 436–437
private files, 478
project hierarchy, 432–433
project item comments, 470
project rights assignment, 453–454
removing files from source control, 478
removing solution and project files from, 493–494
resolving conflicts, 491
restoring a database or project, 463–465
retrieving data, 469–475
securing default users, 434–435
security, 433–435
Source Control list, 437–438
Source Control menu, 435–436
Source Control Options, 439–445
third-party products that work with, 495
types of file it can be used with, 425
undoing check-out of items, 472–474
using, 468–495
using the Task List with, 438
viewing item history, 491–493
VSS 6.0d, 423
VSS Administrator application, 447–454
VSS architecture, 425–433
VSS clients, 426–427
VSS database
connecting to, 480
recovering without Admin password, 467–468
removing a project from, 483–485
updating data in, 475–477
VSS database administration, 454–468
VSS database folders and files, 427–432
VSS database integrity, validating, 456–457
VSS database organization, 427–433
VSS database servers, 426
VSS database temporary file location, 465–466
VSS Explorer, opening, 432–433
VSS Login dialog box, 444
VSS network setup, 426
VSS project, accessing, 446
VSS role, 440
VSS temporary folder, cleaning up, 466–467
VSS user administration, 450–454
adding users, 450–451
removing users, 451–452
user settings, 452
user/project rights, 453–454


Index_W

Team LiB

Index

W

WAN (wide area network), 4
Waterfall Model process method, 836
Web application performance. See ACT
Web configuration files, 627–629
Web page, saving a UML model as, 531–532
Web project dependencies, detecting, 626
Web project output, 626–629
dependencies, 626
graphics files, 627
Web configuration files, 627–629
Web satellite assemblies, 627
Web servers, stress-testing, 537
Web service project, 254
Web service project items, 623
Web services, 77. See also Services
advantages of, 63
analyzing, 537
Web Setup and Deployment Project files, 626–629
Web setup project, order of building and deploying, 629–630
Web setup project content, 629
Web.config configuration file, 227
WebDeploymentProject project items, 622
WebDeploymentProject sample application items, 621–622
WebDeploymentProjectWebService items, 623
Web.Services component, 333
WebUI, for enterprise template project, 274
Welcome dialog box of Administrative Installation, 651
Windows Application project, 504
Windows Application template, 503
Windows applications, deploying, 606–621
Windows configuration files, 613–615
Windows deployed items on target machine, 615–621
Windows DNA, 61–63
advantages of, 63
architecture, 62
vs. VS .NET architecture, 62
Windows Forms, 758, 768
control Location property, 359–360
Label control on, 227
label definition, 358
Label toolbox item, 363–364
Windows Installer, 604–606
Windows Installer upgrade folder URL, 606
Windows project dependencies, detecting, 610–612
Windows project output, 609–615
Windows satellite assemblies, 612
WindowsDeploymentProject project items, 607
WinUI, for enterprise template project, 274
Wizards, adding to enterprise template
project, 277–283
WMI (Windows Management Instrumentation), 231
Workflow diagram, 873
Working directory, 427
Workstations, VSS, 426–427


Index_X

Team LiB

Index

X

XDE (IBM Rational XDE), 88, 500, 534, 791–811
Automatic Synchronization, 798–801
code template file with a scriptlet, 807–808
code templates, 805–809
controlled units, 821–822
design patterns, 809–810
diagramming with, 794–801
external code templates, 806
integration with existing environment, 814–819
internal code templates, 806
items added to VS .NET IDE, 818–819
items in storage units/controlled units, 821–822
learning more about, 810
locking capability, 241
migration, 801–805
Model Documentation window, 819
Model Explorer, 818
modeling with, 793–794
reporting, 821
sequence diagrams, 797
setting properties, 795–797
storage units, 821–823
supported code generation types, 815
vs. Visio, 813–825
vs. VS .NET IDE features, 791–792
XDE Toolbox tabs, 793
XDE type library, 820
XML data validation against a schema, 269
XML Designer, 303, 305
XML editor, 269, 303
XML elements, 257
XML file, 220
creating, 304
in XML Designer, 305
XML Web Services
adding to enterprise template project, 280–283
explained, 74
Xmlns attribute, 400
Xmlspy program, 269


List of Figures

Chapter 1: Getting Started: A Modeling Primer

Figure 1-1: VEA open with a new UML model diagram
Figure 1-2: The UML Class Properties dialog box
Figure 1-3: The UML Class Properties dialog box showing attributes
Figure 1-4: The UML Operation Properties dialog box showing parameters
Figure 1-5: The class diagram with the updated class
Figure 1-6: The Generate dialog box
Figure 1-7: The Model Explorer with Top Package selected
Figure 1-8: The Output window showing semantic errors after code generation
Figure 1-9: The generated VB .NET code for the Logon class
Figure 1-10: The generated C# code for the Logon class
Figure 1-11: Crow's feet notation on a simple ER diagram
Figure 1-12: VEA open with a new database model diagram
Figure 1-13: The Database Properties window open in the Visio workspace
Figure 1-14: The Database Properties window open on the Columns category page
Figure 1-15: The Column Properties dialog box showing the Data Type tab
Figure 1-16: The Database Properties window with updated column lengths
Figure 1-17: The Database Properties window showing the Indexes page
Figure 1-18: The Output window showing database model error-check messages
Figure 1-19: The opening page of the Generate Wizard
Figure 1-20: The second page of the Generate Wizard
Figure 1-21: The Visio Code Editor with the Microsoft Access DDL script
Figure 1-22: The Reverse Engineer Wizard
Figure 1-23: The database tables review page of the Reverse Engineer Wizard
Figure 1-24: The reverse-engineered Customers table on a class diagram

Chapter 2: Planning and Documenting Your Solution

Figure 2-1: The cost of fixing bad design
Figure 2-2: Use case diagram with two processes
Figure 2-3: Use case diagram with an actor and two processes
Figure 2-4: The customer interacting with the system
Figure 2-5: UML sequence diagram
Figure 2-6: The Windows DNA architecture
Figure 2-7: A simple business object model
Figure 2-8: A simple matrix for comparing technologies

Chapter 3: Getting to Know the Unified Modeling Language

Figure 3-1: The Car object expressed using UML
Figure 3-2: A database model
Figure 3-3: An actor
Figure 3-4: A process
Figure 3-5: Simple use case diagram
Figure 3-6: A UML class
Figure 3-7: A simple class diagram
Figure 3-8: A sequence diagram
Figure 3-9: A collaboration diagram
Figure 3-10: A statechart diagram
Figure 3-11: An activity diagram
Figure 3-12: A component diagram
Figure 3-13: A simple deployment diagram

Chapter 4: Examining the UML Models: Behavioral Models

Figure 4-1: The actor notation is a stick figure.
Figure 4-2: Business actors
Figure 4-3: Business actors with generalization (inheritance)
Figure 4-4: Business actors shown with stereotypes
Figure 4-5: Communicates relationship between an actor and a use case
Figure 4-6: Uses relationship between use cases
Figure 4-7: Extends relationship
Figure 4-8: Documentation text box for the Invoice use case
Figure 4-9: The Documentation window
Figure 4-10: Use case with the Business Use Case stereotype
Figure 4-11: The package notation
Figure 4-12: Use case in a package
Figure 4-13: ToyCar Enterprise System packages on a static structure diagram
Figure 4-14: The final system structure
Figure 4-15: System boundary
Figure 4-16: Sequence diagram with class lifeline
Figure 4-17: Sequence diagram with class and actor lifelines
Figure 4-18: Sequence diagram with an Activation shape
Figure 4-19: The six sequence diagram message types
Figure 4-20: Sequence diagram with objects
Figure 4-21: Sequence diagram with objects and activations
Figure 4-22: Sequence diagram with a message
Figure 4-23: Message with a message name
Figure 4-24: Return message on the sequence diagram
Figure 4-25: Parameter setting on a message
Figure 4-26: Note on a sequence diagram
Figure 4-27: Attached Note shape with text
Figure 4-28: The Classifier Role shape and the Multi-Object shape on a collaboration diagram
Figure 4-29: Static structure diagram with an association
Figure 4-30: UML Association Role Properties dialog box
Figure 4-31: Collaboration diagram with an association
Figure 4-32: Creating messages for a collaboration diagram
Figure 4-33: Collaboration diagram with a message
Figure 4-34: Swimlanes on an activity diagram
Figure 4-35: Action State shapes on an activity diagram
Figure 4-36: Transitions on an activity diagram
Figure 4-37: State on the activity diagram
Figure 4-38: Decision shape on the activity diagram
Figure 4-39: UML Transition Properties dialog box with a guard expression

Chapter 5: Examining the UML Models: Static Models

Figure 5-1: Class diagram with a namespace (package)
Figure 5-2: Generate dialog box with the Customer class
Figure 5-3: VB .NET code generated for the Customer class
Figure 5-4: C# code generated for the Customer class
Figure 5-5: UML Class Properties dialog box for the Customer class
Figure 5-6: UML Class Properties dialog box with attributes for the Customer class
Figure 5-7: Generated code for the Customer class with attributes
Figure 5-8: UML Class Properties dialog box with operations for the Customer class
Figure 5-9: UML Operation Properties dialog box
Figure 5-10: UML Operation Properties dialog box with the customerTypeID parameter
Figure 5-11: UML Operation Properties dialog box with code generation settings
Figure 5-12: Code preview for the GetList operation (VB code)
Figure 5-13: Code preview for the GetList operation (C# code)
Figure 5-14: UML Operation Properties dialog box for the CustomerStatus operation
Figure 5-15: Code Preview for the CustomerStatus operation (VB code)
Figure 5-16: Code preview for the New constructor (VB code)
Figure 5-17: Code preview for the Finalize destructor (VB code)
Figure 5-18: UML Association Properties dialog box
Figure 5-19: Binary association between the Customer and ShoppingBasket classes
Figure 5-20: Dependency relationship between the VIPCustomer and the Bonus classes
Figure 5-21: Generalization relationship between the Customer and VIPCustomer classes
Figure 5-22: Code preview for the VIPCustomer class
Figure 5-23: Statechart diagram
Figure 5-24: Guard expression for outgoing transition
Figure 5-25: Component diagram
Figure 5-26: Components category of the UML Node Properties dialog box for Node1
Figure 5-27: Operations category of the UML Interface Properties dialog box
Figure 5-28: Parameters category of the UML Operation Properties dialog box
Figure 5-29: Interface shown in the Model Explorer
Figure 5-30: COM+ component with the ObjectControl interface
Figure 5-31: Generate dialog box with the _ImageShrink interface selected
Figure 5-32: VB code generated for the _Imageshrink interface
Figure 5-33: Class diagram with Class1 class incorporating the ObjectControl and _Imageshrink interfaces
Figure 5-34: UML Class Properties dialog box for Class1, showing the class does not have any operations
Figure 5-35: Code generated for Class1 including interfaces
Figure 5-36: Deployment diagram with two different node types
Figure 5-37: UML Component Properties dialog box
Figure 5-38: UML Node Properties dialog box
Figure 5-39: Stereotypes in the UML Class Properties dialog box
Figure 5-40: Class1 class with the struct stereotype
Figure 5-41: UML Stereotypes dialog box
Figure 5-42: Class1 class with the ASP.NET Page stereotype

Chapter 6: Planning a VB .NET or C# Project

Figure 6-1: An XML-based resource file
Figure 6-2: VS .NET Setup and Deployment projects
Figure 6-3: Enterprise template projects
Figure 6-4: The Web.config configuration file
Figure 6-5: Label control on a Windows form
Figure 6-6: Accessing dynamic properties for a control
Figure 6-7: Dynamic Properties dialog box
Figure 6-8: The app.config configuration file with a dynamic property

Chapter 7: Maintaining the UML Documentation

Figure 7-1: Use case diagram with documentation
Figure 7-2: Sequence diagram based on the use case diagram
Figure 7-3: Class diagram based on sequence diagram
Figure 7-4: Saving a model as read-only

Chapter 8: Using Enterprise Template Projects

Figure 8-1: Selecting the Visual Basic Distributed Application in the New Project dialog box
Figure 8-2: Solution Explorer with a new Visual Basic Distributed Application solution
Figure 8-3: Enterprise template project file hierarchy
Figure 8-4: New enterprise template project in the Solution Explorer
Figure 8-5: Add New Project dialog box
Figure 8-6: Add New Item dialog box
Figure 8-7: New Template Project shown in the New Project dialog box

Chapter 9: Using Policy Files

Figure 9-1: The three policy file contexts
Figure 9-2: Policy file scope
Figure 9-3: VS .NET XML Designer with IntelliSense based on the TDL schema
Figure 9-4: Choosing to create an XML file in the New File dialog box
Figure 9-5: The XMLFile1 XML file shown in the XML Designer
Figure 9-6: Changing the policy file from the VS .NET IDE
Figure 9-7: Policy file loading error
Figure 9-8: Default item policy
Figure 9-9: NewTemplateProject1 project open in the VS .NET IDE
Figure 9-10: View ® Code menu item disabled
Figure 9-11: Policy reminder in the Task List
Figure 9-12: Component reference name shown in the Properties window
Figure 9-13: File ® Add ® New Item menu item disabled by a constraint
Figure 9-14: Policy reminders in the Task List noting wrong property values
Figure 9-15: The Windows Forms Label toolbox item disabled by a constraint
Figure 9-16: Add New Item dialog box with all valid project items for the projBusinessFacade project displayed
Figure 9-17: Add New Item dialog box with all valid project items for the projWebService project displayed
Figure 9-18: Add New Item dialog box with INCLUDE project items only displayed
Figure 9-19: Add New Project dialog box with all valid projects displayed
Figure 9-20: Add New Project dialog box with VB .NET Windows Application displayed

Chapter 10: Using Custom Help Topics

Figure 10-1: Dynamic Help window
Figure 10-2: Dynamic Help window categories
Figure 10-3: Help topics in the Microsoft Document Explorer
Figure 10-4: Displaying Help topics internally
Figure 10-5: Help settings in the VS .NET IDE Options dialog box
Figure 10-6: NewEnterpriseHelp.htm custom help file displayed in Internet Explorer
Figure 10-7: Custom help topic shown in the Dynamic Help window
Figure 10-8: Custom help topic shown in the Microsoft Document Explorer
Figure 10-9: Custom help topic link shown in the Dynamic Help window
Figure 10-10: Registry Editor with the Dynamic Help window debugging information set
Figure 10-11: Dynamic Help window displaying debugging information
Figure 10-12: Setting Dynamic Help display options
Figure 10-13: Custom categories in the Dynamic Help page of the Options dialog box

Chapter 11: Visual SourceSafe

Figure 11-1: A common VSS network setup
Figure 11-2: The root folder in Visual SourceSafe Explorer
Figure 11-3: The default users.txt file
Figure 11-4: Pending Checkins window
Figure 11-5: Output window with Source Control selected
Figure 11-6: General options under Source Control in the Options dialog box
Figure 11-7: This can happen when you allow editing of checked-in items.
Figure 11-8: SCC Provider options under Source Control in the Options dialog box
Figure 11-9: Visual SourceSafe Login dialog box
Figure 11-10: The General tab of the SourceSafe Options dialog box, showing vendor-specific options
Figure 11-11: Integration tab of the SourceSafe Options dialog box
Figure 11-12: Visual SourceSafe Administrator application
Figure 11-13: Environment Variables dialog box
Figure 11-14: Add User dialog box in Visual SourceSafe Administrator
Figure 11-15: Confirm User Deletion dialog box
Figure 11-16: Edit User dialog box
Figure 11-17: Project Rights tab of the SourceSafe Options dialog box
Figure 11-18: Lock Visual SourceSafe Database dialog box
Figure 11-19: Database locked in Visual SourceSafe Administrator
Figure 11-20: Analyze help window listing the command-line switches
Figure 11-21: Choose Project to Archive dialog box
Figure 11-22: Archive Wizard, Step 1 of 3
Figure 11-23: Archive Wizard, Step 2 of 3
Figure 11-24: Archive Wizard, Step 3 of 3
Figure 11-25: Restore Wizard, Step 1 of 3
Figure 11-26: Restore Wizard, Step 2 of 3
Figure 11-27: Restore Wizard, Step 3 of 3
Figure 11-28: Clean Up Local Temporary Files Directory dialog box
Figure 11-29: Check Out dialog box
Figure 11-30: Undo Checkout dialog box
Figure 11-31: Check In dialog box
Figure 11-32: Delete dialog box of the Visual SourceSafe Explorer application
Figure 11-33: Add to SourceSafe Project dialog box
Figure 11-34: Create local project from SourceSafe dialog box
Figure 11-35: Change Source Control dialog box
Figure 11-36: General tab of the SourceSafe Options dialog box
Figure 11-37: Difference Options dialog box
Figure 11-38: Differences dialog box
Figure 11-39: Automatic item merge message
Figure 11-40: Merge SourceSafe version into Local version dialog box
Figure 11-41: History Options dialog box
Figure 11-42: History dialog box

Chapter 12: Visio for Enterprise Architects 2003

Figure 12-1: Generate dialog box
Figure 12-2: Generated code added to a Visual Studio project, using the Empty Project template
Figure 12-3: Generated code added to a Visual Studio project using the Windows Application template
Figure 12-4: Test class added to the TopPackage1 project of the TopPackage solution
Figure 12-5: Code-generation cancellation shown in the Code pane of the Output window
Figure 12-6: Duwamish 7.0 VB sample application in the Solution Explorer
Figure 12-7: Duwamish-DataAccess.vsd added to the duwamish solution
Figure 12-8: VEA with the reverse-engineered DataAccess project
Figure 12-9: Reverse-engineered Books class on a static structure diagram
Figure 12-10: VEA Model Explorer with the complete Duwamish 7.0 VB sample application
Figure 12-11: Semantic errors in a static structure diagram
Figure 12-12: Programmatic error caused by an unsigned integer in VB .NET code
Figure 12-13: Code preview for an element with a programmatic error
Figure 12-14: Code Templates settings in the Preferences dialog box
Figure 12-15: Default code template for VB .NET class implementation
Figure 12-16: VB .NET generated code for the Customer class, based on ClassImpl template
Figure 12-17: Edited VB .NET ClassImpl code template
Figure 12-18: Generated Customer class code based on the custom ClassImpl VB .NET template
Figure 12-19: Generated Customer class code based on the default ClassImpl C# template
Figure 12-20: UML Static Structure Report in the UML Report preview window
Figure 12-21: Selecting to save a model as a Web page in the Save As dialog box
Figure 12-22: Visio VSD file opened in Internet Explorer

Chapter 13: Application Center Test

Figure 13-1: Opening ACT for the first time
Figure 13-2: ACT UI with a project opened
Figure 13-3: Creating a new ACT project in the VS .NET IDE
Figure 13-4: VS .NET IDE with a new ACT project
Figure 13-5: New Users Group
Figure 13-6: General tab of the project Properties dialog box
Figure 13-7: Debugging tab of the project Properties dialog box
Figure 13-8: ACTSamples project in ACT
Figure 13-9: General tab of the test Properties dialog box
Figure 13-10: Users tab of the test Properties dialog box
Figure 13-11: Counters tab of the test Properties dialog box
Figure 13-12: Intermediate test output in the Output window in the VS .NET IDE
Figure 13-13: Intermediate test output in the Test Status dialog box in ACT
Figure 13-14: Application Center Test Results dialog box in the VS .NET IDE
Figure 13-15: Test reports in ACT
Figure 13-16: Test run graph

Chapter 14: Visual Studio Analyzer

Figure 14-1: Simple Visual Studio Analyzer architecture
Figure 14-2: Visual Studio Analyzer event collection and analysis process
Figure 14-3: Visual Studio Analyzer setup options
Figure 14-4: Remote Components Setup option
Figure 14-5: Visual Studio Analyzer projects in the VS: NET IDE
Figure 14-6: Visual Studio Analyzer Project Wizard, Step 1
Figure 14-7: Visual Studio Analyzer Project Wizard, Step 2
Figure 14-8: Visual Studio Analyzer Project Wizard, Step 3
Figure 14-9: Visual Studio Analyzer event recording/collection dialog box
Figure 14-10: Edit New Filter dialog box
Figure 14-11: Visual Studio Analyzer Event List
Figure 14-12: Process diagram

Chapter 15: Deploying Your Applications

Figure 15-1: VS .NET Setup and Deployment Projects
Figure 15-2: Properties window
Figure 15-3: Property Pages dialog box for a setup project showing configuration- dependent properties
Figure 15-4: File System Editor
Figure 15-5: File types in the Windows Folder Options dialog box
Figure 15-6: File Types Editor
Figure 15-7: Registry Editor
Figure 15-8: User Interface Editor
Figure 15-9: Add Dialog dialog box
Figure 15-10: Custom Actions Editor
Figure 15-11: Select Item in Project dialog box
Figure 15-12: Launch Conditions Editor
Figure 15-13: WindowsDeploymentProject project items
Figure 15-14: Add Project Output Group dialog box
Figure 15-15: DeploymentProject detected project dependencies
Figure 15-16: DeploymentProject content
Figure 15-17: File Properties dialog box
Figure 15-18: Assembly information file
Figure 15-19: Support Info dialog box
Figure 15-20: WebDeploymentProject project items
Figure 15-21: Copy Project dialog box
Figure 15-22: Web setup projects content
Figure 15-23: .NET Framework launch condition
Figure 15-24: .NET Configuration application (for .NET Framework 1.1)
Figure 15-25: License Agreement dialog box
Figure 15-26: License Agreement dialog box with a banner logo
Figure 15-27: License Agreement dialog box in German
Figure 15-28: Setup project file (.vdproj) with text modified
Figure 15-29: Configuration Manager
Figure 15-30: Welcome dialog box of Administrative Install
Figure 15-31: Folder properties dialog box of Windows XP
Figure 15-32: Edit Alias dialog box

Chapter 16: Hands On: An Internal Project

Figure 16-1: MSF Process Model
Figure 16-2: Preliminary solution actors
Figure 16-3: Verb-based use case diagram with identified actors and processes
Figure 16-4: Q&A-based use case diagram with identified actors and processes
Figure 16-5: Use case diagram with relationships
Figure 16-6: Use case diagram mixing use cases from two different systems
Figure 16-7: Use case diagram showing relation to another system
Figure 16-8: Shape Display Options dialog box
Figure 16-9: UML Association Properties dialog box
Figure 16-10: UML Use Case Properties dialog box with plain text documentation
Figure 16-11: UML Use Case Properties dialog box with the complete description
Figure 16-12: UML Use Case Properties dialog box with the complete Maintain Time Entries description
Figure 16-13: Split Maintain Time Entries use case
Figure 16-14: A use case is easier to reuse if it contains a single process only.
Figure 16-15: UML Use Case Properties dialog box with the complete Maintain Projects description
Figure 16-16: Dependency relationship between the Maintain Tasks and Maintain Projects use cases
Figure 16-17: UML Use Case Properties dialog box with the complete Maintain Tasks description
Figure 16-18: UML Use Case Properties dialog box with Approve and Validate Time Entries description
Figure 16-19: UML Use Case Properties dialog box with the detailed Approve and Validate Time Entries description
Figure 16-20: UML Use Case Properties dialog box with the Send Disapproval Notification description
Figure 16-21: UML Use Case Properties dialog box with the Create Totals Report description
Figure 16-22: UML Use Case Properties dialog box with the Create Personal Report description
Figure 16-23: Sequence diagram with an Employee object
Figure 16-24: UML Classifier Role Properties dialog box with the Name and Classifier properties set
Figure 16-25: Time Sheet object added to the sequence diagram
Figure 16-26: Sequence diagram with all use case tasks
Figure 16-27: Sequence diagram reflecting the use case and the login information
Figure 16-28: Sequence diagram being made more IT-specific
Figure 16-29: The Maintain Time Entries sequence diagram
Figure 16-30: Task sequence from two use cases in same sequence diagram
Figure 16-31: Sequence diagram for the Maintain Time Entries use case
Figure 16-32: Complete sequence diagram for the Approve and Validate Time Entries use case
Figure 16-33: UML Datatype Properties dialog box
Figure 16-34: Register Hours class diagram with the most important classes
Figure 16-35: Save operation of the TimeSheet class with a second parameter
Figure 16-36: Class diagram with a database table and relation
Figure 16-37: Class diagram with TimeSheetForm placed on an ASP.NET page
Figure 16-38: Generate dialog box
Figure 16-39: Code generated for the TimeSheet class
Figure 16-40: Class diagram with the CEmployee class
Figure 16-41: Generated code for the TimeSheet class
Figure 16-42: Generated code for the CEmployee class
Figure 16-43: Approve and Validate Time Entries sequence diagram with new notification modeling
Figure 16-44: Class diagram showing how to use the ITREmail class
Figure 16-45: Component diagram with the ITReadyMessage COM component
Figure 16-46: UML Component Properties dialog box
Figure 16-47: Data model for the ITReady solution modeled in UML
Figure 16-48: Data model for the ITReady solution modeled using the database model diagram template

Chapter 17: Hands On: An External Project

Figure 17-1: High-level use case diagram for the Sales Company, Product Database, and Picture Database actors
Figure 17-2: High-level use case diagram for the User, Administrator, and Product Database actors
Figure 17-3: Upload Picture sequence diagram
Figure 17-4: Upload Picture sequence diagram made more physical
Figure 17-5: Incomplete Upload Picture class diagram
Figure 17-6: Incomplete Picture database diagram
Figure 17-7: One table containing all User records
Figure 17-8: One table for each User subclass, containing all records for that specific User subclass
Figure 17-9: Updated Upload Picture-c class diagram
Figure 17-10: Upload Picture-c class diagram with parameters and data types set for operations and inheritance set for classes
Figure 17-11: Method category of the UML Operations Properties dialog box
Figure 17-12: Complete Upload Picture-c class diagram
Figure 17-13: Generate dialog box with classes selected
Figure 17-14: Generated CoffeeInc.sln solution opened in VS .NET
Figure 17-15: Selecting the Has Method option for the GetInfo operation
Figure 17-16: UML Association Properties dialog box
Figure 17-17: UML Association End Properties dialog box
Figure 17-18: Preferences dialog box showing the default data types for lists
Figure 17-19: Component Services with the new component

Chapter 18: IBM Rational XDE

Figure 18-1: XDE Toolbox tabs
Figure 18-2: Related Books and Categories classes from Duwamish DataAccess project in a class diagram
Figure 18-3: Automatic Synchronization feature in the Options dialog box
Figure 18-4: Synchronization policy property for the Categories class
Figure 18-5: See your code and UML at the same time by splitting the view in VS .NET.
Figure 18-6: Simple Rose model
Figure 18-7: Rose model converted to XDE
Figure 18-8: IBM Rational Rose Pathmap Editor
Figure 18-9: Step 1 of creating a code template file with a scriptlet
Figure 18-10: Step 2 of creating a code template file with a scriptlet

Chapter 19: Comparing Microsoft and IBM Rational UML Tools and Development Frameworks

Figure 19-1: Reverse-engineered C# form in VEA
Figure 19-2: Reverse engineered C# form in XDE
Figure 19-3: VEA Reverse Engineer feature in the VS .NET IDE
Figure 19-4: Visio UML Reverse Engineer button
Figure 19-5: VEA reverse-engineered model placed in the Solution Explorer
Figure 19-6: Rational XDE Model Explorer
Figure 19-7: Rational XDE Model Documentation window

Chapter 20: Microsoft Solutions Framework 3.0

Figure 20-1: The Waterfall Model method
Figure 20-2: The Rapid Application Development method
Figure 20-3: The MSF project life cycle
Figure 20-4: The Process Model
Figure 20-5: The project tradeoff (devil's) triangle
Figure 20-6: Workflow diagram
Figure 20-7: Technology choice matrix
Figure 20-8: The tradeoff matrix
Figure 20-9: Tradeoff matrix with resources tradeoff specified
Figure 20-10: Risk decreases over time.
Figure 20-11: Risk Model steps
Figure 20-12: UML Business Actors modeled in VEA and UmL 1.2


List of Tables

Chapter 2: Planning and Documenting Your Solution

Table 2-1: Windows DNA vs. VS .NET Architecture

Chapter 3: Getting to Know the Unified Modeling Language

Table 3-1: UML Models

Chapter 4: Examining the UML Models: Behavioral Models

Table 4-1: UML to .NET Mapping

Chapter 5: Examining the UML Models: Static Models

Table 5-1. UML Code Mapping to .NET
Table 5-2: Code File Types

Chapter 7: Maintaining the UML Documentation

Table 7-1. UML Update Responsibilities
Table 7-2. Situations Causing Updates to the UML Model
Table 7-3. Maintaining Different Model Views

Chapter 8: Using Enterprise Template Projects

Table 8-1. Child Elements in an Enterprise Template File
Table 8-2. Enterprise Template Projects Building Blocks
Table 8-3. The .vsdir File Elements
Table 8-4: Icons for Enterprise Template Projects in the New Project Dialog Box
Table 8-5: Values for the Name and Location of the Solution Created

Chapter 9: Using Policy Files

Table 9-1. Default Item Policy Using the DEFAULTACTON and POLICYMODE Nodes
Table 9-2: TDL Nodes

Chapter 10: Using Custom Help Topics

Table 10-1: CONTEXT Child Node Settingx in a Policy File
Table 10-2: CTXTATTRIBUTE Node and AItem Node Combinations

Chapter 11: Visual SourceSafe

Table 11-1. VSS Database Folders and Files

Chapter 12: Visio for Enterprise Architects 2003

Table 12-1. Macros for Use with Code Templates
Table 12-2: Relationship to .NET Data Type Mapping

Chapter 13: Application Center Test

Table 13-1: Microsoft ACT Project Files
Table 13-2: VS .NET Application Center Test Project Files

Chapter 15: Deploying Your Applications

Table 15-1. VS .NET Setup and Deployment Options
Table 15-2: . File-to-Folder Deployment
Table 15-3: Assembly Attributes to File Properties Mapping
Table 15-4: Setup Project Properties to Add or Remove Programs Control Applet Mapping
Table 15-5: Typical Build Output

Chapter 16: Hands On: An Internal Project

Table 16-1: Verbs Identified from the System Requirements Description
Table 16-2: Database Element UML Mapping

Chapter 17: Hands On: An External Project

Table 17-1: Extra Operations Added to the Class Diagram

Chapter 18: IBM Rational XDE

Table 18-1: XDE VS .NET IDE Features
Table 18-2: Synchronization Settings for an Element

Chapter 19: Comparing Microsoft and IBM Rational UML Tools and Development Frameworks

Table 19-1: MSF and RUP Comparison

Chapter 20: Microsoft Solutions Framework 3.0

Table 20-1: MSF Models
Table 20-2: Team Model Roles and Corresponding Goals
Table 20-3: Vision Scope Document Content
Table 20-4: Revision History

Appendix: Useful Links and References

Table A-1: UML Links and References
Table A-2: VB .NET Links and References
Table A-3: C# Links and References
Table A-4: MSF Links and References
Table A-5: Visio Links and References
Table A-6: VS .NET Enterprise Links and References
Table A-7: Miscellaneous Links and References


List of Exercises

Chapter 1: Getting Started: A Modeling Primer

Exercise 1-1
Exercise 1-2
Exercise 1-3
Exercise 1-4
Exercise 1-5
Exercise 1-6
Exercise 1-7
Exercise 1-8
Exercise 1-9
Exercise 1-10
Exercise 1-11
Exercise 1-12
Exercise 1-13
Exercise 1-14
Exercise 1-15
Exercise 1-16

Chapter 4: Examining the UML Models: Behavioral Models

Exercise 4-1
Exercise 4-2
Exercise 4-3
Exercise 4-4
Exercise 4-5
Exercise 4-6
Exercise 4-7
Exercise 4-8
Exercise 4-9
Exercise 4-10
Exercise 4-11
Exercise 4-12
Exercise 4-13
Exercise 4-14
Exercise 4-15

Chapter 5: Examining the UML Models: Static Models

Exercise 5-1
Exercise 5-2
Exercise 5-3
Exercise 5-4
Exercise 5-5
Exercise 5-6
Exercise 5-7
Exercise 5-8
Listing 5-1. Code Generated for the Customer Class
Exercise 5-9
Listing 5-2. Code Generated for the Customer Class with a Binary Association
Exercise 5-10
Exercise 5-11
Exercise 5-12
Exercise 5-13
Exercise 5-14
Exercise 5-15
Exercise 5-16
Exercise 5-17
Exercise 5-18
Exercise 5-19
Exercise 5-20
Exercise 5-21
Exercise 5-22

Chapter 8: Using Enterprise Template Projects

Exercise 8-1
Listing 8-1. Visual Basic Distributed Application Enterprise Template File
Listing 8-2. The projectschema.xsd Enterprise Template Project Schema File
Exercise 8-2
Exercise 8-3
Exercise 8-4
Exercise 8-5
Listing 8-3. The Initial NewTemplateProject.etp File
Exercise 8-6
Listing 8-4. The NewTemplateProject.etp File with Wizard Reference
Exercise 8-7
Listing 8-5. The NewWebService.vbproj File without the Policy File Reference
Exercise 8-8

Chapter 9: Using Policy Files

Listing 9-1. Policy File Structure
Exercise 9-1
Exercise 9-2
Exercise 9-3
Exercise 9-4
Exercise 9-5
Exercise 9-6
Exercise 9-7
Listing 9-2. MENU Node Definition for the View ® Code Menu Item
Listing 9-3. ELEMENT Definition of VB Code Files
Listing 9-4. Project ELEMENT Definition with a MEMBERCONSTRAINT Node
Listing 9-5. codeSqlDataAdapter ELEMENT Code Declaration Scope
Exercise 9-8
Listing 9-6. Category of ELEMENT Nodes
Listing 9-7. Specifying a Project Item PROTOTYPE for an ELEMENT Node
Exercise 9-9
Listing 9-8. Project Item ELEMENT Nodes for Add New Item Dialog Box Configuration
Listing 9-9. Project ELEMENT Nodes for Add New Item Dialog Box Configuration
Listing 9-10. Specifying a Project PROTOTYPE for an ELEMENT Node
Exercise 9-10
Listing 9-11. Project ELEMENT Nodes for Add New Project Dialog Box Configuration
Listing 9-12. Enterprise Project ELEMENT Nodes for Add New Project Dialog Box Configuration
Listing 9-13. Adding Menu Items to the FEATURES Node
Listing 9-14. Using Constraints to Disable a Menu or Menu Item
Exercise 9-11
Listing 9-15. Using Associations to Disable a Menu or Menu Item
Exercise 9-12
Listing 9-16. Minimum Property Constraint Definition
Listing 9-17. Windows Forms Label Defined
Listing 9-18. Setting Property Constraints for an Included ELEMENT Node
Exercise 9-13
Listing 9-19. Adding Toolbox Items to the FEATURES Node
Listing 9-20. Using Constraints to Disable a Toolbox Item
Exercise 9-14
Listing 9-21. Using Associations to Disable a Toolbox Item
Exercise 9-9 Answers
Exercise 9-10 Answers

Chapter 10: Using Custom Help Topics

Listing 10-1. NewEnterpriseHelp.xml Context File
Listing 10-2. NewEnterpriseHelp.htm Custom Help File
Listing 10-3. Basic Custom Help Context File
Exercise 10-1
Exercise 10-2
Listing 10-4. NewEnterpriseHelp.xml Context File with a Context Node
Exercise 10-3
Listing 10-5. NewEnterpriseHelp.xml Context File with an AItem Attribute Node
Exercise 10-4
Listing 10-6. projItemVBCodeFile ELEMENT Node for Policy File
Listing 10-7. CONTEXT Node in a Policy File
Exercise 10-5
Listing 10-8. projItemWebForm ELEMENT Node with a CONTEXT Child Node
Exercise 10-6
Exercise 10-7
Listing 10-9. projItemWebForm ELEMENT Node Without a CTXTATTRIBUTE Node

Chapter 12: Visio for Enterprise Architects 2003

Exercise 12-1
Exercise 12-2
Exercise 12-3
Exercise 12-4
Exercise 12-5
Exercise 12-6
Exercise 12-7

Chapter 15: Deploying Your Applications

Exercise 15-1
Exercise 15-2
Exercise 15-3
Exercise 15-4
Exercise 15-5
Exercise 15-6
Exercise 15-7
Exercise 15-8
Listing 15-1. No-Touch Deployment Stub

Chapter 16: Hands On: An Internal Project

Exercise 16-1
Exercise 16-2
Exercise 16-3
Exercise 16-4
Exercise 16-5
Exercise 16-6
Exercise 16-7
Exercise 16-8
Exercise 16-9
Exercise 16-10
Exercise 16-11
Exercise 16-12
Exercise 16-13
Exercise 16-14
Exercise 16-15
Exercise 16-16
Exercise 16-17
Exercise 16-18
Exercise 16-19
Exercise 16-20
Exercise 16-21
Exercise 16-22
Exercise 16-23

Chapter 17: Hands On: An External Project

Exercise 17-1
Exercise 17-2
Exercise 17-3
Exercise 17-4
Exercise 17-5
Exercise 17-6
Exercise 17-7
Exercise 17-8
Listing 17-1: User Class Generated Code
Listing 17-2: SalesCompanyUser Class Generated Code
Exercise 17-9
Listing 17-3: Modified SalesCompanyUser Class
Listing 17-4: LegalRight Class
Exercise 17-10
Listing 17-5: Upload Class


List of Sidebars

Chapter 1: Getting Started: A Modeling Primer

Visio Versions
Coding Conventions
ER and ORM Diagrams

Chapter 2: Planning and Documenting Your Solution

What If They Don't Want Service-based Development?

Chapter 3: Getting to Know the Unified Modeling Language

Choosing the Right Interaction Diagram

Chapter 5: Examining the UML Models: Static Models

Stateless Classes
Generalization, OOP Inheritance, and Polymorphism

Chapter 6: Planning a VB .NET or C# Project

Learn More Than One Programming Language

Chapter 7: Maintaining the UML Documentation

Another Approach: Updating in Stages

Chapter 8: Using Enterprise Template Projects

Too Many Solution Layers

Chapter 9: Using Policy Files

Unexpected Policy Behavior
TDL White Spaces

Chapter 10: Using Custom Help Topics

About the Predefined Help Categories

Chapter 11: Visual SourceSafe

Using the Task List in Team Development
Visual SourceSafe Extras

Chapter 12: Visio for Enterprise Architects 2003

Evaluating VEA

Chapter 14: Visual Studio Analyzer

Deciding Which Components and Events to Analyze
What Is Too Much Time for a Component to Spend?

Chapter 15: Deploying Your Applications

Why Bother to Set File Attributes?
Copy Project Feature
Getting More Information About Versioning
Undoing Default Text Modifications
Missing Deployment Functionality

Chapter 16: Hands On: An Internal Project

Splitting a Use Case to Reuse Functionality
Adding a Dependency Relationship for External Systems
Modeling Two Use Cases in a Single Sequence Diagram

Chapter 17: Hands On: An External Project

Reflecting Inheritance in a Database

Chapter 18: IBM Rational XDE

Viewing Your Code and UML Simultaneously

Chapter 20: Microsoft Solutions Framework 3.0

Project Team vs. Project Process
Missing "Tools"
Security Management

Team LiB
Previous Section