Share via

BizTalk Application Naming Conventions

  • Article

[last update: 2013-12-13]

Introduction

The “Naming guidelines for the .NET Framework types” and "Guidelines for names" are used as a basis for this document. Also see the “Naming Convention” in Wikipedia.

See the BizTalk Orchestration Naming Conventions for names inside orchestration.

General Considerations

Names should be short, sortable, readable, discoverable, and self-describing.

When constructing name you should ask yourself these questions:

  • Where can I see a name?
  • How can I easily read, understand, and search a name?

Frequently names are used in the name lists. Think about these lists as namespaces in programming languages. Long name lists are always grouped with some logical hierarchy. Naming Conventions help to organize this hierarchy.

Short Names

  • Shorter name is better.
  • Use abbreviations only in limited cases. See article the “Abbreviations”.
  • Use prefixes and suffixes only to differentiate names.
  • If you see one word repeated in several places of a full name, consider this a bad signal. Try to change the name design.

Sortable Names

  • Create “sortable” name. Use more generic/important part of the name in the leftmost position. For example, use the "Folder_20090515" but not the "Folder_05_15_2009".

Readable Names

See http://en.wikipedia.org/wiki/Typography

  • Use the name case compatible with the well-known practices in programming languages/protocols with respect to upper and lower cases. For instance, the XML namespaces (URL) sometimes are preferable in lower case format, but the other names should be in the Pascal format. See the “Capitalization Styles” article.
    If the word with specific case is widely used in company, don’t force to change it to the Pascal format.
  • Decorate infixes, prefixes or suffixes with lower case and with underscore symbol. For example: TicketBatch_type, Source1_and_Source2_to_Target, msg_MyRequest.

Discoverable Names

  • The name should be discoverable. That means we easily understand a purpose of artifact by its name [and by its context]. Names should give additional information about artifacts. Say, the schemas with XML namespace the http://domain.company.com/solution/project/2009-05-14 definitely should be in the Company.Domain.Solution.Project project and in the Company.Domain.Solution.Project.dll assembly.

Self-describing Names (Semantics)

  • Create name from a Business point of view not from a Developer point of view, especially if name is exposed externally to other systems and applications.
  • Don’t use generic terms in the names. Examples: Send, Receive, Service, Message, Transformation, Schema, Map, Orchestration, BizTalk. Context plays an additional information source for a name.
  • Place frequently used terms into a shared dictionary [with comments about where do use them and where do not use].

Name definitions

Composite names are names composed from several words in Pascal format without separating symbols.

  • Examples: MySoulution, PatientRecord. 

Artifacts can use full names or logical names. 

Logical names are composite or single-word names with or without separating symbols [.-_/]. A logical name defines a logical entity within a logical hierarchy. A logical name could hold some hierarchical information and could be composed from several words.

  • Examples: MyCompany.SeattleOffice, MyDomain-DepartmentA, MySolution_Internal, Schemas.SystemX. 

Full names are compounded from logical names separated by separating symbols. Full names express logical hierarchical grouping.

  • Examples: MyCompany.MyDomain.MySolution.Schemas. 

See this document for example how to use logical and full names.

Naming Conventions

Generic Names

  • <Word> =:  [A-Z][a-z1-0]*
  • <CompositeName> =: <Word>[._]<Word>[[._]<Word>]
  • <LogicalName> := <Word>[.<Word>]
    • <CompositeName>
  • <Company> =:
  • <Domain>    =: <Word>
  • <Solution>    =:  <LogicalName>
  • <Namespace> =:
  • <SolutionNamespace>  =:  <Company>.<Domain>.<Solution>

Visual Studio artifacts

  • <SolutionFullName>  =:
  • **<BizTalkApplication> ** =: <Namespace>
  • <Project> =:
  • <ProjectNamespace> =:
  • <Assembly> =:
  • <DotNetNamespace> =:  <Namespace>.<LogicalName>
  • <SolutionsRootFolder> =: c:\Solutions
  • <SolutionFolder>  =:  <SolutionsRootFolder><Company><Domain>\ Solution>
  • <ProjectFolder> =:  <SolutionFolder>\<Project>
  • <OrchestrationProject> =:  <Namespace>.Orchs
  • <SchemaProject>  =:  <Namespace>.Schemas
  • <MapProject>  =: <Namespace>.Maps
  • <PipelineProject> ** =:  <Namespace>.Pipelines**
  • <PipelineComponentProject>  =:  <Namespace>.PipelineComponents
  • <SchemaTargetNamespace> =:   http://<Namespace>[.Qualifier][/<Version>]
  • <Version> =:  <integer>.<integer>.<integer>
    • <date> [in YYYY-MM-DD format]

