Architectural Roles

This blog discusses the new Architectural Roles feature available in the Visual Studio Team System 2008 Architecture Edition.

Architectural Roles (or Roles for short) are an extensibility point, allowing software architects to embellish objects of Application Diagrams, System Diagrams, and Logical Datacenter Diagrams with metadata that describes the responsibilities objects have within a design. The metadata can be a simple label that calls attention to the role, or it can include rich information about the role including documentation and even links to specialized tools.

In practice, an architect can employ this feature to provide custom and specific guidance to his/her team. Applying the Roles to specific objects in a design allows team members to consume the guidance.

For example, an architect could define roles that identify specific architectural layers (SmartClient, EntityService, GatewayService, etc.).

To do this, the architect authors new SDM resources to define the Architectural Roles (See example below: SampleArchitecturalLayers.sdmDocument), and registers the file under the key: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\EnterpriseTools\Sdm\InitializationFiles]

The roles can be applied to specific objects in a design, by right clicking on a shape and choosing Add | Role | <Role Name>.

The role’s name will be visible on the object’s shape, and the role’s properties will be visible in the Settings and Constraints window. The user can query these properties to receive guidance. This extensibility point opens the possibility for Tools to be written to make use of these Architectural Role properties.

You can learn more about defining and using SDM resources in the System Definition Model (SDM) SDK: https://msdn2.microsoft.com/en-us/teamsystem/aa718757.aspx.

Copy and Paste the below XML into a file named SampleArchitecturalLayers.sdmDocument and use the SDM SDK to compile this document.  

<?xml version="1.0" encoding="utf-8"?>

<SystemDefinitionModel xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" Name="Microsoft.SdmDesigners.Example.ArchitecturalLayers" Version="1.0.0.0" DocumentLanguage="en" xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1" CompilationHash="1B4172215886FDDC7078F59AF6758811220084BF">

<Information>

<FriendlyName>Sample ArchitecturalRoles describing Architectrual Layers</FriendlyName>

<CompanyName>Microsoft Corporation</CompanyName>

<Copyright>Copyright (c) Microsoft Corporation. All rights reserved. This is provided AS IS with no warranties, and confers no rights.</Copyright>

<Description>

<Entry Name="Description">Contains some sample definitions of architectural roles .</Entry>

</Description>

<CompilerVersion>1.0.60130.0</CompilerVersion>

</Information>

<Import Alias="System" Name="System" Version="1.0.60130.0" Culture="neutral" />

<Import Alias="ArchitecturalRoles" Name="Microsoft.ArchitecturalRoles" Version="1.0.60130.0" Culture="neutral" />

<DesignData>

<VisualStudio xmlns="https://schemas.microsoft.com/SystemDefinitionModel/2005/1/DesignData/VisualStudio">

<ModelElement Type="Microsoft.VisualStudio.EnterpriseTools.Application.Modeling.SoftwareComponentDocument">

<Property Name="DocumentType" Value="AbstractTypes" />

</ModelElement>

</VisualStudio>

</DesignData>

<!--EntityService can be applied to either a WebService or a WebApplication-->

<ResourceDefinition Name="EntityService" Extends="System:ResourceDefinition" Abstract="true">

<Description>

<Entry Name="Description">A Sample Role</Entry>

</Description>

<SettingDeclaration Name="StandardPractices" Definition="System:String" CanBeNull="true">

<Description>

<Entry Name="DisplayName">Standard Practices</Entry>

<Entry Name="Category">Guidance</Entry>

<Entry Name="Description">A link to the Standard Practices guidance document.</Entry>

</Description>

</SettingDeclaration>

<SettingDeclaration Name="PreCannedDataContracts" Definition="System:String" CanBeNull="true">

<Description>

<Entry Name="DisplayName">Pre-Canned Data Contracts</Entry>

<Entry Name="Category">Contracts</Entry>

<Entry Name="Description">A link to existing data contracts.</Entry>

</Description>

</SettingDeclaration>

</ResourceDefinition>

<ContainmentDefinition Name="WebServiceRolesContainsEntityService" Extends="System:ContainmentDefinition" ParentDefinition="ArchitecturalRoles:WebServiceRoles" MemberDefinition="EntityService" />

<ContainmentDefinition Name="WebApplicationRolesContainsEntityService" Extends="System:ContainmentDefinition" ParentDefinition="ArchitecturalRoles:WebApplicationRoles" MemberDefinition="EntityService" />

<!--GatewayService can be applied to either a WebService or a WebApplication-->

<ResourceDefinition Name="GatewayService" Extends="System:ResourceDefinition" Abstract="true" />

<ContainmentDefinition Name="WebServiceRolesContainsGatewayService" Extends="System:ContainmentDefinition" ParentDefinition="ArchitecturalRoles:WebServiceRoles" MemberDefinition="GatewayService" />

<ContainmentDefinition Name="WebApplicationRolesContainsGatewayService" Extends="System:ContainmentDefinition" ParentDefinition="ArchitecturalRoles:WebApplicationRoles" MemberDefinition="GatewayService" />

<!--SmartClient can be applied to a WindowsApplication-->

<ResourceDefinition Name="SmartClient" Extends="System:ResourceDefinition" Abstract="true" />

<ContainmentDefinition Name="WindowsApplicationRolesContainsSmartClient" Extends="System:ContainmentDefinition" ParentDefinition="ArchitecturalRoles:WindowsApplicationRoles" MemberDefinition="SmartClient" />

</SystemDefinitionModel>