BizTalk Application Naming Conventions

BizTalk Application Naming Conventions

[last update: 2013-08-24]

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 which are the hierarchical groups. Think about these lists as namespaces in programming languages.

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


  • 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 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.

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> =: 

<CompositeName> =:

<LogicalName> :=

<Company> =:
<Domain>    =:

<Solution>    =: 

<Namespace>         =:
<SolutionNamespace>         =:

Visual Studio artifacts

<SolutionFullName>        =:
<BizTalkApplication>           =: 

<Project> =:
<ProjectNamespace> =:
<Assembly> =:
<DotNetNamespace> =:


<SolutionsRootFolder> =: c:\Solutions

<SolutionFolder>      =:
\<Company>\<Domain>\ Solution>

<ProjectFolder>       =:


<OrchestrationProject>       =:

<SchemaProject>    =:

<MapProject>          =:

<PipelineProject>     =:

<PipelineComponentProject>         =:


<SchemaTargetNamespace> =:

<Version> =:
         <date> [in YYYY-MM-DD format]

BizTalk Artifacts

<Orchestration>       =:

<Schema> =:
         <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> =:

<ReceivePort>      =:

<ReceiveLocation>   =:

<SendPort>   =:


<SchemaNamespace>   =:
<MapNamespace>   =:
<OrchestrationNamespace>   =:


<MessageType>   =:

<MessageLogicalName> =:


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.


  • Do we have to group different artifact types into the different projects? It depends. Make this grouping, if you have a good reason.
  • Naming convention of the BizTalk map project depends on your preference. It could be Transforms as proposed by Scott Colestock and used in the BizTalk Deployment Framework (e.g. '<project.Transforms>') and as well Maps as used by the BizTalk Solution Factory (e.g. '<project.Maps').
  • Naming convention of .Net (ComponentProject) project could be the Classes,  or Components, or BusinessComponents
  • 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) 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. 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 but 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.
  • Consider to use two formats for versions. One format is a format used for the .NET assemblies, like "". The second format uses a creation date, like "2012-09-15". 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 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.

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.

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 are always provided with a BizTalk application name. 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.


  • 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 for a long name.
  • Create local naming conventions for artifacts if there are a big enough quantity of artifacts.   


  • 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 using logical names is the optimal way.
  • Do we have to use prefixes or suffixes to mark the pipeline type as “Send” or “Receive”? Possible No. Those pipelines are always placed in different lists. 


Ports are the primary artifacts of the BizTalk solution. 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? 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.
  • 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 inside a 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 mirrors the namespace. 
    Example: the MyCompany.MyDomain.MySolution.MyProject project is placed in the c:\Solutions\MyCompany\MyDomain\MySolution\ MyCompany.MyDomain.MySolution.MyProject folder.
  • If we want to use some files for references from other projects, place these files into a separate project.
  • Place artifacts to 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 and we could place schemas and maps into the separate projects.
  • If the project is simple, place all artifacts 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 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 separate Schemas/Maps projects. If number of schemas and maps is big, create the project subfolders and group schemas in maps into these folders.

Solution subfolders

For the BizTalk projects with different artifacts you can add the Schemas, Orchestrations, and Maps solution folders to group artifacts by 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
  • Itineraries from the ESB Toolkit.


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.

Leave a Comment
  • Please add 8 and 4 and type the answer here:
  • Post
Wiki - Revision Comment List(Revision Comment)
  • Steef-Jan Wiggers edited Revision 20. Comment: Added See Also

  • Maheshkumar S Tiwari edited Revision 46. Comment: minor edit

  • Pantelis44999 edited Revision 4. Comment: Added Table of Contents

Page 1 of 1 (3 items)
Wikis - Comment List
Posting comments is temporarily disabled until 10:00am PST on Saturday, December 14th. Thank you for your patience.
  • Steef-Jan Wiggers edited Revision 20. Comment: Added See Also

  • Maheshkumar S Tiwari edited Revision 46. Comment: minor edit

  • Pantelis44999 edited Revision 4. Comment: Added Table of Contents

  • Educative Article....

Page 1 of 1 (4 items)