BizTalk Artifacts

  • <Orchestration>  =:  <LogicalName>
  • <Schema> =:  <LogicalName>
    • <LogicalName>_FF [for Flat File schema]
  • <Map>  =:  <SourceSchema>_to_<DestinationSchema> [for one-to-one map]
    • <SourceSchema1>_and_<SourceSchema2>_to_<DestinationSchema> [for two-to-one map]
  • <Pipeline> =:  <LogicalName>
  • <ReceivePort> =:  <Namespace>.<LogicalName>
  • <ReceiveLocation>   =:  <ReceivePort>.<TransportType>
  • <SendPort>  =:   <Namespace>.<LogicalName>.<TransportType>
  • <SchemaNamespace>   =:
  • <MapNamespace>   =:
  • <OrchestrationNamespace>  =:  <ProjectNamespace>[.<Qualifier>]*
  • <MessageType>  ** =:  <SchemaNamespace>#**<SchemaRootName>
  • **<MessageLogicalName> ** =:  <SchemaRootName>

Considerations

Generic and Visual Studio Names

  • A Solution term is used in the Visual Studio meaning, it is a solution name we see in the Visual Studio Solution Explorer window. Sometimes Solution and Project terms can be mixed but not in this document.
  • A Project term is used in the Visual Studio meaning, it is a name of the project we see in the Solution Explorer window in the Visual Studio.
    Use the full name for the projects because the same project could be part of several Visual Studio solutions. Moreover, it is easy associate the Project with Assembly if they have the same names.
  • DotNetNamespace term is used for a namespace of the BizTalk artifacts which are stored in .NET assemblies. Artifacts as Schemas, Maps, Pipelines, and Orchestrations have DotNetNamespace. Some BizTalk artifacts as Ports are not stored in assemblies but only in a BizTalk Management database. Those artifacts do not have DotNetNamespace.
  • Projects with Schemas, Maps, and Orchestrations inside can place these artifacts into additional folders. In this case the artifact namespace is modified by the name of this folder which is the Qualifier in these naming conventions.
  • Assembly is an “Assembly name” property and DotNetNamespace is a “Default namespace” property in the project Properties window.
  • We should separate the .NET namespaces (SchemaNamespace) and the XML namespaces (SchemaTargetNamespace). They are different things and used in different places.
  • Name of the .Net **project **(ComponentProject) can be **Classes,  **or **Components, **or BusinessComponents.
  • Name of the BizTalk map project depends on your preference. It can be **Transforms **as proposed by Scott Colestock and used in the BizTalk Deployment Framework (e.g. '<project.Transforms>') and can be as well the **Maps **as it used by the BizTalk Solution Factory (e.g. '<project.Maps').

Controversial

  • Do we have to group different artifact types into the separate projects? It depends. Separate, if you have a good reason. Schemas almost always are placed separately.
  • We generate several artifacts using a WCF Consume Service Wizard. It creates several schemas and an orchestration. Do we have to move schemas to the Schema project and move an orchestration (or the message and port types from this orchestration) to the Orchestration project (to another orchestration)? Probably not, because if we should regenerate those artifacts, we should repeat all these tasks again and again. Probably we should follow a rule “do not touch the automatically generated objects”.

XML namespaces

Prefer strict rules for the XML namespaces, because they are an important part of the XML documents. Those XML documents expose data to the external applications. So the XML namespaces are visible to these external applications. The XML namespaces should follow the industry standards and the corporate standards. XML namespaces work as the global unique identifiers for the XML documents nodes.

When interface is exposed, it cannot be easily changed, because the external applications depend on it. It should be considered immutable, that's why the versioning of the XML namespaces is very important.

The URL or URN are used for the XML namespaces. Feel free to use one of these standards. See the “Namespaces in XML 1.0 (Second Edition)”http://www.w3.org/TR/xml-names/ for more information.
URL format is widespread and users are familiar with it. There are several confusions about using URL as an XML namespace:

  • The URLs are usually used as the internet site addresses. But a URL in an XML namespace works as a global unique identifier, not as an address.
  • Note the reverse names order in typical URLs, for example, not the http://com.company.domain but http://domain.company.com. If you don’t want to use XML namespaces that looks like the web addresses, use the XML namespaces in the non-reversible, sortable order. 
  • URLs are case-sensitive (Yes, they are!) You can use the upper case letters in XML namespaces, but make sure you are consistent with it.
  • Consider two formats for versions. One option is to use the Semantic Versioning, like "0.1.0". The second option is to use a creation date, like "2012-09-15". Here I use the date format.

Additional Rules for the XML Namespaces

  • Use the same XML namespace for all schemas in single project. Schemas are differentiated by the root node names. Do not place the root node name inside the XML namespace.
  • Use the project creating date for the first version of all schemas inside project.
  • Use the current date for the second and next versions.
  • Create the new version only if the old one is published to production (test) environment. Do not create new versions inside internal development cycles.
  • Use the YYYY-MM-DD date format to make the “sortable” names. Do not use MM/DD/YY format.
  • If schemas are autogenerated, manually change of the XML namespaces would be very suspicious idea. Think twice!

Example: for the MyCompany.MyDomain.MySolution solution and the MyProject project the XML namespace should be like this:

  • http://MyCompane.MyDomain,MySolution.MyProject/2009-05-15

