TN_1105: Why Class Libraries are not Shown on an Application Diagram

Bill Gibson, Program Manager
Microsoft Corporation

At first glance, it might appear that class libraries should have been modeled alongside applications on the application and system diagrams as a way to visualize more of the design of a distributed system. This note discusses why class libraries are not visualized on these diagrams, and why it is preferable to think about and visualize class libraries as a detail of an application, exposed by drilling into the application, than as peers of an application.

First, it is important to understand what applications and systems are.

Applications

In the context of Visual Studio Team Edition for Software Architects, the term ‘application’ is used loosely to refer to a collection of systems that serve some collective user-oriented purpose, such as a Marketing or a Payroll application. However, application is also used in a more precise way to refer to a finer-grained notion, that of an independently configurable and deployable package of software resources. These resources are typically deployed into a single application domain on a single server.  It is these finer-grained applications that are depicted on the application diagram.  In this note, the term application always refers to this latter definition. For more information about applications, see Understanding Applications and the Application Diagram.

All systems are ultimately a configuration of applications, which in turn are configurations of resources. Application resources include binaries, configuration files, XML files, and other resource files.

Systems and Deployment

While a system is the unit for which a deployment is defined, an application is the unit of distribution. A system may be deployed across many servers, but applications are always deployed to a single server. A deployment diagram describes the deployment of a single system to a logical datacenter. To describe a deployment, the system being deployed is decomposed into its constituent applications, and each of these applications is then bound to a logical server.

The purpose of the application diagram is to create and configure application definitions and thus to define the atoms from which composite systems are composed. In the general case, the resources from which an application is composed are all deployed as part of deploying the application, so it is enough to bind the application to the logical server to indicate that all its resources are deployed to that server.

Visualizing Resources

Introducing a representation of resources that are contained within applications on the application diagram that depicts applications would be confusing. On the system diagram, the visual language shows the members of a system contained within the boundary of the system. Class libraries (resources) are members of an application, not of the system, so to depict them alongside their parent applications would break the consistency of the visual language.

When you design a deployment, the tools support dragging an application from a system diagram to a logical server on the deployment diagram as a simple gesture to create the binding between the application and server. Any member of a system can be bound in this manner. If resources were introduced into the diagram, the gesture of dragging system members to define deployment would be complicated by the presence of a class of objects that are not bound using that gesture. Resources are bound via the binding of their encapsulating applications.

The Case of Configurable Class Libraries

A further reason to handle class libraries in a different way arises from the manner in which class library configuration is handled in .NET. A class library that supports configurable behavior requires entries in its app.config file. When such a class libary is referenced by an application at run time, the configuration is provided by the application that uses it and is not provided from the class library’s app.config file. Suppose a Web application references a class library that makes a configurable reference to a Web service or a database. The appropriate configuration entries from the app.config file associated with the class library must be copied into the web.config of the Web application. At run time, these entries are used as the basis of the configuration of the class library’s behavior. Thus a common data access class library that accesses a database may be configured differently to connect to a different database instance in each application in which it is referenced. On the application diagram and system diagrams, the configuration of endpoints is shown as connections. If class libraries that make configurable connections are shown on the diagram, how would they be connected? How would their connections be visualized so that it was apparent that the same class library is configured to connect to two different databases in two different application contexts?

Class Libraries in the Deployment Report

So while class libraries and DLLs are not visualized in the diagrams, it does not mean that they are not recognized or comprehended by the System Definition Model (SDM). Once applications have been implemented and built, all referenced class libraries and DLLs will be included as referenced resources in deployment reports, as long as you have set the Include Binary Files property on the relevant deployment diagram to "True". You can locate this property under the Project Files section in the Properties window on the deployment diagram.

How to Visualize Internal Application Structure

Visualizing the inner structure of applications is not an insurmountable problem by any means, but the best solution requires more than simply showing class libraries on the application and system diagrams as peers of applications. The solution is to not think of class libraries and other resources as peers but as parts of an application. Instead of seeing class libraries connected alongside applications, class libraries and other resources should be visualized by drilling in to the application to view the implementation of the application.  In the same manner that a system diagram depicts the delegation of system endpoints to member endpoints, the drill-in view of an application would depict the delegation of its endpoints to endpoints on its resources—projects, class libraries, DLLs, and so on.

A drill-in view could be provided in-place or in a separate designer/diagram. Imagine double-clicking an application on the application diagram or system diagram to open a drill-down view. In the common case, you would see the root resource (the root project) and a nested hierarchy of dependent resources (class libraries/DLLs etc.) contained within an outer application shape.  Each endpoint on the outer application shape would be delegated to an endpoint either on the root project or one of its dependent resources. Such a designer would also address the problem of copying configuration file entries from a class library into the configuration file of the root project. The visualization and experience could closely parallel that of the system diagram today.

Handling Frameworks

As implied earlier, the view presented above is a simplification. There are additional scenarios involving shared class libraries and other resources that are referenced by multiple applications but which are not configured within each application context. The solution for these lies in recognizing some deployment unit analogous to an application. Such a unit is analogous to an application in that it is packaging construct in that it contains sets of reusable resources but offers no endpoints and would not be restricted to being deployed only once within a system, but could be deployed to each logical server as required to satisfy application dependencies on its resources. Frameworks are an example of this kind of package. This kind of package could also be deployed independently of a system or even be part of a server’s basic configuration so that its resources are available to any application deployed to that server.

Other Resources

Several of the topics touched on in this note are expanded on in other notes:

Understanding Applications and the Application Diagram

Connecting Applications to Web Services from Class Libraries

Understanding Systems and the System Designer

Understanding the System Definition Model

The Four Layers of Systems in the System Definition Model