Assembly/DLL Naming Guidelines


I have not seen this be much of debate externally, but it
has been pretty hotly debated internally.  We just closed down on this
guideline… As always, your comments are welcome:


 


 


style="FONT-SIZE: 18pt">2.3.4 Assembly/DLL Naming Guidelines style="FONT-SIZE: 13.5pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> 


style="COLOR: black; mso-bidi-font-size: 10.0pt">An assembly  is the
unit of deployment and security for managed code projects.  Typically
an assembly contains managed code and maps 1-1 with a DLL, although style="mso-bidi-font-size: 10.0pt">assemblies can span one or more files and may
contain managed and unmanaged code as well as non-code files such as
resources.  style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> 


style="COLOR: black; mso-bidi-font-size: 10.0pt">Assemblies are self-describing
units of compiled managed code. When assemblies are in more than one file, there
is one file that contains the entry point and describes the other files in the
assembly.  A Module is compiled code that can be added to an
assembly but has no assembly or version information of its own. style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> 


style="mso-bidi-font-size: 10.0pt">You should choose names for your assemblies
that suggest large chunks of functionality such as System.Data.  Assembly
and DLL names don’t correspond to namespace names but it is reasonable to follow
your namespace href="#_msocom_1#_msocom_1"> style="FONT-SIZE: 8pt; COLOR: blue; mso-bidi-font-size: 12.0pt">[mcm1] style="mso-bookmark: _msoanchor_1"> style="mso-bookmark: _msoanchor_1"> style="FONT-SIZE: 8pt; mso-bidi-font-size: 12.0pt">  style="mso-bookmark: _msoanchor_1"> style="mso-bidi-font-size: 10.0pt">conventions style="mso-bookmark: _msoanchor_1"> style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> href="outbind://424/#_msocom_1"> style="FONT-SIZE: 8pt; COLOR: blue; FONT-FAMILY: Verdana; mso-bidi-font-size: 12.0pt">[mcm1] style="mso-bidi-font-size: 10.0pt"> when naming assemblies. style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> 


style="COLOR: green; FONT-FAMILY: 'Wingdings 2'; mso-bidi-font-size: 10.0pt">? style="FONT-SIZE: 7pt; COLOR: green; FONT-FAMILY: 'Times New Roman'">     
Consider naming managed DLLs
according to the following pattern:
style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-FAMILY: 'Courier New'; mso-bidi-font-size: 10.0pt"><Company>.<Component>.dll style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="mso-bidi-font-size: 10.0pt">Where <Component> contains one or more
dot-separated clauses.  For example, style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-FAMILY: 'Courier New'; mso-bidi-font-size: 10.0pt">Microsoft.VisualBasic.dll
Microsoft.VisualBasic.Vsa.dll
Microsoft.Directx.dll
System.Web.dll
System.Web.Services.dll
Fabrikam.Security.dll
Litware.Controls.dll 


style="BACKGROUND: #f3f3f3; mso-bidi-font-size: 10.0pt">FxCop rule coming.


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'"> 


style="mso-bidi-font-size: 10.0pt">Please keep in mind that namespaces are
distinct from DLL names.  Namespaces represent logical groupings for
developers whereas DLLs represent packaging and deployment boundaries. 
DLLs can contain multiple namespaces for product factoring and other reasons,
and namespaces can span multiple DLLs.  Since namespace factoring is
different than assembly factoring, you should design them
independently. style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">



style="FONT-SIZE: 8pt; FONT-FAMILY: 'Times New Roman'; mso-bidi-font-size: 12.0pt">  href="#_msoanchor_1#_msoanchor_1"> style="COLOR: blue">[mcm1] style="mso-bidi-font-size: 10.0pt">Make this a hyperlink to 2.3
Namespaces style="FONT-SIZE: 12pt; FONT-FAMILY: 'Times New Roman'">


style="FONT-SIZE: 8pt; FONT-FAMILY: 'Times New Roman'; mso-bidi-font-size: 12.0pt"> 

Comments (6)

  1. Nicko Cadell says:

    As the number of frameworks increase is there a consensus on a naming convention that identities the framework that the assembly targets. Currently we are building different assemblies for .net 1.0, .net 1.1, .net compact framework 1.0, sscli 1.0 and mono. We build from the same source with very minor conditional compilation for each framework.

    So how should we identify the assemblies built for each framework?

  2. Michael Murray says:

    Hi Nicko – While your dependencies will of course be bound to a specific version of the framework, you should choose different names only if you’re trying to aid developers in adding references to your assembly. If they typically have to choose from the different flavors above on the same machine, maybe choosing a name that calls out the flavor (neoworks.feature.sscli.dll, neoworks.feature.mono.dll) would help. $0.05CDN – Michael

  3. Nicko Cadell says:

    Michael, thanks for the reply. Currently we are using the following assembly names:
    log4net-net-1.0.dll
    log4net-net-1.1.dll
    log4net-netcf-1.0.dll
    log4net-mono-0.23.dll
    log4net-sscli-1.0.dll
    As there are no assembly level identifier that can be used to identify which framework the assembly is built for we are left with no alternative but to use the assembly name itself. This does cause some confusion for users because they assume that the number in the assembly name is the version of our assembly rather than the version of the target framework.

    So far I have seen no public discussion of this issue, which I see as becoming more important with the release of the Compact Framework.

  4. Michael Murray says:

    Hey – Sorry for the delay :). Perhaps your convention above with a small tweak would help?

    log4net-[version]-fw-[version].dll

    or something like that, and document the convention. Not the nicest, but…

    I’ll keep your example in mind thoug, it is a good one – thanks, m.

  5. Juan M. García says:

    I think that versión will be fine with private assemblies, but If you use this assemblies in the GAC … I think you must use the same name and delegate in GAC the assembly versions’ organization.

    I have a question about what to write down in <Component>. Layers?? Structural components?? Architectural elements?? Both??