BizTalk Artifact Names

Are the shorter names always better?

Usually we have two choices: using logical names or using full names.

 When we work with names in global lists, where artifacts of many BizTalk applications are mixed, we have to use full names. In those global lists the leftmost part of the name, which is the namespace (the BizTalkApplication name), helps in grouping and fast searching of artifacts. But, if, for example, a global list has a separate column with a BizTalkApplication name, we do not have to use a full name because we can use the BizTalkApplication column for the fast searching and grouping. But using logical names in the global namespace force us to use unique names, which is e a problem with long name list.

Global lists are used in:

  • Development tools: Visual Studio windows;
  • Source code system: TFS, Subversion, etc.;
  • BizTalk Administrator Console:
    • Static Application artifacts
    • Run-time BizTalk Group queries
  • Logs: Event logs; Debug/Trace output; Performance counters
  • Assembly lists

Orchestrations, Schemas, Maps, Pipelines

Lists with these artifacts are always provided with a BizTalk application name. Visibility of these artifacts is limited the application boundary. We don’t need to use composite names. Use logical names for these artifacts.

Tip: If you see the same word in several places of a full name, consider this as a bad signal. Try to rethink the name design rules. I repeat this rule here again, because exactly in the full names of orchestrations, schemas and pipelines we can frequently see the repetitive words.

Considerations
  • If it is possible, do not change the schema names in the map name. If the map name is excessive long, cut the schema names, but use the same cut rule for all map names.
  • Using lower-case _to_ and _and_ infixes in maps helps us visually separate logical parts of a long name. Lower case stresses these infixes are not the part of logical names, but kind of operators between these logical parts.
  • Create local naming conventions for artifacts if there is a big enough quantity of artifacts.   
Controversial
  • Do we have to use prefixes or suffixes to separate the artifact type as “_orchestration” or “_map” or “_schema” or “_pipeline”? No. Those artifacts are always placed in different lists so use logical names without these additions.
  • Do we have to use prefixes or suffixes to mark the pipeline type as “Send” or “Receive”? Maybe Not, maybe Yes. Those pipelines are always placed in different lists in Admin Console, but usually they are placed in the same Visual Studio project. So, be reasonable.

Ports

Ports are the primary artifacts of the BizTalk solution. Visibility of send and receive ports, and receive locations (sic!) is limited by the BizTalk Group boundary, not the application boundaries. BizTalk forces us to use unique names for ports across all applications, so we have to use full names.

  • Do we have to use prefixes or suffixes to mark the Send and Receive ports, like "MySomethingSendPort"? No. Those ports are placed in different lists. If they are placed in the same list (like in the Suspended list), they are always qualified with type. BizTalk does not force us to use different name for Send and Receive ports. Moreover we can use the same name for the Send Port and for the Receive Port. It is permitted and does not create a name conflict.
  • Do we have to use Transport type as part of Send port name to make a name rule consistent with a rule for Receive Location? It is up to you. But take in account the Backup Transport of the Send Port.
  • Do we have to use message type in the port names, like .PatientRecord? Maybe. Single port can work with several message types. But for sure a message type can be used as a part of the port name.

BizTalk artifact and project file placement

Consider this chapter as “out-of-scope”. The artifact and files placement is a separate and wealthy topic. Here only main considerations are. See this document for examples.

  • Folder structure copycats the namespace. 
    Example: the MyCompany.MyDomain.MySolution.MyProject project is placed in the c:\Solutions\MyCompany\MyDomain\MySolution\ MyCompany.MyDomain.MySolution.MyProject folder.
  • If some artifacts are referenced from other projects, extract these artifacts into a separate shared project. Shared artifacts should be in separate shared projects!
  • Place artifacts into different projects if these artifacts have different refactoring life cycle. For example, if the EDI standard schemas are never changed, place them into a separate project. The maps are changed more frequently than schemas so we place schemas and maps into separate projects.
  • If a project is simple, place all artifacts just in one project. Nothing is wrong with it.
  • Don’t place the technology-specific schemas and maps (used only inside one project) away from the orchestration they used for. For example, for the SQL port we auto generate the (technology) schemas and then create a map to transform original schema to this (technology) schema. Place these schemas and map together with orchestration, not into the separate Schemas/Maps projects. 
  • If number of artifacts of a project is big, create the project subfolders and group artifacts into these folders. Visual Studio modifies the .NET namespaces accordingly, adding the subfolder as a part of namespace and this is great.

Solution subfolders

For the BizTalk projects with different artifacts you can add the Schemas, Orchestrations, and Maps solution folders to group projects by artifact type.

Out of scope

Several BizTalk artifacts are out of scope this naming convention:

  • BRE artifacts: Rule sets, Vocabularies, etc.
  • BAM artifacts: Activities, Views, BAM Definitions, Tracking Profiles
  • Parties, Role links, Send Port Groups
  • Itineraries from the ESB Toolkit.

References

See Also

Another important place to find a huge amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.