BizTalk: Naming Conventions for BizTalk Solutions

I'm keeping the last, up-to-date version of the Naming Conventions on the Microsoft TechNet site

Version 3.1 2012-05-14
Version 3.0 2011-12-26       [Added a Namespace term, it simplifies everything. Extracted the Orchestration conventions into a separate document.]
Version 2.2, 2011-01-05
Version 2.1, 2009-08-09
Here is the BizTalk Orchestration Naming Conventions 
--------------------------------------------------------------------

General rules
The “Naming guidelines for the .NET Framework types” are used as a basis of this document. Also see the “Naming Convention” in Wikipedia.
When you are constructing a name ask the questions:
  • Where can we see the name?
  • How easily can we read, find, and understand the name?

Frequently we use names in the lists of the artifacts, for example in the BizTalk Administration Console or in the Visual Studio project. Find all such lists and you can start to design the good naming conventions. If these lists are not in the requirements, it is not possible to create the good naming conventions.
Names should be sortable, readable, discoverable, and self-describable.
Sortable:
  • Create “sortable” name. Use more generic/important part of the name in the leftmost position. For example, use the "Folder_20090515" not the "Folder_05_15_2009".
Readable:
See http://en.wikipedia.org/wiki/Typography
  • Use the name case compatible with the well-known practices in programming languages/protocols with respect to the upper and lower cases. For instance, the XML namespaces (URL) might be in lower case format, but other names  might  be in the Pascal format. See the “Capitalization Styles” article.
    If the name with specific case is widely used in the company, don’t force to change it to the Pascal format.
  • Decorate infixes, prefixes or suffixes with lower case and with an underscore symbol. For example: TicketBatch_type, Source1_and_Source2_to_Target, msg_MyRequest.
  • Use abbreviations only in restricted cases. See article the “Abbreviations”.
  • If you see one word in several places of a full name, consider this a bad signal. Try to change the name design.
 Discoverable: 
  • A name should be discoverable. That means we easily should understand a purpose of artifact by its name [and by the place of name]. Names should link artifacts. Say, the schemas with XML namespace the http://domain.company.com/solution/project/2009-05-14 definitely cab be in the Company.Domain.Solution.Project project and in the Company.Domain.Solution.Project.dll assembly.
Self-describable (Semantics):
  • Create name from the “business point of view” not from the “developer point of view”, especially if name is exposed externally, to other 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 the frequently used terms into a dictionary / a name repository [with comment about where do use it and where do not use].
Full, Short, and Composite names:
The names can be compounded from a single Word or from the several Words separated by the Separating symbols [.-_/]. 
The Word is a combination of the letters and numbers and the Word is started from a letter. Word usually is strarted from the capital letter.
The names can be the full names or the short names.
A Full name is compounded from a namespace and a short name separated by separating symbols [.-_/].
For example, Patient.Record or MyCompany.MyDomain.MySolution.Schemas. Full name expresses the logical hierarchical grouping.
A Short name is a part of the Full name without the namespace. Usually the Short name is considered in a context of its namespace. A Short name can be compounded from several Words with of without the separating symbols. The separation symbols add the local hierarchy.
For example, Schemas, Schemas.Generic.
A Composite name is the name composed from several words in the Pascal format. For example MySoulution or PatientRecord. Composite name can be used for any name. Naming conventions for VS artifacts
<Namespace>         =:
    <Company>.<Domain>.<Solution>
Note: Namespace is a main part of the full names. Namespace is a hierarchical name. It shows the hierarchy of artifacts. Leftmost parts are more important than rightmost parts. Rightmost parts are “belongs” to the leftmost part like Details to Master relationship (1 to M relation).
Example: MyCompany.MyDomain.MySolution
<VSSolutionFullName>        =:
<BizTalkApplication>           =:
    <Namespace>
Note: A Solution term is used in the Visual Studio meaning, it is a name of the solution we see in the Solution Explorer window in the Visual Studio. Sometimes Solution and Project terms can be mixed but not in this document.

<VSProject> =:
<Assembly> =:
<DotNetNamespace> =:
    <Namespace>.<VSProjectShortName>
Note:
  • 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.
  • Assembly is an “Assembly name” property and DotNetNamespace is a “Default namespace” property in the project Properties window.
  • We should separate the .NET namespaces and the XML namespaces. They are different things and used in different places.
Folders
<SolutionsRootFolder> =:
    c:\Solutions
<SolutionFolder>      =:
    <SolutionsRootFolder>\<Namespace>
<ProjectFolder>       =:
    <SolutionFolder>\<Project>
Note: Use the well-defined folder structure. This eliminates the errors and reduces deployment effort.
Example: the MyCompany.MyDomain.MySolution.MyProject project is placed in the c:\Solutions\MyCompany\MyDomain\MySolution\ MyCompany.MyDomain.MySolution.MyProject folder. Naming conventions for BizTalk projects
<OrchestrationProject>       =:
    <Namespace>.Orchestrations
