Version 3.0 2011-12-26
Version 2.2, 2011-01-05
Version 2.1, 2009-08-09
Here is a BizTalk Orchestration Naming Convention
How to use this
document
To accommodate this document for the
specific solution create the real names in Appendix (see Instructions in Appendix)
or create a separate Name Repository.
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.
Names should be short, sortable,
readable, discoverable, and self-describing.
The main test for constructing name
rule should be in questions:
·
Where I can see a name?
·
How
easily I can use the name in these places?
“Use” means to read, to find, and to understand it
without errors. Frequently we use names in lists. Think about these lists as
namespaces in programming languages.
Short names:
·
Shorter name is better.
·
Use
abbreviations only in restricted cases. See article the “Abbreviations”.
·
Use
prefixes and suffixes only to differentiate names.
·
If
you see one word in several places of a full name, consider this a bad signal.
Try to change the name design.
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 upper and lower cases. For instance, the
XML namespaces (URL) should be 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:
·
The
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 should be in the Company.Domain.Solution.Project project and
in the Company.Domain.Solution.Project.dll assembly.
Self-described
(Semantics):
·
Create
name from the “business point of view” not from the “developer point of view”,
especially if name is exposed externally.
·
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 comment about where do use
it and where do not use].
Artifacts can have the full names or short names.
Full names are compounded from short
names separated by separating symbols [.-_/].
For example, Patient.Record or MyCompany.MyDomain.MySolution.Schemas. Full
names express logical hierarchical grouping.
Short names are
names usually without such separating symbols. If we need to add additional
logical grouping it is possible to use several words with separating symbols.
For example, DepartamentA.PatientRecord.
Composite names
are short names composed from several words in Pascal format, for example MySoulution
or PatientRecord. Composite names can be used for any part of a full 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.
<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.
<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.
·
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:
o
Static Application artifacts
o
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.
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.
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
1.
“Naming guidelines
for the .NET Framework types” in MSDN
2.
“Naming Convention”
in Wikipedia
3.
“Abbreviations” in MSDN
4.
“Readability” in
Wikipedia
5.
“Capitalization
Styles” in MSDN
6.
“Assembly Versioning”
in MSDN
7.
“Namespaces in XML
1.0”
8.
URN in Wikipedia
9.
URL in Wikipedia
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.
1. Copy
Appendix to a new text document.
2.
After creating a new artifact copy its name to
this document below rule for a respective artifact.