<SchemaProject>    =:
    <Namespace>.Schemas
<MapProject>          =:
    <Namespace>.Maps
<PipelineProject>     =:
    <Namespace>.Pipelines
<PipelineComponentProject>         =:
    <Namespace>.PipelineComponents
Controversial:
Do we have to group different artifact types to different project types? It depends. Make this separation, if you have good reasons.
Example:
We generate artifacts using the WCF Consume Wizard. It creates several schemas and an orchestration. Do we have to move schemas to the Schema project and 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 important part of the XML documents which expose the data to the external applications. The XML namespaces should follow the industry standards and the corporate standards. XML namespaces work as global unique identifiers for nodes of the XML documents.
When interface is exposed, it cannot be easily changed. It should be considered immutable, that's why versioning for XML namespaces is very important.
The URL or URN is used for 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.
Note: URL format is widespread and users are more familiar with it. There are several confusing things about using URL as an XML namespace:
  • The URLs are usually used as addresses in internet. URL in XML namespace works mostly 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, consider to use the XML namespaces in the generic, nonreversible, 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.

<TargetNamespace> =:
    http://<Domain>.<Company>.com/<SolutionShortName>/<ProjectShortName>/<Version>
<Version> =:
    <date> [in YYYY-MM-DD format]
Note: Consider to use two version formats. One format is a format used for the .NET assemblies, like 1.0.0.1. The second version format uses a creation date. Use the first format only if you can implement strict versioning rules, if you create/have some version approval procedure. Here I use the date format. Additional Rules for XML namespaces
  • Use the same XML namespace for all schemas in the whole project, maybe in the whole solution. 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.

Example: for the MyCompany.MyDomain.MySolution solution and the MyProject project the XML namespace should be the http://mydomain.mycompany.com/mysolution/myproject/2009-05-15 Naming Conventions for BizTalk Artifacts Considerations
Shorter names are better. Usually we have two choices: using short 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. If global list has a separate column with BizTalkApplication name, we do not have to use a full name. Short name is enough and more convenient.
Global lists are in:
  • Development tools: Visual Studio windows;
  • Source code system: TFS or Subversion or any another;
  • 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 always have with BizTalk application name. We don’t need to use composite names. Use simple 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.
<Orchestration>       =:
    <ShortName>
<Schema> =:
    <ShortName>
    <ShortName>_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> =:
    <ShortName>
Note:
  • 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 helps to separate visually logical parts of the long name.
  • Create local naming conventions for artifacts if there are a big enough number of artifacts. Do not force strict rules if it is not necessary. 

Controversial:
  • Do we have to use prefixes or suffixes to mark the artifact type as “_orchestration” or “_map” or “_schema” or “_pipeline”? No. Those artifacts are always placed in different lists.
  • De we have to use prefixes or suffixes to mark the pipeline type as “Send” or “Receive”? No. Those pipelines are always placed in different lists.
Ports
Ports are the primary artifacts of the BizTalk solution. BizTalk forces us to use unique names for ports, so we have to use full names.
<Port>      =:
    <Namespace>.<PortShortName>
Controversial:
  • De we have to use prefixes or suffixes to mark the Send and Receive ports? 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.

<ReceiveLocation>   =:
    <Port>.<TransportType>
Note:  Several Receive Locations could belong to one receive port and the main differentiator is a Transport type of the Receive Location.
Example:
ReceivePort::GLD.Samples.Itineraries.Test :
                ReceiveLocation:: GLD.Samples.Itineraries.Test.File        ReceiveLocation:: GLD.Samples.Itineraries.Test.Ftp
Controversial:
  • De 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? No. Single port can work with several message types. But for sure a message type can be used inside a port name.
BizTalk artifact and project placement
Consider this chapter as “out-of-scope”. The files placement is a separate and wealthy topic. Here are only main considerations.
  • If the project is simple, place all artifacts in one project. Nothing is wrong with it.
  • If we want to use some files for references from other projects, place these files in separate project.
  • Place artifacts to different projects if these artifacts have different refactoring lifecycle. For example, if the EDI standard schemas are never changed, place them to a separate project. The maps are changed more frequently than schemas and we could place schemas and maps to the separate projects.
  • Don’t place the technology-specific schemas and maps (used only inside this project) away from the orchestration they used for. For example, for the SQL port we generate a (technology) schema and usually create a map to transform original schema to this (technology) schema. Place these schemas and map together with orchestration, not into the Schemas/Maps projects, but only number of schemas and maps is small.
Project subfolders
For the BizTalk project with different artifacts you can add the Schemas, Orchestrations, and Maps solution folders to group artifacts by type.
Group the project artifacts inside subfolders to keep artifact list short and logical. 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
  • Itineraries from the ESB Toolkit.

See also Appendix
Syntax Generic Naming conventions:
<Word> =: 
    [A-Z][a-z1-0]*
<CompositeName> =:
    <Word><Word>[<Word>]
<ShortName> :=
    <Word>[.<Word>]
    <CompositeName>
<{Any}ShortName> =: 
    <ShortName>
        - [replace {Any} with any term. For example, term Solution creates a <SolutionShortName> term]
<Company> =:
<Domain>  =:
<Solution>    =: 
    <ShortName>
<Namespace>         =:
    <Company>.<Domain>.<Solution> Naming conventions for VS artifacts:
<VSSolutionFullName>        =:
<BizTalkApplication>           =: 
    <Namespace>
<VSProject> =:
<Assembly> =:
<DotNetNamespace> =:
    <Namespace>.<VSProjectShortName>
 
<SolutionsRootFolder> =:
     c:\Solutions
<SolutionFolder>      =:
    <SolutionsRootFolder>\<Namespace>
<ProjectFolder>       =:
    <SolutionFolder>\<Project>
 
<OrchestrationProject>       =:
    <Namespace>.Orchestrations
<SchemaProject>    =:
    <Namespace>.Schemas
<MapProject>          =:
    <Namespace>.Maps
<PipelineProject>     =:
    <Namespace>.Pipelines
<PipelineComponentProject>         =:
    <Namespace>.PipelineComponents
 
<TargetNamespace> =:
    http://<Domain>.<Company>.com/<SolutionShortName>/<ProjectShortName>/<Version>
<Version> =:
    <date> [in YYYY-MM-DD format] Naming Conventions for BizTalk Artifacts:
<Orchestration>       =:
    <ShortName>
<Schema> =:
    <ShortName>
    <ShortName>_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> =:
    <ShortName>
<Port>      =:
    <Namespace>.<PortShortName>
<ReceiveLocation>   =:
    <Port>.<TransportType>
Instructions
Keep the names of the artifacts in a list, a list per solution. Keep them in one list; it forces developers to use naming convention, because inconsistencies in the names are visible on the development stage.
  • Copy Appendix to a new text document.
  • After creating a new artifact copy its name to this document below rule for a respective artifact.

 
Print | posted on Friday, July 31, 2009 10:44 AM

Feedback

# re: BizTalk: Naming convention for the BizTalk solutions

left by Monish Nagisetty at 1/5/2010 1:40 PM Gravatar
Under 7.4 you mention not to "repeat the type of shape icon by word". I would think that repeating it would be helpful in troubleshotting orchestration exceptions. For example:

Shape name: SendPO
ShapeId: 72c8affc-f9c9-4edf-9baa-68c455f79397
versus
Shape name: PO
ShapeId: 72c8affc-f9c9-4edf-9baa-68c455f79397

What are your thoughts?

# re: BizTalk: Naming convention for the BizTalk solutions

left by Leonid Ganeline at 1/5/2010 2:28 PM Gravatar
Hi Monish,
Thank you for asking!
It depends how frequently you use one or other feature.
In my experience it is much more frequently to screen the picture of the Orchestration and go through the message flow then come through the debugging messages. The clean readable shape names are more important to me. But you easily could hit another situation whit different priorities. Everything is up to you and up to context.

# re: BizTalk: Naming convention for the BizTalk solutions

left by Michael Høtoft at 7/5/2010 4:30 AM Gravatar
Or go with Scott suggestions which are almost a defacto standard ;)

http://www.traceofthought.net/misc/BizTalk%20Naming%20Conventions.htm

# re: BizTalk: Naming Convention for BizTalk Solutions

left by immigration expert canada at 2/22/2012 4:25 AM Gravatar
The bright lucid compensation epithet are more significant to me. Except you with no trouble could rage an additional loci whit dissimilar precedence. All is upbeat to you and up to condition.

# re: BizTalk: Naming Convention for BizTalk Solutions

left by Leonid Ganeline at 2/22/2012 8:30 AM Gravatar
Hi Michael,
I used Scott Colestoc convention previously. The artifacts names follow the same rules with simplification in several parts.
But convention for the Orchestration is completely redesigned. For each rule I included the reasons why I've done this. So, if you have thoughts about reasons and fresh ideas you are more then welcome to change.
Short example:
Rule for the Loop shape from old convention:
Loop_<ExitCondition>
New convention: no rule for the Loop shape. Because it gives us nothing in terms of readability.
Related Generic new rules:
* Use spaces in shape names [not '_'], names here are just descriptions.
* Do not repeat shape type as prefixes. We also have icon for this purpose. Name is also too short.

Etc.

# re: BizTalk: Naming Conventions for BizTalk Solutions

left by Tord Glad Nordahl at 8/8/2012 1:02 AM Gravatar
Love this post Leonid! I've missed a blog post like this, should definatly be a TechNet Wiki article as well!
Post A Comment
Title:
Name:
Email:
Comment:
Verification: